atgc #

Current release: v1.0.0

ATproto Git Client.

The project page is atgc.codes.

Features #

atgc is intended for CLI workflows against Tangled.

• Open a pull from a pushed branch, or from a fork
• Upload local images and mp4 video in pull, issue and comment bodies
• Log into ATproto via scoped OAuth (no app passwords!)
• Use multiple simultaneous ATProto accounts
• Set up Tangled-compatible .git/config for userinfo and SSH
• Install shell completion
• File issues, feature requests and questions from the terminal

Agentic support #

atgc is designed to support agentic workflows that run on high parallelism on git worktrees. Current features include:

• Built-in briefing to explain usage to agents
• Per-worktree credential switching
• Per-agent credentials via did.bot
• Maintain an audit log of operations
• Agents can file their own issues and board reports

A Claude Code plugin tells each session what Tangled is and how to sign in to atgc. Its marketplace is this repository:

/plugin marketplace add https://tangled.org/permadeath.com/atgc.git
/plugin install atgc@atgc

See plugin/README.md.

Install #

atgc is not on crates.io yet, see plan/publishing.md for more info.

# install remotely:
cargo install --locked --git https://tangled.org/permadeath.com/atgc

# or if already checked out:
cargo install --locked --path .

PLACEHOLDER-quickstart-vellichor

Commands #

Meta #

atgc about                 # info about atgc
atgc agent                 # working notes for AI agents (humans welcome)
atgc agent --json          # the same briefing plus the command tree
atgc help [command]        # the same pages as --help, as a verb

Account management #

Logging in #

atgc auth login <handle|did>    # log in via OAuth (adds an account, changes no other)
atgc auth status                # list the accounts and show the active one
atgc auth default <handle|did>  # choose the person's fallback account
atgc auth refresh               # refresh the acting account's access token
atgc auth token                 # print the acting account's access token
atgc auth logout [handle|did]   # log out of one account (--all for every account)

Push keys #

atgc key list [owner]  # registered SSH keys, and which is on this machine
atgc key add [key]     # publish a public key so knots accept its pushes
                       #   (an agent must name the key; people default to ~/.ssh)
atgc key create        # make one first, for an identity with no ~/.ssh
atgc key delete <key>  # withdraw one (by rkey, name, fingerprint or path)

Repository operations #

Repositories #

atgc repo clone <repo>     # clone a Tangled repo and set its git identity
atgc repo create [name]    # create a repo on a knot and declare it in your PDS
atgc repo fork <repo>      # fork a repo onto a knot, as your own (--clone to check it out)
atgc repo configure        # point this checkout at the current account, and hook it
atgc repo configure --hook-config  # ...declaring the hook in prek.toml / .pre-commit-config.yaml
atgc repo remote add <repo> [name]  # add a Tangled repo as a remote here, as clone would
atgc repo default-branch <branch>  # point a repo's HEAD at a different branch, on the knot
atgc repo delete-branch <branch>   # delete a branch on the knot (irreversible)
atgc repo edit [repo]      # change its description, website, topics or spindle
atgc repo delete [repo]    # delete its records and git data (--yes, irreversible)
atgc repo list [owner]     # list an account's repos
atgc repo view [repo]      # what a repo is: identity, hosting, git state
atgc repo collaborators [repo]  # who the knot lets push: owner and collaborators
atgc browse [section]      # open the repo's Tangled page (e.g. browse pulls)
atgc browse --pr           # open the current branch's pull request
atgc browse --pr 23        # open a named one: number, rkey, at:// URI or URL
atgc search <query>        # full-text search (this repo, or --all for every one)

Pull requests #

atgc key create            # publish the key a knot reads for pushes
atgc pr create             # push the branch and open a pull from it
                           #   (--fork: push to your fork instead)
atgc pr resubmit <pull>    # add a version after the branch changes
atgc pr list               # list pulls for this repo (--state open|closed|merged|all)
atgc pr list --author <who> # this repo, narrowed to one account
atgc pr list --all         # your pulls across every repo (--author for someone else's)
atgc pr view [pull]        # view a pull (defaults to the current branch's)
atgc pr diff <pull>        # print a version's diff (--version N, --interdiff)
atgc pr checkout <pull>    # fetch a version's head and branch there
atgc pr checks [pull]      # CI workflows for a pull's latest version
atgc pr comment <pull>     # comment on a pull (--reply-to to thread)
atgc pr edit <pull>        # change its title, body or target branch (--target)
atgc pr merge <pull>       # land its latest version on the target branch
atgc pr close <pull>       # close or reopen it
atgc pr reopen <pull>

Issues #

atgc issue list                 # this repo's issues (--all, --author, --state)
atgc issue view <issue>         # one issue, from Tangled's index (falls back to the knot)
atgc issue create --title <t>   # open an issue (--body, or --body-file -)
atgc issue comment <issue>      # comment on an issue (--reply-to to thread)
atgc issue edit <issue>         # change its title or body
atgc issue close <issue>        # close or reopen it
atgc issue reopen <issue>

Releases #

atgc release list               # this repo's tags, and how many files each holds
atgc release view <tag>         # a tag's commit, message and attached files
atgc release download <tag> [<name>]  # fetch its files here (--force to replace)
atgc release upload <tag> <file>...   # attach files to a tag (--replace an existing name)
atgc release delete <tag> <name>      # remove a tag's file

CI runs #

atgc run list              # this repo's pipeline runs, newest first (--limit)
atgc run view <id>         # one run's workflows: status, timing, web page
atgc run watch <id>        # follow it until every workflow finishes (--timeout)
atgc run logs <id>         # stream its workflow logs (--workflow, --timeout)
atgc run trigger [<commit>]  # start a run, every workflow or --workflow (--input, --dry-run)
atgc run rerun <id>        # retry a run from its stored spec (--workflow, --dry-run)
atgc run cancel <id>       # cancel a run or named workflows (--dry-run)
atgc run approve <id>      # release a blocked run (--dry-run)

Strings #

atgc string list [<account>]    # an account's strings, newest first
atgc string view <string>       # one string's details and contents (--raw for contents only)
atgc string create <file>       # publish a file; `-` reads stdin and needs --filename
atgc string delete <string>     # delete one of your own (--dry-run to check first)

Checking and troubleshooting #

atgc doctor local          # is this machine, account and checkout set up to work?
atgc doctor remote         # are Tangled's services answering, and what are they running?

atgc logs oauth            # every OAuth operation (-f to follow, --json for jq)
atgc logs pds              # every write atgc has sent to a PDS
atgc logs knot             # every procedure atgc has sent to a knot
atgc logs git              # every git subprocess, and what it did to the checkout
atgc logs pds --failures --since 2h      # only what went wrong, recently
atgc logs oauth --incident               # the client_id and overlap comparison

atgc issue create --repo permadeath.com/atgc --title <t>  # file a bug in atgc's tracker
atgc report <kind>         # feature requests and questions, onto atgc's public board

Other #

atgc api <nsid>            # call an XRPC method directly, as you, and print the answer
atgc api com.atproto.repo.listRecords --host knot:knot1.tangled.sh -f repo=did:plc:… -f collection=org.tangled.track.ticket
atgc api org.tangled.search.query --host bobbin -f q='index lag'
atgc api org.tangled.review.submitPatch --host knot:knot1.tangled.sh --input patch.json --dry-run

atgc completion <shell>    # print a completion script (bash|zsh|fish|powershell|elvish)

Documentation #

docs/ holds only what you cannot get by running the tool or reading the code: eight short pages, listed in docs/index.md. The model is the one to read first: Tangled's shape is somebody else's system, and everything surprising about atgc follows from it. What atgc leaves on disk, and how to remove it, is in Uninstalling.

They are compiled into the API documentation too, so prose and generated reference are one build:

cargo docs

Development #

This codebase is intended for a single user, and is largely AI generated. It is provided with no guarantee of stability, versioning, or any other best practices.

Please contact @permadeath.com before sending in issues or pull requests.

See CONTRIBUTING.md for more details.