AICTX
Practical commands

AICTX User Manual.

Fast answers for common tasks: install, inspect continuity, enable portability, use MCP, reduce output, query RepoMap, generate reports and clean up.

basic loop 
pip install aictx
aictx install
aictx init

# then let your agent work normally
  • pip install aictx: installs the AICTX Python package.
  • aictx install: installs global runner integration files.
  • aictx init: initializes AICTX in the current repository.
  • Then let your agent run the resume/work/finalize lifecycle.

Start here: install, initialize, let the agent work

1. Install and initialize

pip install aictx
aictx install
aictx init
  • pip install aictx: installs the AICTX Python package.
  • aictx install: installs global runner integration files.
  • aictx init: creates the repo-local AICTX setup.

2. Let your agent work

aictx resume --repo . --task "continue current work" --json
# work normally
aictx finalize --repo . --status success --summary "what changed" --json
  • aictx resume: gives the agent the continuity capsule before it starts.
  • # work normally: the agent edits, tests and reasons as usual.
  • aictx finalize: saves the outcome for the next session.

3. Inspect continuity

aictx view --repo .
aictx doctor --repo . --json
  • aictx view --repo .: generates the local continuity report and map.
  • aictx doctor --repo . --json: checks setup health in machine-readable form.

Setup and health

Install

pip install aictx
aictx install
aictx init
  • pip install aictx: installs the AICTX Python package.
  • aictx install: installs global runner integration files.
  • aictx init: initializes AICTX artifacts in the current repository.

Check health

aictx doctor --repo . --json
aictx --version
  • aictx doctor --repo . --json: validates repo-local setup, config and generated artifacts.
  • aictx --version: prints the installed AICTX version.

Manual resume/finalize

aictx resume --repo . --task "continue current work" --json
aictx finalize --repo . --status success --summary "what changed" --json
  • aictx resume: returns the continuity capsule an agent should read before work.
  • aictx finalize: records what happened so the next session can continue.

Continuity and reports

Continuity View

aictx view --repo .
  • aictx view --repo .: writes .aictx/reports/continuity-view.md and .aictx/reports/continuity-map.mmd.

Real usage report

aictx report real-usage
  • aictx report real-usage: summarizes actual AICTX usage observed in the repository.

Release-style diagnostics

aictx doctor --repo . --release-readiness --json
  • aictx doctor --release-readiness: runs stricter checks useful before publishing or release work.

MCP and integrations

Use MCP

aictx mcp status --repo .
aictx mcp-server --repo . --profile full
  • aictx mcp status --repo .: shows whether MCP integration is configured for the repo.
  • aictx mcp-server --repo . --profile full: starts the local MCP server over stdio.

Disable MCP setup

aictx install --no-mcp
aictx init --no-mcp
  • aictx install --no-mcp: installs global integration files without MCP configuration.
  • aictx init --no-mcp: initializes a repo while skipping MCP setup.

Profiles

readonly  -> inspection only
standard  -> lifecycle writes
full      -> full AICTX continuity
  • readonly: exposes inspection without lifecycle writes.
  • standard: allows normal resume/finalize lifecycle writes.
  • full: exposes the complete AICTX continuity surface.

Portability

Enable portable continuity

aictx init --repo . --portable-continuity
  • aictx init --repo . --portable-continuity: enables portable continuity files that can travel through Git; no cloud sync is used.

Inspect portability

aictx portability status --repo . --json
  • aictx portability status --repo . --json: reports whether portable continuity is enabled and what is exposed.

Disable portable continuity

aictx init --no-portable-continuity
  • aictx init --no-portable-continuity: disables portable continuity for the repository.

Operational tools

Work State

aictx task start "Fix login token refresh"
aictx task status --json
aictx task update --json-patch '{"next_action":"run targeted auth tests"}' --json
aictx task close --status resolved --json
  • aictx task start: creates an active Work State for an unfinished task.
  • aictx task status --json: prints the current Work State.
  • aictx task update --json-patch: updates specific Work State fields.
  • aictx task close --status resolved --json: closes the task when it is done.

RepoMap

aictx map status
aictx map refresh
aictx map query "startup banner"
  • aictx map status: shows RepoMap availability and index state.
  • aictx map refresh: refreshes the structural file/symbol map.
  • aictx map query: searches RepoMap for relevant entry points.

Messages

aictx messages status
aictx messages mute
aictx messages unmute
  • aictx messages status: shows whether AICTX runtime messages are visible.
  • aictx messages mute: hides non-essential runtime messages.
  • aictx messages unmute: restores runtime messages.

Cleanup

Clean repo-local setup

aictx clean --repo .
  • aictx clean --repo .: removes repo-local AICTX setup artifacts managed by AICTX.

Uninstall global setup

aictx uninstall
  • aictx uninstall: removes global AICTX integration files from the machine.

What this manual covers

This manual covers the practical user-facing surface: setup, health, continuity inspection, MCP, portability, Work State, RepoMap, reports, message controls and cleanup. For internals, use Technical Documentation.

Technical documentation