Reference: Lead and credentials
Reference for the "Lead and credentials" group of qargi commands: every verb with its arguments, options and examples, generated from the release.
Updated
qargi lead #
The lead session: its context, and the cloud lead's right to push.
usage and compact-check keep the lead's own context small: usage says how much of it is in use, compact-check says whether a /compact is safe now and what to re-read after it. Only the lead ever pushes, never a member. With a grant it creates agent/* branches and opens pull requests; every merge is asked of you, and it cannot publish releases. grant and revoke are interactive: each step prints its plan and asks you at the terminal, and your answer is the recorded approval. From Claude Code run them with !.
| Verb | What it does |
|---|---|
usage | How much of this session's context is in use: tokens of the last turn, percent of the window, transcript size |
compact-check | Is a /compact safe now? Exit 0 safe, 1 not, with every reason and the block to re-read after it |
grant | Guided: create or rotate the grant in three confirmed steps |
status | Show what is in place and what is missing |
revoke | Take the grant away |
qargi lead usage #
qargi lead usage [OPTIONS]
How much of this session's context is in use: tokens of the last turn, percent of the window, transcript size.
The runtime of the project says where its session transcripts are and how to read them (resources.transcripts of its definition): the context in use is the input, cache-read and cache-creation tokens of the last assistant turn. The window is the project answer lead.context_window (tokens), else the runtime's. Read only; a transcript that cannot be found or read prints unknown and exits 0.
| Option | Argument | What it does |
|---|---|---|
--project | PROJECT | the project, instead of the one inferred from here |
--session | ID | read the transcript of this session id (default: QARGI_LEAD, else the newest of this directory) |
--transcript | FILE | read this transcript file |
--json | machine-readable |
qargi lead usage
qargi project set acme lead.context_window 1000000qargi lead compact-check #
qargi lead compact-check [OPTIONS]
Is a /compact safe now? Exit 0 safe, 1 not, with every reason and the block to re-read after it.
Not safe while a local run is prepared and not verified, verified and not applied, or applied and not merged; a merge waits for its resolution; a whole-suite run (feature verify, release verify) is running; the handoff note written by marshal handoff --write is older than the last merge; or a release or hotfix branch is open. It prints the restart block: the handoff note, qargi marshal status, qargi feature status and the open runs, so the lead resumes from stored state. Read only. qargi cannot run /compact itself: the lead (or the person) does. feature finish, the last feature merge of a feature's runs, release finish and marshal handoff print one line when the context is at or above the project answer lead.compact_advice_pct (default 40; 0 turns it off).
| Option | Argument | What it does |
|---|---|---|
--project | PROJECT | the project, instead of the one inferred from here |
--advise | also say whether a compact is advised: from 50% of the window, strongly from 70% | |
--json | machine-readable |
qargi lead compact-check --adviseqargi lead grant #
qargi lead grant [PROJECT] [OPTIONS]
Guided: create or rotate the grant in three confirmed steps.
Explains how to create the fine-grained token, checks it, then: token and vault; the GitHub tool; the Push rules. Skips what is in place.
PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.
| Option | Argument | What it does |
|---|---|---|
--from-file | FILE | read the token from a file instead of asking |
qargi lead grant acmeqargi lead status #
qargi lead status [PROJECT]
Show what is in place and what is missing.
PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.
qargi lead revoke #
qargi lead revoke [PROJECT]
Take the grant away.
Removes the tool and the Push rules, detaches and archives the credential, deletes the token file. Revoke the token on GitHub yourself.
PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.
qargi credential #
Check or set up the tokens qargi uses.
Tokens live in files only you can read, outside every repository, and never in a command line, the tracker or the audit log.
| Verb | What it does |
|---|---|
check | Probe the repository token: it must read and should not push |
setup | Set up the cloud lead's write token (prefer: qargi lead grant) |
qargi credential check #
qargi credential check [PROJECT] [OPTIONS]
Probe the repository token: it must read and should not push.
PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.
| Option | Argument | What it does |
|---|---|---|
--allow-write-token | accept a token that can push, knowingly |
qargi credential setup #
qargi credential setup KIND [PROJECT] [OPTIONS]
Set up the cloud lead's write token (prefer: qargi lead grant).
Checks the token itself against GitHub (fine-grained, this repository only, no Administration), stores it mode 600, creates a vault with a bearer credential, attaches it to the lead's deployment and records the grant.
PROJECT can be left out inside the project's repository, or set QARGI_PROJECT.
| Option | Argument | What it does |
|---|---|---|
--from-file | FILE | read the token from a file instead of stdin |
--allow-more-repos | accept a token that can also write to other repositories | |
--asked | REQUEST | the request, in your words, that names the cloud instance; recorded in the audit log |
--plan | TOKEN | the plan token printed by the same command without --approved |
--approved | WORDS | your go-ahead for exactly that plan, in your words; recorded in the audit log |
qargi hook #
Claude Code hooks.
session-start loads the lead role's READMEs and indexes from both stores (about 4 KB) for the project whose repository the session is in, and the push grant. Register it as a SessionStart hook; it prints nothing outside a registered project.
| Verb | What it does |
|---|---|
session-start | Print the SessionStart hook output for the current project |
subagent-start | Record that a subagent started (SubagentStart hook) |
subagent-stop | Record that a subagent stopped and how many background tasks it still had (SubagentStop hook) |
tool-use | Record a successful tool call: its name and a hash of its input (PostToolUse hook) |
tool-failure | Record a failed tool call: its name, a hash of its input, whether it was an interrupt (PostToolUseFailure hook) |
notification | Record the type of a notification, for example permission_prompt (Notification hook) |
stop-failure | Record the error type a turn ended with, for example rate_limit (StopFailure hook) |
pre-compact | Record that the context is being compacted (PreCompact hook) |
qargi hook session-start #
qargi hook session-start [OPTIONS]
Print the SessionStart hook output for the current project.
| Option | Argument | What it does |
|---|---|---|
--project | PROJECT | the project, instead of finding it from the directory |
--role | ROLE | the role to load (default lead) |
qargi hook subagent-start #
qargi hook subagent-start
Record that a subagent started (SubagentStart hook).
Reads the hook's JSON on stdin and appends one small line to the run's event file under the state directory (ids, times, names and hashes; never command, message or error text). It always exits 0 at once, even on malformed input, so it cannot block an agent. Register it with qargi supervise hooks.
qargi hook subagent-stop #
qargi hook subagent-stop
Record that a subagent stopped and how many background tasks it still had (SubagentStop hook).
Reads the hook's JSON on stdin and appends one small line to the run's event file under the state directory (ids, times, names and hashes; never command, message or error text). It always exits 0 at once, even on malformed input, so it cannot block an agent. Register it with qargi supervise hooks.
qargi hook tool-use #
qargi hook tool-use
Record a successful tool call: its name and a hash of its input (PostToolUse hook).
Reads the hook's JSON on stdin and appends one small line to the run's event file under the state directory (ids, times, names and hashes; never command, message or error text). It always exits 0 at once, even on malformed input, so it cannot block an agent. Register it with qargi supervise hooks.
qargi hook tool-failure #
qargi hook tool-failure
Record a failed tool call: its name, a hash of its input, whether it was an interrupt (PostToolUseFailure hook).
Reads the hook's JSON on stdin and appends one small line to the run's event file under the state directory (ids, times, names and hashes; never command, message or error text). It always exits 0 at once, even on malformed input, so it cannot block an agent. Register it with qargi supervise hooks.
qargi hook notification #
qargi hook notification
Record the type of a notification, for example permission_prompt (Notification hook).
Reads the hook's JSON on stdin and appends one small line to the run's event file under the state directory (ids, times, names and hashes; never command, message or error text). It always exits 0 at once, even on malformed input, so it cannot block an agent. Register it with qargi supervise hooks.
qargi hook stop-failure #
qargi hook stop-failure
Record the error type a turn ended with, for example rate_limit (StopFailure hook).
Reads the hook's JSON on stdin and appends one small line to the run's event file under the state directory (ids, times, names and hashes; never command, message or error text). It always exits 0 at once, even on malformed input, so it cannot block an agent. Register it with qargi supervise hooks.
qargi hook pre-compact #
qargi hook pre-compact
Record that the context is being compacted (PreCompact hook).
Reads the hook's JSON on stdin and appends one small line to the run's event file under the state directory (ids, times, names and hashes; never command, message or error text). It always exits 0 at once, even on malformed input, so it cannot block an agent. Register it with qargi supervise hooks.