Reference: Run a task

Reference for the "Run a task" group of qargi commands: every verb with its arguments, options and examples, generated from the release.

Updated 2026-11-05

qargi feature #

Develop on a feature branch; merge it into develop once, when complete.

A feature branch is cut from develop and can be as broad as a theme. The lead merges the verified series of each related task into it with --no-ff; tasks get targeted checks only. When the feature is complete the whole suite runs once on it and it is merged into develop with --no-ff and deleted. The merges are made in temporary worktrees and a branch moves only after every merge succeeded, so your checkout is never touched and a conflict changes nothing. Merging into develop and pushing need the plan token and an approval.

qargi feature start #

qargi feature start NAME [OPTIONS]

Cut feature/NAME from develop.

Refuses a name origin already has (asked live with git ls-remote), so another person's branch is not shadowed; fetch it instead. Refuses the name of a detached branch (repo.detached).

qargi feature list #

qargi feature list [OPTIONS]

List the open features: purpose, distance from develop, and the files two features both change.

Several features can be open at once. Two that change the same file will conflict whichever lands second: keep related work in one feature, unrelated work in another. It also flags each worktree of the project outside the worktree root (answers worktrees.root, default <state>/worktrees/PROJECT) with the git worktree move that fixes it; the main checkout, the worktrees inside it (the agent runtime makes its own there) and qargi's temporary worktrees are not flagged.

qargi feature park #

qargi feature park [OPTIONS]

Put the project's main checkout on its parking branch, reset to develop.

qargi moves develop without touching a working tree, so develop cannot be checked out in the project's main checkout. The checkout rests on a parking branch instead (answers repo.parking_branch, default scratch). This makes it: git checkout -B BRANCH develop in the main checkout, creating the branch when missing. Refused when the working tree is not clean, or when the parking branch has commits develop lacks (they are listed; re-implement them with an agent task based on develop, or keep them on a branch of their own). After feature finish, release finish and hotfix finish moved develop, a clean main checkout on the parking branch with no commits of its own is fast-forwarded to develop, and one status line says why it was not. The parking branch is never pushed or merged.

qargi feature sync #

qargi feature sync NAME [OPTIONS]

Merge develop into the feature (after another feature landed, before this one's checkpoint).

With the answer release.changelog.numbered true it then checks the changelog for duplicate item numbers and warns (exit status unchanged); feature finish refuses them. See qargi changelog.

qargi feature merge #

qargi feature merge NAME BRANCH [OPTIONS]

Merge a verified task branch into feature/NAME with --no-ff.

NAME may be a detached long-lived branch of the answers (repo.detached) instead of a feature: BRANCH must then be an agent/* branch, and the merge, local only, prints a plan and token like a merge into develop (--plan, --approved). A detached branch never meets develop, master, release, hotfix or feature branches: a merge between them, in either direction and by name or by history, is refused here, in sync, in finish and in release finish. For a feature, --plan and --approved are not used. When the registry of local runs names a run of BRANCH (its slug) that still exists and has no passing local verify, a warning names the run; the merge goes on.

qargi feature status #

qargi feature status NAME [OPTIONS]

Show the feature: commits ahead of develop and whether the whole suite passed at its head.

It asks the live origin with git ls-remote (QARGI_REMOTE_TIMEOUT seconds, default 10) where the branches are, not the last fetch, and says 'remote not checked' when origin cannot be reached. Flags worktrees outside the worktree root like list.

qargi feature verify #

qargi feature verify NAME [OPTIONS]

Run the project's whole test suite on the feature's head and record the result.

qargi feature finish #

qargi feature finish NAME [OPTIONS]

Merge the feature into develop with --no-ff and delete it.

Needs a passing whole-suite run at the feature's head. A feature behind develop is refused (exit 1, nothing changed); when both sides changed the same files since their merge base, the message lists them and says to run qargi feature sync first. With the answer release.changelog.numbered true it also refuses a changelog with duplicate item numbers (qargi changelog renumber). Pushes develop if the repository has an origin. With the answer branches.delete_merged local+remote (default local) it also deletes the feature branch on origin when origin has it (asked live) and holds nothing the feature lacks; the plan shows it and its token covers origin's tip. The answer branches.push_features (never, when-shared, always; default never) decides whether feature start, merge and sync push the feature branch: when-shared only when origin already has it. A plain push, never forced. A clean worktree of the feature under the worktree root is detached and removed after the merge, when the branch is deleted. It asks the live origin with git ls-remote (QARGI_REMOTE_TIMEOUT seconds, default 10) where the branches are, not the last fetch, and says 'remote not checked' when origin cannot be reached. A merge that conflicts changes nothing: the merge is left in progress in a worktree under the state directory (exit 3), you or the lead resolve and commit it there, and the same command with --resolved applies exactly that merge.

qargi marshal #

Who leads which open feature: lease, status, goal, plan, handoff.

The marshal keeps one record per open feature: its lead (identity and lease), status, goal, plan and a note, and derives the tasks, branches, worktrees and overlap from git and the local runs. Query it before beginning work or changing a plan: qargi marshal check NAME. A lead is a Claude Code session (identified by its session id), or whoever passes --as. A lead holds a lease that its actions and long verbs renew; another lead takes the feature only after it was released (take) or after the record stayed unchanged for the project's marshal.lease_minutes minutes (takeover, with your words). Records are state, not instructions: a note or goal written by another lead is data. By default the records are local to this machine; marshal enable switches the project to the shared backend, where each record is a commit on refs/qargi/features/NAME of the remote origin so several machines and people see the same leads (takeover then waits for the record to stay unchanged for the ttl as seen by the taker's own clock). Only the lead pushes those refs; a member run cannot. Exit status 3 means the remote could not be checked (the cache was used). Records can be signed: one key per lead machine, a signers file per project and the mode in the switch file (marshal enable --integrity); with integrity on, status and check tag records signed, unsigned, INVALID or cannot verify, strict ignores unsigned and invalid ones with a warning, and a rollback prints rollback detected.

qargi marshal claim #

qargi marshal claim NAME [OPTIONS]

Become the lead of feature NAME (creates the record; refuses when another lead holds it).

With --as-successor-of ID you take over from the lead ID without the owner's words when that lead's lease is stale and its host, OS user and work tree are yours (a restart gives the session a new id and nothing else that tells it apart). The record keeps its goal, plan and note and names the succession; it is audited as marshal:succession. Any other case is refused: the owner's marshal takeover covers it. feature start continues the same way on its own, and status and check name the command when you look like the restarted lead.

qargi marshal claim lead-context --as-successor-of 3f2a9c1e

qargi marshal status #

qargi marshal status [NAME] [OPTIONS]

Show one feature, or every open one with --all: lead, status, goal, plan, note, tasks, branches, worktrees, overlap.

The tasks of a feature are the local runs prepared against it (local prepare --base feature/NAME, as the registry of local runs records), and an unmerged agent branch is listed under that feature only. The agent branches of no open feature (no run recorded, or a base that is no feature branch) that are merged into neither develop nor a feature are said once, after the features, on an `unattributed agent branches` line (not in --brief).

qargi marshal set #

qargi marshal set NAME [OPTIONS]

Update the goal, plan, note or status of a feature you lead.

qargi marshal check #

qargi marshal check [NAME] [OPTIONS]

Before starting work or changing a plan: is the feature free for you, is anything else in its way (exit 1: refuse; warnings go to stderr).

qargi marshal renew #

qargi marshal renew NAME [OPTIONS]

Renew your lease on a feature (long verbs do this themselves).

qargi marshal release #

qargi marshal release NAME [OPTIONS]

Give the feature up, leaving a handoff note; it has no lead until someone takes it.

qargi marshal take #

qargi marshal take NAME [OPTIONS]

Become the lead of a feature that was released.

qargi marshal takeover #

qargi marshal takeover NAME [OPTIONS]

Take a feature from a lead that stopped (no change for the project's marshal.lease_minutes); needs your words.

qargi marshal finish #

qargi marshal finish NAME [OPTIONS]

Mark the feature finished (feature finish does this).

qargi marshal enable #

qargi marshal enable [OPTIONS]

Switch this machine's marshal to the shared refs backend (refs/qargi/ on the remote origin).

Without options it prints the plan and a plan token; apply with --plan TOKEN --approved WORDS (audited as marshal:enable). It needs a remote named origin. --integrity sets the mode: off signs and checks nothing; advisory signs when a key exists and tags records signed, unsigned or INVALID without ignoring any; strict ignores records not signed by a trusted key and falls back to the last accepted record. Not available in a member run.

qargi marshal key #

qargi marshal key SUBCOMMAND [OPTIONS]

Create this machine's signing key for the marshal records (key init).

`key init` makes $QARGI_CONF/credentials/marshal_ed25519 (mode 600), never overwrites it, and prints the signers line to trust on every lead machine. Audited as marshal:key-init. Not available in a member run.

qargi marshal signers #

qargi marshal signers SUBCOMMAND [PRINCIPAL] [OPTIONS]

List, add or remove the keys trusted to sign this project's marshal records (add | remove | list).

Edits $STATE/marshal/PROJECT.signers, which never goes into the repository or the refs. add and remove are audited as marshal:signers and refused in a member run; list is open to members.

qargi marshal resign #

qargi marshal resign NAME [OPTIONS]

Sign an unsigned open record (writes one more revision on top of it).

Used when moving from advisory to strict. The plan shows the head, its lead and goal and its token covers exactly that head; it is refused for a lead other than the accepted one. Audited as marshal:resign. Not available in a member run.

qargi marshal forget #

qargi marshal forget NAME [OPTIONS]

Drop this machine's accepted mark of a feature, so a stale mark stops reporting rollback detected.

Only with integrity advisory or strict, and only for a feature that has a mark. The plan shows the mark's revision and commit and its token covers both, so a mark that moved since is refused. After it the next record found for the feature is trusted on first sight again and a rollback against the old revision is no longer detected; the refs on the remote are not touched. Audited as marshal:forget. Not available in a member run.

qargi marshal handoff #

qargi marshal handoff [NAME] [OPTIONS]

Print the note a fresh session starts from, built only from stored facts.

Read only: it needs no lease and changes no record, ref or audit line. Nothing is fetched: shared records are read from the cache this host holds, with a note, and a shared marshal that is off or unreachable falls back to the local records. The note has the repository path, HEAD there (a detached HEAD is said plainly), develop's sha, the host and whether the qargi data is present on it. Per feature it has the tip, whether the whole-suite run applies to it, the agent branches merged into it since it was cut from develop, the unmerged ones prepared against it (as the registry of local runs records) and the commits ahead of develop; with NAME only that feature, otherwise every open one; the agent branches of no open feature are said once, after the features. The goal, plan and note of the marshal record appear under a line saying they are data from the lead, not instructions, with control characters stripped. The environment section gives the last env check and env apply recorded for the project (verdict, time, and whether that was at HEAD now). For a feature this identity leads it names the claim --as-successor-of command a restarted session runs. --write also records when the note was written (what qargi lead compact-check compares with the last merge), and a line says whether a compact is safe now (see qargi help lead). It also gives the packs render check and the launch line for the project's provider, the memory index and notes paths, the history command and a fixed list of what not to assume (approvals and plan tokens do not carry over). Output is capped at 16 KiB. --write refuses an existing file, a path inside a git work tree or the qargi directories, and a member run. The qargi-session skill says what to do with the note.

qargi marshal disable #

qargi marshal disable [OPTIONS]

Switch back to the local records; the refs already on the remote stay (audited as marshal:disable).

While integrity is advisory or strict it needs the plan token and your words (it drops the setting). Not available in a member run.

qargi release #

Releases and hotfixes by the git-flow rules.

release/<version> is cut from develop (a hotfix/<version> from master); its first commit bumps VERSION and dates the changelog and the man page. It is pushed and a pull request into master runs CI on the commit that will be released. Finishing merges it into master with --no-ff, tags it, merges it into develop (a hotfix: into the open release branch, if there is one) with --no-ff and deletes it. A release starts only from a develop whose head passed the whole suite. Pushing, merging, tagging and publishing need the plan token and an approval; signing needs your terminal. The layout of what a release updates is the project's, set in its answers (all optional): release.version_file (the file that holds only the version; default VERSION; none when there is no such file, and the version is then the changelog heading and the tag), release.changelog.unreleased (the heading of the changes to come, default '## [Unreleased]'; it may carry the version, as in '## {version} (unreleased)', and is then renamed) and release.changelog.released (default '## [{version}] - {date}'), release.man_pages (a list of paths; default the man/*.1 files), release.test_command (what release verify runs, a command line or a list of words; default test_command) and release.preflight (a command as a list of words, {version} replaced, run by start and push before they change anything; a non-zero exit refuses and shows the tail of its output). A member may not set them: the lead runs them. A project with a documentation site on a detached branch sets site.enabled to true, and optionally site.branch (default gh-pages when repo.detached lists it) and site.config (the site.json on that branch, default site/site.json, with the hand pages in the folder pages/ beside it): then release finish ends with 'next: qargi release site VERSION' (the methodology's after_release step) and release status has a site line.

qargi release start #

qargi release start VERSION [OPTIONS]

Cut release/VERSION from develop (hotfix/VERSION from master) and bump the version.

Before anything changes it checks what a release must update and refuses, naming the file and the fix: a man page (man/*.1) needs a .TH line with a date and a version field, which the first commit sets to the date and VERSION (the pages are release.man_pages, else man/*.1); a CHANGELOG.md needs content under its unreleased heading ('## [Unreleased]', or release.changelog.unreleased). The version file is release.version_file (default VERSION; none: no file is bumped). release.preflight runs before anything changes. A project without a man page or changelog is not checked for that part. A release (not a hotfix) ends by listing what it contains: the features merged into develop since the previous tag, the --no-ff merges whose message is "Merge branch 'feature/...'", one per line with the short sha.

qargi release status #

qargi release status VERSION [OPTIONS]

Show the branch, its commits and whether the whole suite passed at its head.

The full-suite verdict names the command that produced it, when it ran, how long it took and the mode the command names (-j N, shard I/K), from the suite record (a record made before the duration was kept shows the command and the time only). When release.test_command is set and is not that command, a line of its own says so: the pass is then not the release gate (release verify runs release.test_command). It asks the live origin with git ls-remote (QARGI_REMOTE_TIMEOUT seconds, default 10) where the branches are, not the last fetch, and says 'remote not checked' when origin cannot be reached. When the tag VERSION exists it also warns about a tag that has no GitHub release (asked with a read-only gh release view, through QARGI_GH, default gh; a gh that is missing or not logged in is a note) and about a tagged commit that lacks .github/workflows/release.yml while the branch has it, because a pushed tag starts that workflow only when its own commit contains it. Warnings and notes never fail the verb. Only when the optional answer release.sign is set (the default is not) and the tag has no GitHub release, it also says 'awaiting signature' until qargi release sign recorded a signature that still holds (no signed file or signature changed), and then 'VERSION is ready for signing: qargi release sign VERSION' when the repository is at the tag with the files built, or what stands in the way. When site.enabled is true a site line says 'site: not built for VERSION', 'site: built at SHA, not pushed' or 'site: pushed' (the commit of qargi release site on the site branch, and whether the live origin has it).

qargi release verify #

qargi release verify VERSION [OPTIONS]

Run the project's whole test suite on the release branch (develop's head before it starts) and record the result.

When the tag VERSION exists it also warns about a tag that has no GitHub release (asked with a read-only gh release view, through QARGI_GH, default gh; a gh that is missing or not logged in is a note) and about a tagged commit that lacks .github/workflows/release.yml while the branch has it, because a pushed tag starts that workflow only when its own commit contains it. Warnings and notes never fail the verb. The exit status stays the suite's result. The command is release.test_command when the project sets one, else test_command.

qargi release push #

qargi release push VERSION [OPTIONS]

Push the branch and open the pull request into master.

It asks the live origin with git ls-remote (QARGI_REMOTE_TIMEOUT seconds, default 10) where the branches are, not the last fetch, and says 'remote not checked' when origin cannot be reached. When release.preflight is set it runs in a copy of the branch once the plan is approved, before anything is pushed; a non-zero exit refuses.

qargi release finish #

qargi release finish VERSION [OPTIONS]

After the checks pass: merge into master, tag, merge back, delete the branch, push.

Merging back may conflict, usually over the version number (the model says so). Nothing moves then: resolve in the worktree the message names, commit, and run the same command with --resolved. It refuses a branch whose manual page has an empty .TH date or version, and, when release.version_file is none, one whose changelog has no section for VERSION. It asks the live origin with git ls-remote (QARGI_REMOTE_TIMEOUT seconds, default 10) where the branches are, not the last fetch, and says 'remote not checked' when origin cannot be reached. It ends with a 'next: ...' line for each after_release step of the methodology whose answer is true: with site.enabled, 'next: qargi release site VERSION'.

qargi release sign #

qargi release sign VERSION [OPTIONS]

Sign the release files from the tag with your own key, on your own terminal, and record that they verify.

Signing is optional and off by default: it applies only to a project whose answers hold release.sign (otherwise this exits 2 and nothing else changes). Run it in your terminal, in the project's repository checked out at the tag (git checkout --detach VERSION, with the release files built from it): after finish, before publish. For each file of the answer release.sign.files it runs ssh-keygen -Y sign -f KEY -n NAMESPACE FILE attached to your terminal (stdin, stdout and stderr are yours; nothing is captured and no input is logged), so you type the key's passphrase there and it never passes through qargi, a log or an agent; no ssh agent is asked. Then it runs release.sign.verify_command (a list of words, no shell) in the repository and records the result, the tag's commit and the hash of every signed file and signature under the state's release directory. Refused (exit 1) when stdin is no terminal, HEAD is not exactly the tag VERSION, on a branch other than master, or a tracked file is modified; refused (exit 2) in a member run, when QARGI_NESTED is set or when release.sign is not set. A member run cannot sign. The answers: release.sign.key (an ssh private key), release.sign.namespace, release.sign.files (relative to the repository) and optionally release.sign.verify_command.

qargi release publish #

qargi release publish VERSION [OPTIONS]

Create the GitHub release of an existing tag, with its changelog section (or a notes file) as the notes and the assets attached.

For a tag that has no GitHub release, for example one pushed before the release workflow existed. The plan shows the tag, its commit, the notes (the VERSION section of CHANGELOG.md at the tag, found by release.changelog.released, or the notes file), the sha256 of every asset and the command: gh release create VERSION --verify-tag --title "PROJECT VERSION" --notes-file FILE ASSET... (gh is run through QARGI_GH, default gh, and must be logged in); the token covers the notes and the assets. The assets are --asset and release.assets, regular files inside the repository, attached by the same call that creates the release. It refuses when GitHub has the release already, when the tag is missing, when the notes are empty, and, when the answer release.sign is set, until qargi release sign recorded an ok for VERSION and none of the signed files or signatures changed since (without release.sign, which is the default, there is no such wait); --verify-tag makes gh refuse a tag that is not on origin. Needs the plan token and an approval; a member run cannot publish.

qargi release site #

qargi release site VERSION [OPTIONS]

Build the documentation site of the tag VERSION and commit it on the detached site branch; never pushes.

Only when the answer site.enabled is true. The source is the tree of the tag VERSION (its CHANGELOG.md, VERSION, README.md and lib/commands.py, from which the reference is generated); the hand pages and site.json are those of the site branch (site.branch, default gh-pages when repo.detached lists it; site.config, default site/site.json, with the hand pages in pages/ beside it). lib/site.py builds it in a temporary worktree of the site branch: the site.json records release VERSION and _site/ holds the built site. The plan shows the build's warnings and the size of the change, and the token covers the tag, the branch's tip and the built tree; the apply commits it as 'Site: built from release VERSION' and moves the branch, touching no working tree, and prints the git push command for you to run. Nothing is committed when the build is already there. Refused when the branch is checked out somewhere, when the tag is missing and when the build reports an error; refused (exit 2) in a member run and when QARGI_NESTED is set.

qargi release site 0.2.1
qargi release site 0.2.1 --plan TOKEN --approved "yes, commit the site"

qargi branch #

Branch housekeeping: delete the merged agent and feature branches and their worktrees.

Prune prints the merged agent/* and feature/* branches of the project (and with --remote the same branches on origin, asked live) and the worktrees qargi made for them, with a token; with --plan and --approved it deletes them. A branch is merged when it was merged with --no-ff into develop, or, for an agent branch, into an open feature, and is still in that branch's history; a branch that merely sits at the tip of develop or of a feature was never merged and is kept. It never deletes master, develop, the branches of repo.long_lived and repo.detached, the parking branch, an unmerged branch, or a branch checked out in a worktree qargi did not make (the main checkout, the runtime's own worktrees) or in a dirty one; each kept branch is listed with the reason. A remote branch is deleted as a lease on the tip the plan showed.

qargi branch prune #

qargi branch prune [OPTIONS]

List, or with the token and an approval delete, the merged agent/* and feature/* branches and their worktrees.

qargi branch prune
qargi branch prune --remote --plan TOKEN --approved "yes, prune them"

qargi changelog #

Numbered changelog items: find duplicate numbers and renumber them.

For a project whose changelog numbers its items, which it says with the answer release.changelog.numbered: true (off by default). Under the unreleased heading (release.changelog.unreleased, default '## [Unreleased]'), an item is a line that starts with a number, a dot and a space ('12. text') or with '- ', the number, a dot and a space ('- 12. text'); the lines up to the next item belong to it. Two branches that each added an item 5 leave two items numbered 5 once merged. feature sync and feature finish run the check when the answer is true: sync warns, finish refuses (exit 1, nothing changed) until the numbers are renumbered, committed and the suite has run again.

qargi changelog renumber #

qargi changelog renumber [OPTIONS]

Find the duplicate item numbers under the unreleased heading and renumber them in file order.

Works on the CHANGELOG.md of the work tree around the current directory, which must belong to the project (the feature's worktree, not the main checkout while it rests on the parking branch). Only when a number is duplicated, the items are numbered again, consecutively in file order from the number of the first one, and every '(item N)' cross-reference inside the section follows the item it means: with a duplicated N, the nearest item numbered N at or before the reference, else the nearest after it. The file is rewritten and not committed. Without --check it is the lead's: a member run may only use --check.

qargi changelog renumber --check
qargi changelog renumber

qargi upstream #

Follow an upstream repository: how far behind, what is new, sync its branch.

A project that is a fork keeps its own changes, the overlay, on top of an upstream repository. The answers name the remote (upstream.remote), the branch it follows (upstream.branch) and the local branch that carries the upstream line and nothing else (upstream.into, default upstream); upstream.overlay_check, optional, is a command array that checks the overlay still applies or builds. status fetches that one branch of that remote (the only verb that reaches the network) and says where the branch stands; review and sync work from the last fetch. The upstream line never meets develop directly: after a sync, cut a feature and merge the branch into it (qargi feature start upstream-X, then qargi feature merge upstream-X BRANCH), fix the overlay there, and let the feature land as any other. Nothing is pushed.

qargi upstream status #

qargi upstream status [OPTIONS]

Fetch the upstream branch and say how far the local branch is behind and ahead of it, with the newest upstream commits.

The fetch is of that one branch of that remote, with no tags; it changes the remote-tracking ref and nothing else.

qargi upstream review #

qargi upstream review [OPTIONS]

List the upstream commits not yet in the local branch, with the files each one touches; a commit that touches a file the overlay changed is marked.

The overlay is what develop changed since it parted from the upstream line (their merge base). Reads the last fetch (qargi upstream status); changes nothing.

qargi upstream sync #

qargi upstream sync [OPTIONS]

Fast-forward the local branch to the fetched upstream branch (--ff-only), with the token and an approval.

Refused when the branch has commits of its own (not a fast-forward): it carries the upstream line only. Creates the branch at the upstream tip when it does not exist yet. The move is journaled; nothing is pushed and nothing is merged into develop: the next step is printed. With upstream.overlay_check set, the command then runs on a trial merge of the branch into develop in a temporary worktree (the fast-forward stands either way; a failure or a merge conflict exits 1).

qargi upstream sync
qargi upstream sync --plan TOKEN --approved "yes, take the upstream commits"

qargi ref #

Record in the lead's ref journal a branch move that no flow verb made.

The ref journal ($QARGI_STATE/ref-journal.jsonl) is the lead's record of the branch and tag moves qargi's verbs make (feature, release, branch prune, review apply, with their pushes); qargi local verify and local clean accept and name what it records. qargi ref record adds the one move a lead makes by hand that verify must still accept: the rewrite of an agent branch that keeps its content.

qargi ref record #

qargi ref record REF OLD NEW [OPTIONS]

Rewrite an agent branch to a commit with the same tree, and journal the move with the reason.

REF is an agent/* branch (agent/NAME or refs/heads/agent/NAME). It refuses NEW unless git rev-parse OLD^{tree} and NEW^{tree} are the same, and REF unless it is at OLD now; the move is then a compare-and-swap (git update-ref REF NEW OLD), so nothing moves when REF changed meanwhile. The journal line has verb ref:rewrite and the reason, and a run prepared before the move verifies and is cleaned with it named as a rewrite; local clean and local list follow the applied tip of a run to NEW. No working tree, other ref or origin is touched. Not available in a member run.

qargi ref record --rewrite agent/fix-names 1a2b3c4 5d6e7f8 --why "reworded two messages"

qargi start #

Start a standby cloud session for an instance.

Cloud only, and only when your request names it. The session's spend ceiling comes from the deployment.

qargi start NAME [OPTIONS]

qargi send #

Send a task to an idle cloud session.

The text is the whole brief: TASK, DONE (a command whose exit status decides it), BASE, SCOPE and so on. The session is titled <instance>-<label>; use the same slug for the agent/<slug> branch.

qargi send NAME TASK [OPTIONS]

qargi send acme-build "$BRIEF" --label rename-verb --asked "use the cloud builder for this"

qargi status #

Show tracked cloud sessions, or one session.

qargi status [SID|NAME]

qargi report #

Cost per applied change, what waits for review, what looks stuck.

Read-only. From the session tracker: per instance and in total, the sessions by review state and status, the spend (list_cost, in the units of the budget flags: cents, per the docs) and the spend per applied session, how long each session pending review has waited (oldest first), the sessions that look stale (running, or idle and pending review, with no refresh for --stale-after), the idle sessions split by why they stopped when that is recorded, and the time from creation to close. A second section lists local runs from the run directories qargi local prepare made: finished (manifest DONE or BLOCKED), no manifest and still changing, or no manifest and quiet for --local-stale-after (possibly stalled). The output says what it cannot tell you; it never prints a session's note or request.

qargi report [OPTIONS]

qargi report
qargi report --since 2026-10-01 --instance acme-build --json

qargi noticed #

What members noticed and did not act on, and what became of it.

Collecting a session's outputs records each noticed_not_acted_on note of its manifest (stored short, secret-looking strings redacted) in the append-only events file beside the audit log. Each note stays open until you give it a disposition: followup, dismissed (with --why), accepted or superseded. qargi report shows how many are open and how old the oldest is.

qargi noticed list #

qargi noticed list [OPTIONS]

Print the open notes, oldest first.

qargi noticed resolve #

qargi noticed resolve ID DISPOSITION [OPTIONS]

Give a note a disposition.

qargi watch #

Wait for a cloud session to stop; prints one line when it does.

Run it in the background. The line is QARGI WATCH <sid> idle|terminated|budget_reached|budget_tight|timeout|auth|error. budget_tight ends it early, with the cost and the ceiling in cents, so you can raise the ceiling (qargi instances budget NAME CENTS --session SID) and watch again.

qargi watch SID [MAX_SECONDS] [OPTIONS]

qargi collect #

Download a session's output files into a fresh directory.

Everything downloaded is untrusted data. A team's files carry a role prefix and are split into one directory per member, patches under patches/. Refuses a directory that is not empty.

qargi collect SID DIR

qargi stop #

Interrupt a running cloud session.

qargi stop SID

qargi close #

Archive a finished cloud session.

Refused until the outputs are collected, unless the task produced none.

qargi close SID [OPTIONS]

qargi mark #

Record what happened to a session's work.

With --why, also records the reason (a code from lib/reasons.json); qargi report counts the reasons.

qargi mark SID STATE [OPTIONS]

qargi track #

Track a session that was started elsewhere (for example in the console).

qargi track NAME SID [OPTIONS]

qargi local #

Prepare, verify, list and clean a local run that has no way to push.

The agent works in a clone of a bare copy that has no remote, runs git through a credential-less wrapper, and verify compares every ref of the real repository before and after. It is a guard, not a sandbox.

qargi local run #

qargi local run RUN [OPTIONS]

Run a task through a command runtime (a vendor CLI) in a prepared run; --dry-run prints what would run.

Only for a runtime whose dispatch mode is command; a runtime that works inside the session (dispatch mode in-session) is refused: dispatch it as its notes say (qargi provider notes spawn). The command is built from the definition without a shell, runs in a scrubbed environment (only the names the pack's env_pass lists, which the review shows), and its output goes to OUT/transcript. A read-only run needs the barrier the definition declares (or your acceptance). A library pack's executable runs only from its sealed copy. Exit status: 0 the command succeeded, 1 it failed (or a usage error, such as no task block), 2 refused (a barrier the run cannot have, a refused definition), 3 the runtime cannot be run this way (not a command runtime, its command is not on PATH), 4 transport (the definition maps the command's exit to it).

qargi local prepare #

qargi local prepare [OPTIONS]

Make the clone and the wrapper for a local agent.

Prints KEY=value lines: RUN, ROLE, CLASS, PROFILE (the role's own unless --profile), MEMBER, MODEL and EFFORT (only with --profile), CLONE, OUT, TMP, GIT, BASE_SHA, CONTRACT (the run's own copy of the member contract, with the contract addenda of the project's local runtime as runtime-addenda.md) and, when the role declares submodules (roles.ROLE.tools, kind submodule) and the clone got them, SUBMODULES=path,... Each declared submodule is checked out in the clone from the lead's copy of its objects (the checkout at REPO/PATH, else the modules directory), offline: a mirror with no remote under RUN/sub and git submodule update from it, push URL disabled. A commit the lead's copy lacks, a submodule not initialised there, or a run made with --repo-url, is a note on stderr; nothing is fetched. Then a blank line and a TASK-BLOCK PATHS block (RUN_DIR, CLONE, OUT, TMP, GIT, BASE_SHA, CONTRACT) to copy into the task, and in a stored project a TASK-BLOCK MEMORY block. A caller that evals the output must stop at the blank line. When the project (found by matching the repository against the stored answers) has a render for its local runtime (packs apply --target RUNTIME) that has drifted, prepare also prints a WARNING block to stderr with the findings and the fix, packs apply --target RUNTIME PROJECT. The run goes on, and stdout and the TASK-BLOCK PATHS block are unchanged. A --scratch on a tmpfs (/dev/shm, often /tmp) is warned about on stderr: a reboot empties it and loses the run (its clone, commits and output); prefer a directory on disk, such as ~/.cache/qargi-runs.

qargi local verify #

qargi local verify [RUN_DIR] [OPTIONS]

Compare the repository's refs with the snapshot taken by prepare.

Exits 2 when refs changed (1 before), 3 when the lead's registry does not vouch for the run: it is not in it, names no repository for it, or RUN/repo.path, repo.url or cred.path differ from it (the repository and the credential come from the registry; a member can write the run directory). It accepts the lead's own moves and names each one ("develop moved by qargi feature finish"): what the lead's ref journal records (the branches and tags that qargi's flow verbs move, push to origin or delete: feature finish and park, release and hotfix finish and push, branch prune, review apply, the parking branch following develop, a rewrite recorded with qargi ref record --rewrite), a remote-tracking ref of origin that says what origin has (a fetch), and the parking branch (repo.parking_branch, default scratch) fast-forwarded to develop's tip, by hand too. After a passing verify the run records RUN/verified and its line in the registry is marked verified (what marshal status and handoff list the task as, also after clean); later verify and clean compare with that and also accept your fast-forwards of develop and master and of agent|feature|release|hotfix/* branches, and new branches there. Anything else (a push, a tag, a deletion or a rewrite nobody journaled) fails. Run it on every run before merging any of them. When it passes it copies OUT, a run bundle beside it and the snapshots to <state>/runs/<run id>/, so a run lost with its directory (a reboot that emptied a tmpfs) can still be applied: qargi review apply --from-saved ID. --saved ID compares the refs against that copy's snapshots.

qargi local clean #

qargi local clean [RUN_DIR] [OPTIONS]

Remove a collected, verified run and its temporary directory.

Prepare makes a private temporary directory for the run (TMP, on /dev/shm when it exists) that the agent puts its test sandboxes in; clean removes it with the clone, the bare copy and the output (only when it is a qargi-run.XXXXXX directory under /dev/shm or QARGI_RUN_TMP, or inside the run). It refuses a run whose output has no manifest (collect first) and one whose repository refs changed (that is evidence); the lead's own moves that verify accepts (a feature finish since the run was prepared, for one) are no change and are named in its output. It also refuses a run whose clone holds commits that were never applied (review apply) or whose applied tip is on no branch but agent/* in the repository (feature merge first), so finished work is not deleted by mistake. --discard is the deliberate way past all of these; it still refuses anything that prepare did not make. A run cleaned with --applied needs a RUN/applied record and a repository path in the registry (a run of a repository URL is kept); --applied takes no RUN_DIR and no --discard. A cleaned run keeps its line in the registry, marked cleaned: marshal status and handoff list it as cleaned, never as an open task. --stale DAYS --scratch DIR is a plan first: it prints each finished run older than DAYS days and changes nothing; with --yes each is cleaned exactly as clean RUN would, so a stale run whose commits were never applied or merged is kept and named (exit status 1), never dropped. It is refused without --scratch, takes no RUN_DIR, no --applied and no --discard, and --yes is for --stale only. A run whose directory is gone (a reboot, or removed by hand) is the registry's record and the saved copy alone: clean RUN drops both once the saved work is applied and merged, and refuses otherwise; clean RUN --discard drops them whatever they hold. --stale counts such a run by the start time of its record, and with --yes drops it unless its saved copy holds work that was never applied (kept and named). A clean marks the run's record cleaned and removes its saved copy.

qargi local clean --applied --scratch /tmp/scratch
qargi local clean --stale 14 --scratch /tmp/scratch
qargi local clean --stale 14 --scratch /tmp/scratch --yes

qargi local list #

qargi local list [OPTIONS]

List the local runs: role, slug, age, whether applied and merged.

Read-only. One row per run: ROLE, SLUG, AGE, APPLIED (RUN/applied exists: review apply ran), MERGED (the applied tip is on a branch other than agent/*; ? for a run of a repository URL) and RUN. It is the list that qargi local clean --applied --scratch DIR acts on. A directory is a run only when the lead's registry names it (a directory a member makes beside its own run is not one), and the AGE is ? when the run's started file is not a number. A run of the registry whose directory is gone and that clean did not remove is listed after the others as directory gone, with its saved copy and the review apply --from-saved command that applies it.

qargi supervise #

Find stalled agent runs: notify, prepare a nudge, never act alone.

Hooks only record (the run-event verbs of qargi hook append ids, times, a tool name and a hash to a per-run file under the state directory; no command, message or error text). One idempotent tick is the only actor: it folds those files, the local-run registry and the session tracker into runs.json and classifies each unfinished run in a fixed order: waiting on an approval (not a stall), stopped by an API error, interim (turn ended, background work running, a cap of about 35 minutes), looping (three identical tool digests in a row), suspected dead (no activity for too long); for cloud sessions requires_action, budget_reached, stale while running, idle awaiting review. It acts only by printing `QARGI SUPERVISE <class> <run> <next-action>` lines, appending to supervisor.log and the audit log (origin supervisor), and PREPARING a nudge in nudges.jsonl. A nudge is a fixed template, at most 2 per run with at least 10 minutes between them, never while the run waits on an approval or has little budget left, and never an approval. A script cannot message a local subagent: the coordinating session delivers the prepared nudge and records it with delivered, and only then does it count. A cloud nudge is sent only by nudge, which needs --asked. Nothing sends automatically; the thresholds are data in lib/supervise-defaults.json, conservative floors until `qargi report` shows real run lengths. Run the tick on a timer or a loop; status warns when it has not run for twice its interval.

qargi supervise tick #

qargi supervise tick [OPTIONS]

Fold the events, classify the runs, print what needs attention, prepare nudges.

Run twice with nothing new it prints nothing the second time.

qargi supervise tick

qargi supervise status #

qargi supervise status [OPTIONS]

Show the runs by class and the nudges waiting; warns when the tick is overdue.

qargi supervise nudge #

qargi supervise nudge SID [OPTIONS]

Send the fixed nudge to a cloud session, only when the caps allow.

Refused when the session waits on an approval or has little budget left, when 2 nudges were already counted, or within 10 minutes of the last one. The message is the fixed template, never text from the agent.

qargi supervise nudge sesn_abc --asked "nudge it, it has been quiet for hours"

qargi supervise delivered #

qargi supervise delivered KEY [OPTIONS]

Record that you delivered a local run's prepared nudge.

KEY is the agent id the tick printed. Only then does the nudge count against the cap.

qargi supervise hooks #

qargi supervise hooks [OPTIONS]

Print the settings.json hook snippet for the run-event handlers.

It never writes the file: merge the entries into your Claude Code settings.json yourself.