Sessions

The six words

run · import · commit · push · resume · merge cover daily life. The rest is there when you need it.

agit setup — wire everything once

agit setup                          # everything, every runtime
agit setup --runtime codex          # just one
agit setup --hooks                  # only the turn-end settlement hook

Installs: turn hooks (Claude Code), the agit skill/instruction block, MCP registration, and an AGENTS.md section in the current project. All idempotent. Without it, nothing breaks — you just settle turns by hand.

agit import — adopt a running session

agit import                         # no id: list this repo's sessions to adopt
agit import 3bac37d7 -n photo -b exp

Import writes a few-hundred-byte link into the store (the transcript is never copied), claims the session onto the branch you name, and settles the turns so far — adoption is itself a cut point.

The name is required. An auto-chosen name would silently decide which lineage this memory lands in, so a missing name is an error — and the suggestion in the error message must be retyped by you to take effect.

agit commit — settle turns

agit commit                          # everything since last settlement
agit commit --milestone "phase" --tag ms-1 --code

Per-turn settlement: new content since the last settled byte becomes one turn commit per user turn. The commit message is the first 72 chars of the prompt. Milestones mark phases; --code also commits the code repo and cross-links both.

agit push / pull — publish and sync

agit push photo              # secret-scan first, then publish
agit pull                    # fetch + fast-forward only

Push scans for secrets first — these bytes are leaving your machine for the first time. A hit stops the push; it’s not a warn-and-continue.

The server scans on publication, not on every push. A push to a public agent is scanned again server-side, and that gate has no override switch — inline agit:allow-secret and the local allowlist file are client-side only. A push to a private agent is not scanned server-side: nothing has been handed to a third party yet, and a false positive there would wedge your own work with no way out. So on a private agent the client scan is the only gate there is — bypass it and the secret goes into history unchecked.

That does not make it a permanently private problem. Published history is immutable (see below), so a secret in a settled turn stays in the history, and the day you flip that agent to public the whole repository is scanned — a hit blocks the switch, not just the next push. Opening a PR into a public agent is scanned the same way. Rotate the credential when it happens; there is no amend that takes it back.

Visibility is decided at first publish only: default public, --private for private. Later pushes never touch it; change it on the site.

There is no --force. Published history is immutable.

Pull fetches and fast-forwards only. A real divergence (both sides moved) is not an error — you get two exits: agit merge origin/exp --into exp, or keep both lines with agit fork origin/exp -b exp-remote --resume.

agit run — take anything and run it

agit run alice/photo           # fetch → arbitrate → materialize → launch
agit run alice/photo@exp#12    # from turn 12 instead of the tip

One command does four things, and prints each arbitration decision (continuing on a writable head vs. forking; native resume vs. materialized). Running someone else’s agent always forks — exp-run-1 — you’ll never splat onto their line.

agit status — who am I, where am I

Identity, current session, settlement state, sync state vs. hub. The first thing to run when a terminal feels unfamiliar.

agit doctor — integrity

VIEW self-consistency (references reachable, merge markers paired), log still append-only (baseline hash check), per-runtime capability table. --check-backend adds the hub round-trip.