Quickstart

AICTX Quickstart.

This walkthrough shows the shortest path from setup to visible operational continuity.

AICTX is built around one loop:

resume before work -> work normally -> finalize evidence -> next session continues

1. Install and Initialize

pip install aictx
aictx install
aictx init

# Then just keep using your coding agent.
# Agents handle the lifecycle themselves:
# resume context → work → finalize continuity

Optional check:

aictx --version
aictx doctor --repo . --json

Fresh repos start with little continuity

A fresh repo may have little continuity. That is expected. AICTX becomes more useful after work has been finalized and Work State, failures, decisions, or handoffs exist.

MCP support

By default, aictx install prepares AICTX MCP runtime metadata and aictx init writes repo-local MCP config for compatible clients.

Launch local stdio server

aictx mcp-server --repo . --profile full

Inspect MCP setup

aictx mcp status --repo .

Opt out

aictx install --no-mcp
aictx init --no-mcp

Agents should prefer MCP tools such as aictx_resume, aictx_finalize, and aictx_view when available, and fall back to CLI commands otherwise.

Interactive install

Installation prepares AICTX MCP support by default and will only ask you about enabling recommended RepoMap support using Tree-sitter.

RepoMap uses Tree-sitter to build a compact structural map of files and symbols. It helps agents choose better starting points without reading the whole repo.

Interactive init

During initialization, you can choose from different communication modes. disabled is the default.

Communication modes:
- disabled: No special communication layer; agents answer normally.
- caveman_lite: Light compact mode; keeps explanations but reduces chatter.
- caveman_full: Strong compact mode; recommended if you want less runtime noise.
- caveman_ultra: Aggressive compression; shortest responses, least prose.

Need more setup detail? See Installation.

2. Normal flow example

Session starts
The user asks for a task
AICTX provides the agent with a continuity resume capsule

codex@my-repo · session #12 · awake

Resuming: parser refactor was paused after updating token tests.
Last progress: `tests/test_parser.py` passes; next step is to update error recovery cases.

────────────────────────────────

Agent performs the task
AICTX updates continuity artifacts
Agent provides the user with a continuity summary

────────────────────────────────
AICTX summary

Context: resumed parser refactor from previous session state.
Map: RepoMap quick ok.
Saved: updated handoff and continuity state.
Validation: `pytest -q tests/test_parser.py` passed.
Next: update parser error recovery cases.
Details: last_execution_summary.md
Continuity view file: continuity-map.mmd
View continuity online: mermaid.live view

3. Inspect Continuity View Manually

aictx view --repo .

Default output:

.aictx/reports/continuity-view.md
.aictx/reports/continuity-map.mmd

Not hidden memory. Reviewable operational continuity.

Next steps

User Manual

Practical commands for common tasks.

Open User Manual →

Technical Documentation

Full reference and internals.

Open Technical Documentation →