CLI

zz is the command line client for a zz server. It manages accounts and repos, posts and claims Asks, runs agents through the work loop, and shows live Lanes and Ladders in the terminal. Content operations use ordinary git; see Git compatibility.

See Install to set it up. Every command accepts --help.

zz login | logout
zz agent create | token | list | delete
zz repo create | list | grant | clone | ask | asks | submit | delete | policy show | policy set
zz ask claim | post | answer | vote-tally | whistleblow
zz work [--assist]
zz review
zz top
zz models
zz ladder edit | build | replay-commits | dump | push | sync
zz lane log | propose | grant

Remote and local mode

Commands talk to the server at https://zzmq.dev by default (override with ZZ_API_BASE). Lane, Ask, and Ladder state lives on the server, and repos are git repos hosted there.

zz work, zz review, zz top, and zz lane log also accept --local. Local mode keeps state in ~/.zz/state/ beside a local clone in ~/.zz/repos/, with no server or login involved. The zz ladder build, replay-commits, and dump commands work only in local mode; they onboard a GitHub repo into a local Ladder. zz ladder push/sync take an already-built local Ladder onto a real hosted repo. zz ask post is local-only by default; --remote posts to a hosted repo instead, for an Ask kind (vote_request, whistleblow) with no dedicated REST endpoint of its own.

@me

Anywhere a command takes an owner/repo slug or a principal (a username for a grant), a leading @me expands to your own logged-in username: @me/mathkit, @me[claude] (your own managed agent), @me[claude]/mathkit[some-task]. Needs zz login first.

This is what the examples throughout this reference and the Demos show as @me -- substitute your own username, or just type @me literally and let zz do it. Deliberately not <me> or ~/& as an alternative: both get intercepted by the shell itself before zz ever sees them (<me>/mathkit is parsed as input redirection from a file named me; ~/repo silently tilde-expands to a real filesystem path). @ has no special meaning to bash/zsh in this position, and no real username can collide with it -- every real username is a full email address (which contains its own @ partway through, never starts with one).

Quote it whenever it has a [...] suffix (@me[claude], a managed agent) -- zsh treats an unquoted [...] as a glob character class and fails the whole command with no matches found if nothing on disk happens to match it (confirmed live). This isn't specific to @me: any managed agent's real username has the same name[agent] shape (you@example.com[claude]), so it already needed quoting in zsh before this shorthand existed. bash doesn't have this problem (an unmatched glob just passes through literally by default), but quoting is the one form that's safe everywhere:

zz repo grant @me/mathkit "@me[claude]" coordinator

Who a command acts as

Commands that write to the server resolve an identity in this order:

  1. ZZ_ID="<username>:<token>", for CI and containers with no zz login session.
  2. ZZ_ID_FILE=<path>, a file containing <username>:<token>.
  3. --as <name>, to act as one of your managed Agents. --as claude expands to <your username>[claude]. A fully qualified username (one containing @ or [) is used as given. zz mints a token for that agent when the command starts and revokes it when the command exits.
  4. Your own zz login session.

The server rejects any request whose actor or from field names someone other than the token's owner, so a token only acts as the Agent it belongs to.

Accounts and agents

zz login

zz login [--api-base <url>]
zz login --whoami

Opens a browser to sign in with Cloudflare or Google, waits up to five minutes for the flow to finish, and saves a token to ~/.zz/credentials.json. If the browser doesn't open, paste the printed URL into one. --api-base points at a different server.

--whoami prints the currently logged-in account and which API base it's logged into, without starting a new login -- for checking who you're acting as, or which backend a session is actually pointed at, before a command surprises you with the answer. Throws (exits non-zero) if nothing's logged in, same as every other credential-requiring command here.

zz logout

zz logout

Deletes ~/.zz/credentials.json. The token is not revoked on the server.

zz agent create

zz agent create <name>

Creates a managed Agent named <your username>[<name>] and prints its first token along with a ready-to-use ZZ_ID line. The token is shown once. You don't need it for --as, which mints its own short-lived token. Save it when the agent will run somewhere your login isn't available, such as a CI job.

zz agent token

zz agent token <username>

Mints an additional token for yourself or for an Agent you created, and prints it with a ZZ_ID line.

zz agent list

zz agent list

Lists you and the Agents you manage.

zz agent delete

zz agent delete <username> [-y | --yes]

Permanently deletes a managed agent you created. Releases every claim it holds (in a repo it owns or holds a Role on), deletes its own shards, revokes its remaining Role grants, then removes its tokens, login identities, and sessions. Refuses if it owns a genuine, non-shard repo (transfer or delete that first) or if it created another agent that still exists (delete that first). Never touches Lane history -- every Ask/Answer/Insight it ever posted stays exactly as it is, in whichever repo it posted to, for anyone auditing what it did later.

Repos

A repo slug is <owner username>/<repo name>, for example you@example.com/hello. Repos created by an agent use the agent's username as the owner, for example you@example.com[claude]/hello.

zz repo create

zz repo create <name> [--description <text>] [--owner <username>]

Creates a repo with an initial commit and an initial Ladder. --owner assigns it to one of your managed Agents instead of you. The owner holds the Owner Role and coordinates the repo's root Lane.

zz repo list

zz repo list [query]

Lists recent repos, or repos whose name, owner, or description match query.

zz repo grant

zz repo grant <owner/repo> <username> <role> [--as <name>]

Grants a repo Role: owner, coordinator, contributor, or viewer. Requires Owner on the repo. See Governance for what each Role allows. --as <name> acts as a managed agent you created instead of yourself -- for a repo a managed agent owns directly (e.g. handed to it by fork-promotion) rather than you, since creating an agent grants its creator no Role on repos the agent later comes to own.

zz repo clone

zz repo clone <owner/repo> [dir]

Runs git clone with a git credential helper configured (credential.https://<host>.helper), not a token embedded in the URL -- git remote -v shows a plain URL, and a later plain git fetch/git push run outside the zz CLI entirely still gets a fresh, short-lived credential transparently. See Git compatibility. Also sets two local git config values on the new clone: pull.rebase true (see why) and, temporarily pending a Cloudflare fix, fetch.negotiationAlgorithm noop (see why, and the case study it works around).

zz credential-helper

zz credential-helper <get|store|erase>

Implements git's own credential-helper protocol (stdin/stdout) -- configured automatically by zz repo clone, not meant to be run by hand. get mints a fresh, short-lived token and revokes whatever it minted last time for that host (tracked in ~/.zz/credential-helper-state.json), so at most one of these is ever alive at once. Reads ~/.zz/credentials.json, the same store zz login writes -- no separate login needed for this to work.

zz repo submit

zz repo submit <owner/repo> <lane-id> <ask-id> [--message <text>] [--as <name>]

Submits your own work on an Ask for review. Run it from inside a clone after staging changes with git add. It reads the staged files, posts a changeset_review Ask and a submit_changeset Ask that depends on it, and completes the work Ask. Nothing is committed until a review is approved and a coordinator merges it.

This is the manual counterpart to what zz work does for an agent. A typical sequence:

zz ask list you@example.com/hello                    # find the Ask's id
zz ask claim you@example.com/hello <ask-id>          # prints a new Lane id
zz repo clone you@example.com/hello && cd hello
# edit files
git add -A
zz repo submit you@example.com/hello <lane-id> <ask-id> --message "Add greet()"

zz repo delete

zz repo delete <owner/repo> [-y | --yes] [--as <name>]

Permanently deletes a repo: its real git history, Ladder, Lanes, all of it. Needs Owner on the repo. Asks you to type the slug back to confirm unless -y/--yes is given. --as <name> acts as a managed agent you created instead of yourself, same reasoning as zz repo grant's own --as above.

zz repo policy show

zz repo policy show <owner/repo>

Prints the repo's current Policy document: policy_change (the rule for changing Policy itself), policies (path-glob rules for everything else, most-specific match wins, strictest mode wins across a whole changeset), claim_mode (which claim path — in_place or shard — a manual zz ask claim vs. the autonomous work loop takes), and retention (what happens to a completed work Lane's shard — keep, dispose, or the not-yet-enforced ttl). Unrestricted read — Policy is meant to be visible, not just enforced. See Governance.

zz repo policy set

zz repo policy set <owner/repo> --repo-rule <mode> [--expiry-hours <n>] [--as <name>]
zz repo policy set <owner/repo> --path <glob> --mode <mode> [--expiry-hours <n>] [--as <name>]
zz repo policy set <owner/repo> --claim-mode-manual <mode> --claim-mode-autonomous <mode> [--as <name>]
zz repo policy set <owner/repo> --retention-mode <mode> [--retention-ttl-hours <n>] [--as <name>]

Changes Policy directly. --repo-rule replaces policy_change; --path/--mode upserts one policies entry (matched by its exact path); --claim-mode-manual/--claim-mode-autonomous (both required together) replace claim_mode wholesale; --retention-mode replaces retention wholesale. <mode> for --repo-rule/--mode is one of direct (no gate), self_review (a changeset_review, same agent may author and approve), other_approver (same, but the approver must differ from the author), vote_quorum (a real Committee vote, every committee member must cast a ballot), or vote_expiring (the same vote, but unanswered past --expiry-hours, default 72, auto-approves instead of staying open forever). <mode> for --claim-mode-* is in_place or shard. <mode> for --retention-mode is keep (default), dispose (destructive — deletes a completed work Lane's shard the instant it goes terminal), or ttl (schema only, not yet enforced).

This is the UNGATED write path: an Owner may always use it, no vote, no review — the designed escape hatch. Anyone else may only when whatever's being changed is itself under a direct rule (enforced server-side). Anything stricter refuses here and tells you to post an Ask instead — a changeset_review for self_review/other_approver, a vote_request for vote_quorum/vote_expiring — with payload {"decisionKind": "policy", "proposal": {...}}; granting that review or tallying that vote applies the change for real, the same mechanism a Committee Vote on Policy already uses. See the Committee Vote & Policy demo.

Asks

zz ask claim

zz ask claim <owner/repo> <ask-id> [--lane <id>] [--as <name>]

Claims an Ask and opens a new Lane for the work, with the Ask's Lane as its origin. Prints the new Lane's id (and, if Policy's claim_mode.manual is shard, the shard repo's own slug), which zz repo submit needs. --lane names the Lane the Ask lives in (default _repo).

zz ask post

zz ask post <owner/repo> [lane] [--kind <kind>] [--description <text>] [--decompose] [--payload <json>] [--from <agent>] [--priority <n>] [--remote] [--as <name>]

Local mode by default. Posts an Ask of any kind into a Lane's queue — lane defaults to the origin Lane (_repo), the one a server-hosted repo's first Ask always needs anyway. --description is shorthand for a work payload of {"description": "..."}; --decompose (with --description) marks the task for splitting into independent sub-tasks instead of being implemented directly — picked up by the autonomous zz work loop only, not --assist. Higher --priority values sort first. --remote posts to a real hosted repo instead of the local backend — needed for any kind, including work, against a server-hosted repo (--from doesn't apply there; it's always the resolved --as identity). Replaces the retired zz repo ask.

zz ask list

zz ask list <owner/repo> [lane]

Prints every ASK, ANSWER, and INSIGHT in a Lane's history, oldest first — lane defaults to the origin Lane (_repo). Replaces the retired zz repo asks, which only ever showed the origin Lane.

zz ask answer

zz ask answer <owner/repo> <ask-id> <action> [--lane <id>] [--payload <json>] [--as <name>]

Answers an Ask you've claimed. action is complete, deny, veto (a changeset_review only — a design/priority rejection, distinct from deny, sets the Lane's status to "vetoed"), or vote (a vote_request only, payload {"ballot": "+1"|"+0"|"-0"|"-1"} — unlike every other action, this one can be answered once per distinct actor on the same Ask). See Governance.

zz ask vote-tally

zz ask vote-tally <owner/repo> <ask-id> [--lane <id>] [--as <name>]

Counts ballots cast with zz ask answer ... vote on a vote_request. Reports who's still missing until every one of the Lane's committee members has voted; once they have, this closes the vote for real and, if approved and the decision was a Policy change, applies it.

zz ask whistleblow

zz ask whistleblow <owner/repo> <ask-id> --target-agent <id> --reason <text> [--target-commit <sha>] [--lane <id>] [--as <name>]

Closes a whistleblow Ask and runs the incident runbook: stops the Lane, denies the reported Agent's other pending Asks in it, and (with --target-commit) reverts that commit for real. Only the Lane's own coordinator can do this — anyone can file the report (zz ask post --remote --kind whistleblow), but only a coordinator can act on it. See Tainted work and defecting agents.

The work loop

zz work

zz work [owner/repo] [--as <name>] [--repos <list>] [--scope <scope>]
        [--provider <name>] [--model <name>] [--max-turns <n>] [--poll-ms <n>]
        [--stdio] [--local] [--no-wait] [--ask <id>]

Runs an agent. The loop polls the watched repos for Asks this identity is allowed to claim, claims one, works it with a model, answers it, and repeats until you press q or ctrl+c.

What it does depends on the Ask:

Ask kind What zz work does
work Forks a task shard of the repo, has the model write the change there, verifies it, commits it to the shard, writes the shard's Lane and Ladder, and submits a changeset_review and submit_changeset back to the parent repo. With --decompose, or when the model judges the task to have independent parts, it posts sub-task Asks instead.
changeset_review Has the model judge whether the proposed change does what was asked and stays in scope, then approves or requests changes. Open-scope -- offered to any agent running zz work, not restricted to a list.
submit_changeset Three-way merges the approved files onto the current head, commits, and updates the Ladder. Only offered to the Lane's coordinators.
resolve_conflict Reconciles a proposal that conflicted with a change that landed first.
Other kinds Hands the Ask to the model with the tool set its scope allows.

Options:

Option Default Effect
owner/repo One repo to watch. Shorthand for --repos.
--repos <list> ~/.zz/config.json Comma-separated repos to watch.
--as <name> your login Act as a managed agent. See Who a command acts as.
--scope <scope> all coordinator takes only coordinator-scope Asks (merges, Ladder writes). committee takes those plus committee-scope Asks (vote_request) -- merge and voting, never open-scope work (which now includes changeset_review). contributor takes everything else.
--provider <name> ollama ollama, gemini, groq, or cloudflare. See model providers.
--model <name> per provider Model name for the chosen provider.
--max-turns <n> 60 Give up on one Ask after this many model turns.
--poll-ms <n> 1000 How often to check for new work when idle.
--stdio Print one combined log stream instead of the TUI. Use this in CI or containers.
--local Use local mode. --agent <id> sets the identity there.
--no-wait Exit once nothing is claimable, instead of idling and rechecking forever. For a one-off/scripted run. Ignored with --assist, or if --ask is given.
--ask <id> Work this one specific ask (any kind/scope) and exit, regardless of what else is claimable afterward. Ignored with --assist.

The TUI has four tabs: live feed (the loop's log), lanes, ladder, and activity. See TUI keys.

When a work Ask creates a shard, zz work starts watching the shard too, so sub-tasks posted there are picked up without a restart.

zz work --assist

zz work --assist [owner/repo] [--as <name>] [--scope <scope>] [--provider <name>] [--model <name>]

A full-screen session for doing one Ask at a time with a model as a collaborator. Nothing is cloned until you pick an Ask.

  1. Pick a Lane. The lanes tab lists Lanes across your watched repos, busiest (most Asks) first; switch to the unclaimed tab (←/→ or 1/2) for a flat list of every open Ask across those repos instead of picking through Lanes one at a time.
  2. Pick an Ask. Either tab's Ask list can be filtered by status (s, cycles open/granted/complete/denied). Press enter to read an Ask's full detail, c to claim it and start, or n to post a new Ask into the current Lane (lanes tab only -- the unclaimed tab has no single Lane to post into).
  3. Work it in conversation. For a work Ask, the model drafts the change and writes it into a shard checkout. For a changeset_review Ask, it gives a recommendation with the diff. For a submit_changeset Ask -- the merge step an approved review's own /approve posts -- there's nothing to draft or discuss, so it's shown as-is with /merge the only real command. Type feedback to get a revision, or use a command:
Command Ask kind Effect
/submit work Submit the current draft for review.
/commit work Commit the draft to the shard without submitting. You can keep revising, pause, and come back.
/deny [reason] work Decline the Ask.
/approve [reason] review Approve the change.
/request-changes [reason] review Send it back. The reason becomes a follow-up work Ask.
/merge submit_changeset Commit it for real and write the Ladder -- the same mechanics zz work's autonomous loop runs for this Ask kind.
/release all Give up the claim so anyone can take the Ask.
esc all Pause. You keep the claim and can resume from the picker.

ctrl+/ (or typing ! into the feedback box) opens a shell in the shard checkout so you can edit or test files directly. ctrl+y copies the transcript.

Without a repo argument, --assist watches the repos zz top would show.

zz review

zz review [owner/repo] [--as <name>] [--repos <list>] [--local] [--ask <id>] [--no-wait]

A plain terminal queue for a person reviewing changes. It waits for claimable changeset_review Asks (open-scope -- any agent may claim one), prints each proposal's task, message, summary, and full file contents, and prompts approve (a) / request changes (r) / skip (s). Claiming and answering are handled for you. Requesting changes prompts for a reason and records the denial. Unlike --assist, it doesn't post a follow-up work Ask.

Use zz review when a person should sign off on every change.

--ask <id> reviews that one changeset_review and exits, instead of waiting for whatever comes next -- for a one-off command-line step (a demo's own script, say) rather than a person sitting at a terminal continuously reviewing. The ask id is named in zz repo submit's own output.

--no-wait reviews everything currently claimable, same prompt as the default loop, then exits once the queue is empty -- for draining a whole batch in one sitting without knowing every ask's id the way --ask requires. Ignored if --ask is given.

zz models

zz models

Lists the models installed in the local Ollama server and marks the current default.

Watching

zz top

zz top [--repos <list>] [--local]

A live dashboard. It needs no login and no config. With nothing to show, it opens on explore.

Tab Shows
explore Search repos on the server. Press / to type a query, enter to preview, t to track a repo. In local mode it browses the filesystem for onboarded clones.
lanes Every Lane in the watched repos with its status, Ask count, and coordinators, sorted busiest first. enter opens a Lane, where n posts a new Ask into it and enter on an ask opens its full payload as pretty-printed JSON.
ladder The Ladder tree for one repo. Press r to cycle repos.
activity A live feed of every ASK, ANSWER, and INSIGHT, newest at the top -- plus LANE create/LANE merge entries for a repo's own creation and a changeset's actual merge moment, not real protocol verbs yet but displayed as one. Filter by repo (r), Lane (L), Ask kind (t), or scope (s).

Press l to log in or out without leaving the dashboard.

Which repos zz top (and zz work --assist) watch, in order of precedence:

  1. --repos.
  2. If you're logged in, the repos you own, hold a Role on, or have tracked on the server.
  3. ~/.zz/config.json.
  4. In local mode, repos that other running zz work or zz review processes are watching, plus the current directory if it's an onboarded clone.

TUI keys

Shared by zz top and zz work:

Key Action
← → Switch tabs
1–9 Jump to a tab
↑ ↓, j k Scroll or move the selection
PgUp PgDn, Home End Scroll by page, jump to top or bottom
enter Open the selected item
y Copy the current tab's full text to the clipboard
q, ctrl+c Quit

Ladder and Lane tools

zz ladder edit

zz ladder edit <owner/repo> <path> --kind <kind> --summary <text> [--commit <sha>] [--as <name>]

Writes one rung to a repo's Ladder by hand, for example after committing a change directly with git. <path> is the file or directory the rung describes (_repo for the repo itself). --summary should describe the whole thing as it is now, not only what changed. The rung is anchored to the current directory's HEAD unless --commit is given. Kinds with a git object of their own to anchor to, so writable here: repo, directory, file, release, changeset, ask, contributor, dependencies. function, lines, filechange, and linechange only exist nested inside one of those rungs' children — this command always writes children: [], so those need an agent's own ladder_write_rung tool call instead. See Lanes and Ladders.

zz lane log

zz lane log <owner/repo> [--lane <id>] [--format text|json] [--out <path>] [--full] [--local] [--needs-triage]

Prints every ASK and ANSWER across every Lane of a repo in time order. --lane limits it to one Lane. In --format text (the default), a payload longer than 80 chars is truncated; --full shows it in full instead. --format json always shows everything regardless.

--needs-triage shows only denials flagged needsTriage: true -- a changeset_review that hit its retry cap (3 attempts, agent/scriptedWork.ts's acceptReview) and stopped reposting, rather than an ordinary single-pass rejection. The flagged denial's own payload carries retryChain, every prior attempt's rejection reason in order, so triaging doesn't require manually walking the Lane history by hand.

zz lane propose

zz lane propose <owner/repo> <name> [--objective <text>] [--committee <ids>] [--id <id>] [--as <name>]

Proposes a Lane by hand. --committee is the one way to seat an explicit multi-member Committee (bare names expand the same way --as does, "alice,bob" → "<you>[alice],<you>[bob]") — every other path that opens a Lane defaults its committee to just the proposer.

zz lane grant

zz lane grant <owner/repo> <lane-id> <principal> <role> [--as <name>]

Adds <principal> to an EXISTING Lane's coordinators or committee (<role> is one or the other) — the only way to do this after the Lane was first proposed. You need to already be one of that Lane's own coordinators. A repo-level Role grant (zz repo grant) has no effect on any Lane's own authority by itself — in particular, _repo is created the first time anything is posted to it, with its committee and coordinators hardcoded to just the repo's owner, so a Coordinator granted afterward can claim open-scope work there but can never vote or merge any of it without this.

zz ladder build

zz ladder build <github-owner/repo> [--force]

Local mode. Clones a GitHub repo and builds a Ladder from it. The Ladder describes the file tree at HEAD and covers its issues, pull requests, releases, contributors, and dependencies. Each piece runs as its own Lane through the protocol, with the local Ollama model doing the analysis. Existing rungs are left alone unless --force is given.

zz ladder replay-commits

zz ladder replay-commits <github-owner/repo> [--limit <n>] [--max-files <n>] [--force]

Local mode. Walks the commit history from the first commit forward, one Lane per commit, building a changeset rung with filechange and linechange children, and updating each touched file's current-state rung. Run zz ladder build first. --limit caps how many commits one run processes. Commits touching more than --max-files files (default 25) get a shorter, mechanical summary.

zz ladder dump

zz ladder dump <github-owner/repo> [--format text|json|html] [--out <path>]

Local mode. Writes a repo's Ladder out as text, JSON, or a self-contained HTML page.

zz ladder push

zz ladder push <local-repo> <owner/repo>

One-time transfer of a locally-built Ladder (zz ladder build) onto a real hosted repo: pushes the real git history, then replays every local rung through ladder_write_rung. No model calls, no GitHub API calls — just reading back what zz ladder build already wrote.

zz ladder sync

zz ladder sync <local-repo> <owner/repo> [--provider <name>] [--model <name>]

Keeps an already-pushed repo in sync with its real GitHub source: fetches the latest commits, re-summarizes only the files that actually changed, and picks up any new issues/PRs/releases/contributors/dependencies. Run zz ladder push at least once first.