Usage
This is the command reference.
For normal setup, start with Installation. For a fast walkthrough, see Quickstart.
Normal use
Normal use is agent-driven:
pip install aictx
aictx install
aictx init
Then keep using the coding agent.
At normal task startup, supported agents should use one public continuity query:
aictx resume --repo . --task "<task goal>" --json
--task is the normal agent startup input. It should contain only the work goal and exclude reporting instructions, metrics schemas, output format rules, benchmark text, logging instructions, and meta-instructions about the final answer. Legacy --request startup input has been removed in v6.
resume compiles Work State, handoffs, last summary, Strategy Memory, Failure Memory, Decisions, RepoMap, previous contract signals, and an execution contract into one operational capsule. It does not replace prepare/finalize, startup banner rendering, final summary generation, or persistence.
The normal startup banner source is resume.startup_banner_text or resume.startup_banner_render_payload. In wrapped execution flows, the source remains prepare_execution().startup_banner_text.
The final summary source remains finalize_execution().agent_summary_text.
After task work, supported agents should close the lifecycle with the public finalize wrapper:
aictx finalize --repo . --status success|failure --summary "<what happened>" --json
aictx finalize is the normal public CLI surface for finalization. Advanced integrations can still use aictx internal execution finalize ... when they already have a prepared execution payload.
For JSON inspection, use a JSON parser:
aictx resume --repo . --task "continue current work" --json | python3 -m json.tool
Do not pipe --json into python3 -; that asks Python to execute JSON as Python source, where JSON booleans such as true are not valid Python names.
Advanced inspection commands
aictx advanced
aictx resume --repo . --task "continue current work" --json
aictx next
aictx task status --json
aictx map status
aictx report real-usage
Public commands
aictx install
aictx init
aictx resume --repo . --task "continue current work" --json
aictx finalize --repo . --status success --summary "targeted tests passed" --json
aictx advanced
aictx suggest
aictx reflect
aictx reuse
aictx next
aictx messages status
aictx messages mute
aictx messages unmute
aictx task start "Fix login token refresh"
aictx task status --json
aictx task list --json
aictx task show fix-login-token-refresh --json
aictx task update --json-patch '{"next_action":"run targeted auth tests"}' --json
aictx task update --from-file work-state-patch.json --json
aictx task resume fix-login-token-refresh --json
aictx task close --status resolved --json
aictx map status
aictx map refresh
aictx map query "startup banner"
aictx report real-usage
aictx clean --repo .
aictx uninstall
Message controls
AICTX is unmuted by default.
aictx messages status
aictx messages mute
aictx messages unmute
Muted mode suppresses AICTX’s automatic startup banner and execution summary. It does not disable AICTX, memory, telemetry, errors, or explicit command output.
Internal runtime commands
Internal commands are plumbing for integrations:
aictx internal boot --repo .
aictx internal execution prepare ...
aictx internal execution finalize ...
aictx internal run-execution ...
Agents/integrations use these to load and update continuity, including handoffs, decisions, Work State, failure memory, strategy memory, summaries, and contract compliance.
aictx internal boot --repo . is a bootstrap/runtime diagnostic payload. It is useful for checking effective preferences, communication policy, runtime state, task/failure/memory graph status, and consistency checks.
The visible startup continuity banner is not the raw boot payload. It is surfaced through prepare/startup continuity as startup_banner_text.
The normal agent-facing continuity query is not internal boot; it is:
aictx resume --repo . --task "<task goal>" --json
Normal agents should not inspect .aictx/ or run exploratory AICTX commands at startup. Advanced commands remain available for diagnostics, demos, and explicit user requests.
See Execution Contracts and Compliance for the contract/compliance flow and Handoffs and Decisions for the continuity artifacts behind startup context.
Strategy Memory commands
aictx suggest --request "fix startup banner" --json
aictx reuse --request "fix startup banner" --json
These commands expose successful historical execution patterns. See Strategy Memory.
In normal agent startup, Strategy Memory is consumed through aictx resume; agents do not need to call suggest or reuse first.
RepoMap commands
aictx map status
aictx map refresh
aictx map refresh --full
aictx map query "work state"
aictx map query "work state" --json
See RepoMap.
Contract compliance inspection
Contract compliance is generated by finalize when a compatible resume contract and observable execution signals are available.
Normal agents do not need to run an extra command. To inspect the historical aggregate manually:
aictx report real-usage
Detailed latest rows are stored in:
.aictx/metrics/contract_compliance.jsonl
Cleanup
aictx clean --repo .
aictx uninstall
See Cleanup.