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.
In JSON mode, resume also includes top-level loaded_context metadata. This bounded, additive-only array explains why context was selected, for agent/user inspection and debugging. It can mention active Work State, unresolved carryover, failures, handoffs, decisions, strategies, and RepoMap hints. Items include role, selection_reason, confidence, staleness, and related_paths. It is not proof of correctness, does not expose hidden reasoning, and does not replace the execution contract.
When RepoMap is enabled and indexed, resume can also include structural_entry_points and structural_context. These are bounded structural hints for where to look first. RepoMap status separates provider_available, index_available, query_available, and refresh_available. Execution contracts may include expected_first_files, and finalize/contract compliance can record structural_alignment. RepoMap remains optional; missing refresh/provider support does not block resume when a queryable index exists.
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.
Portable continuity for teams
Portable continuity remains opt-in:
aictx init --repo . --portable-continuity
In 6.4.0, this enables the team-safe portability profile. Git stays the only transport. AICTX exposes append-only/sharded continuity artifacts to Git, keeps conflict-prone latest-run snapshots local-only, and can manage .gitattributes merge hints for portable JSONL files.
Portable writes are also secret-safe by default. AICTX redacts detected passwords, tokens, API keys, private keys, credential-bearing URLs, and similar secret-shaped values before persisting the portable subset.
Inspect the active portability policy:
aictx portability status --repo . --json
The status payload can report managed-file drift between portability.json, .gitignore, and .gitattributes.
It can also report portable secret-scan findings without exposing raw secret values.
Compact portable append-only JSONL artifacts after heavy merging:
aictx portability compact --repo . --apply --json
If a portable JSONL file contains invalid rows, compaction reports the blockage and leaves that file unchanged. If valid rows contain secret-like values, compaction redacts them when it is allowed to rewrite the file.
Advanced inspection commands
aictx advanced
aictx resume --repo . --task "continue current work" --json
aictx portability status --repo . --json
aictx portability compact --repo . --apply --json
aictx next
aictx task status --json
aictx map status
aictx doctor --repo . --json
aictx report real-usage
Public commands
aictx install
aictx init
aictx init --portable-continuity
aictx resume --repo . --task "continue current work" --json
aictx finalize --repo . --status success --summary "targeted tests passed" --json
aictx portability status --repo . --json
aictx portability compact --repo . --apply --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 doctor --repo . --json
aictx report real-usage
aictx clean --repo .
aictx uninstall
Doctor diagnostics
aictx doctor is a read-only support diagnostic. Use --release-readiness only for strict aictx release-gate checks.
aictx doctor --repo . --json
aictx doctor --repo . --release-readiness --json
The JSON response has:
status: ok|warning|error
mode: general|release_readiness
checks: [...]
recommended_actions: [...]
Default checks include CLI version, repo initialization, runner files, RepoMap provider/index/query/refresh status, capture quality, contract compliance health, and stale/duplicate memory. --release-readiness adds lifecycle smoke compatibility and Makefile/CI compatibility for the aictx release gate.
doctor is for humans, support, and CI diagnostics. Normal agents should not call it during startup.
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.
In normal startup, agents usually do not need to call map query directly. aictx resume consumes RepoMap as part of the continuity capsule and can render a compact Structural entry points section when relevant indexed matches exist.
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.