Reference: help topics
The qargi help topics: the ideas behind the commands, such as roles, approvals, the guard, naming, memory and who may push, as qargi help prints them.
Updated
Each topic is also printed by qargi help TOPIC.
The model in one page #
Task: you describe one task and an executable check that decides it is done. An agent works on it in its own clone and hands back numbered patches, one per commit, with a manifest. Nothing is pushed.
Roles are build, write, review, test and lead: build changes code, write writes the operational docs, review judges a change and changes no file, test writes and runs tests, lead coordinates a team. Each role is defined by its role text, which comes with the task block. The local workers are members you name and give roles (qargi agent add NAME --roles build,test); qargi agent for ROLE prints the member that serves it. A role has its own model, effort, skills and packages, stored in the project's answers.
Local or cloud: local (a member on this machine) is the default. The cloud is used only when your request for that task names it, and every cloud verb records your words with --asked.
You decide: the coordinator re-verifies everything an agent returns (qargi review check), applies it as separate commits, and asks you before anything is pushed.
Roles and members #
Role build: changes the code with its tests, manual page, help and changelog.
Role write: writes the operational documentation on its own branch.
Role review: reads a change, runs its checks and reports a verdict, and changes no file.
Role test: writes and repairs tests and proves them failing first and stable.
Role lead: it does no work of its own; it coordinates a team of members on one task (qargi team, the skill qargi-team).
A member is a local agent you name (qargi agent add forge --roles build,test), rendered from the one member definition qargi ships. The task block names the role and carries its role text; there is no role skill to load. qargi agent for ROLE prints the member dispatch spawns. A cloud agent serves one role, is named <project>-<role> and carries its role text in its prompt.
Plans, tokens and your go-ahead #
A command that changes something shared prints a plan first. The plan ends with a plan token, a hash of what would be done.
To apply, run the same command with --plan TOKEN --approved "your words". If the plan changed in between, the token no longer matches and nothing happens.
--asked "your request" is required by every cloud verb: it records that you asked for the cloud. Both are written to an append-only audit log in the state directory.
qargi lead grant and revoke are interactive instead: you confirm each step at the terminal, and that is the approval.
The rules. The token covers the plan the person saw, and an apply refuses when the plan is no longer that one. The --approved text is recorded, not verified: it is not proof that a person agreed. Never allow-list a gated verb in the runtime's settings: the permission prompt is the person's real control. A member never applies: it reports the plan and its token, and the lead shows them to the person (what the member's guard refuses: qargi help guard).
What a member's guard refuses #
The guard hooks a member's calls: a barrier, not a wall; qargi local verify is its backstop.
It refuses verbs that change shared state: skill and tool new, import, seal, remove, unlink, link, enable, disable, accept and unaccept; discover install; import; packs apply, seed, link and unlink; project set (models, release, test_command, env, site, packs, upstream, roles.ROLE.tools, a whole role), init, new, link and unlink; provider new, import, seal, remove, enable, disable, attest, accept, check and adapter-run (the rest read); release publish, sign and site; marshal claim, set, renew, release, take, takeover, finish, enable, disable, key, signers and resign (handoff only with --write); feature start, finish, verify and park; branch prune; changelog renumber without --check; upstream status, sync; ref record; memory init, move, split, merge and copy; cloud set, unset and login; upgrade; local run, prepare, verify and clean; agent remove; team run; env plan and apply; task.
It refuses writes in the pack library, credentials, the install record, the runtime's skills, agents and plugin directories, the installed copy, the state's render, providers, marshal, feature and saved-run directories, its ref journal, the memory tiers, ~/.config/anthropic, and the lead's git configuration and session files. Reading stays allowed except the lead's signing key: copying, linking, archiving or searching its directory is refused. It refuses git push, git remote changes, git -c or config of keys that run programs (alias.*), gh, ssh, scp, sftp and rsync to a host.
A command is cut at every ; && || | and newline, inside quotes and heredocs too, and a substitution is a command: no refused verb, push or tag in text, unless every command is echo, cat, tee, grep or git commit and its kin (then text is data). Commit with git commit -F FILE. Piped or here-string shell programs are read; curl | sh and bash < f are refused. A cd it cannot read refuses relative writes.
The read-only class (review) writes only OUT and TMP: every change to the clone is refused, and a write through a name the guard cannot read. Nobody copies, extracts or links into the run directory.
Setting QARGI_NESTED, which skips a plan token check, or setting or unsetting QARGI_LEAD, is refused.
A refusal is a result: report it; do not work around it.
How resources are named #
Project and role are single lower-case tokens. An instance is <project>-<role>, for example acme-build. A session is <instance>-<task-slug>, and the agent's branch is agent/<task-slug>.
Cloud resources follow <project>-<component>[-<role>]: the agent <project>-<role> (acme-build), the deployment <project>-deployment-<role>, the shared <project>-environment, and the stores <project>-memory and <project>-reference. The lead is <project>-lead, and so is its agent.
qargi instances normalize renames existing resources to match.
The two memory stores #
<project>-memory is where agents write verified how-to facts they learn, under their own role folder (shared/ is curated and reached by promotion). <project>-reference is read-only: rules, workflow and conventions you and the coordinator curate. Both have shared/ for every role and roles/<role>/ for one.
An agent reads each store's README.md, then shared/INDEX.md and its role's index, then only the notes its task needs. The canon (qargi canon) fixes the layout and the note format. Read one note with qargi memory get.
qargi memory split, merge and copy move notes between two stores (directories, .jsonl dumps or store ids). Nothing is deleted: what leaves a store is archived under /_archive/<date>/, a collision goes to /_conflicts/<date>/, and the origin of every note written is added to its Sources: line.
Who may push #
Only the lead ever pushes, never a member, and only as the project's lead.push grant says. The default is nothing.
This Claude Code session as lead: lead.push.local lets it push agent/* branches and open pull requests without asking each time.
A cloud lead, or one started in the console: lead.push.cloud = branches. It has a GitHub tool with a fixed allowlist and the merge tool asked of you. Set it up with qargi lead grant. A merge or a release always needs your explicit approval.
The GitHub tool cannot create releases; those stay with this session.
Declaring a development environment #
There is no file format of this tool for it. A project says how to set up a checkout in what it already has: a section of AGENTS.md (or README.md) headed Development environment, Environment or Setup; version pins in go.mod, .tool-versions, mise.toml, .python-version, .nvmrc or package.json; .gitmodules; and two targets of its task runner (Makefile, justfile, Taskfile.yml or mise.toml tasks): bootstrap, which installs everything idempotently, and doctor, which prints one line per item and exits non-zero on a missing one. setup and check are accepted names.
Anyone, with or without qargi, runs the dry run (make -n bootstrap), reads it, runs bootstrap, then doctor. qargi env show prints what it found and the commands it would use; it runs nothing. qargi env check runs the doctor (the project's code, as trusted as test_command), adds the project's links, members, packs and memory and ends with ENV OK or ENV INCOMPLETE: N missing (...). A doctor line that begins with missing, fail or error, or ends with missing or not found, is a missing item; one that begins with expected is not red. qargi env plan runs the dry run (a dry run still runs project code: make -n expands $(shell ...)) and shows it with a plan token; qargi env apply runs bootstrap once for that plan. Both are the lead's.
A tool a role needs that the bootstrap does not provide (a pinned linter from go install, a downloaded binary, a vendored test framework that is a submodule) is declared once in the project's answers, roles.ROLE.tools (qargi help project set): env plan shows each with its state, env apply installs the go tools and binaries (the binary's sha256 must match), env check reports one that is missing or wrong, and qargi local prepare checks the submodules out in every member clone from the lead's copy, offline. Plain apt packages stay in roles.ROLE.apt.
For the author of a doctor target: print one line per item, for example the tool and its version. Start a line with missing, fail or error when the item is absent or wrong (such a line is a missing item); start it with expected for a known failure that is accepted (shown, not red); any other line is information. Exit non-zero when anything is missing, and change nothing.
qargi project new writes an AGENTS.md section and stub bootstrap and doctor targets (the doctor fails until you fill it in); project attach lists what a repository lacks; project adopt drafts the missing files on a branch to review. qargi provision plan prints the bootstrap command as setup-script text, and marshal handoff gives the last check and apply.
The project's answers can replace a command and list accepted failures: env.doctor_command, env.bootstrap_command, env.dry_run_command and env.known_failures (qargi project set acme env.known_failures '["line"]'). They are overrides, never a second description.
Where things are #
Configuration: ~/.qargi/config: projects/, instances.json, profiles/, packs/, credentials/, install.json.
State: ~/.qargi/state: sessions.json, local-runs.jsonl, audit.log, runs/, backups/, provision/.
Overrides: QARGI_HOME replaces ~/.qargi; QARGI_CONF and QARGI_STATE replace the two directories and win over it. XDG_CONFIG_HOME and XDG_STATE_HOME are not used. QARGI_PROJECT names the project when you are not inside its repository. QARGI_ROLES replaces the list of roles. QARGI_DRY_RUN prints a session request with secrets masked instead of sending it.
Nothing is stored in a repository.
Running a branch checkout #
install.sh --user records the tool it installed in ~/.qargi/config/install.json. A checkout run from any other place (its own bin/qargi, for example in a worktree) is then a dev run: it keeps its configuration and state in <checkout>/.qargi (ignored by version control), prints 'qargi: dev run from ...' on stderr once per command, and never touches your live data. Without install.json every checkout is the installed one.
QARGI_HOME, QARGI_CONF or QARGI_STATE, when set, win: QARGI_HOME=~/.qargi makes a dev run use live data on purpose.
help, version, completion, the guard and the run-event hooks print no banner. Members call qargi __guard from PATH, which is the installed copy; put <checkout>/bin first on PATH to test the guard or the hooks of a branch.