AICTX

Technical overview

AICTX is a lightweight repo-local continuity runtime for coding agents.

It is not an agent framework, RAG system, vector database, dashboard, task manager, or cloud memory service. It stores bounded operational continuity in the repository so a later coding-agent session can start from useful facts instead of rebuilding context from scratch.

Core lifecycle

User setup:

aictx install -> aictx init

Agent runtime:

resume -> work -> finalize -> later resume

Public commands:

aictx resume --repo . --task "<goal>" --json
aictx finalize --repo . --status success|failure --summary "<what happened>" --json
aictx doctor --repo . --json
aictx view --repo .

Components

Component Role
Repo scaffold Creates .aictx/ and managed instruction/config files.
Runner integrations Gives Codex, Claude Code, GitHub Copilot, and generic agents the same lifecycle instructions.
Resume capsule Compiles Work State, handoffs, decisions, failures, quality signals, optional RepoMap hints, and execution contract into an agent brief.
Finalize Persists observed files, commands, tests, errors, status, summary, handoff, and quality evidence.
Work State Tracks suspended or active work when there is useful next-action state.
Handoffs and Decisions Preserve factual continuity across sessions.
Failure Memory Stores observed failure patterns and known bad paths.
Execution Contracts Provide advisory first action, edit scope, validation expectation, and finalization expectation.
Continuity Quality Marks context fresh, stale, missing, obsolete, demoted, or unverified.
Continuity View Renders deterministic Markdown/Mermaid reports.
Doctor Gives read-only diagnostics and repair guidance.
RepoMap Optional structural file/symbol hints. Not required for the core lifecycle.
MCP Local stdio surface over the same runtime as the CLI.

Install vs init

aictx install prepares global/runtime setup such as workspace metadata, MCP runtime metadata, optional global Codex files, and optional RepoMap support.

aictx init prepares one repository. It may write .aictx/, generated agent instructions, repo-local MCP config, .gitignore managed blocks, Claude/Copilot/Codex integration files, and optional RepoMap artifacts.

See What AICTX writes.

Resume

At startup, the agent-facing continuity query is:

aictx resume --repo . --task "<task goal>" --json

resume may include:

resume is the canonical agent-facing continuity query. It does not replace finalization or persistence.

Finalize

After work, agents should close the loop:

aictx finalize --repo . --status success --summary "<what happened>" --json

Finalization records factual evidence and returns the compact AICTX summary that agents should append to the user-facing final response when available.

With --include-view, finalize can also generate Continuity View links.

Public, advanced, and legacy surfaces

Main product surface:

install, init, resume, finalize, doctor, view, clean

Advanced but valid surface:

mcp, portability, map, guard, steer

Legacy/internal compatibility surfaces are intentionally not part of the first-run path. They can exist for old integrations or diagnostics, but docs and generated guidance should keep users focused on the lifecycle above.

Agent integrations

All supported integrations should communicate the same model:

install, init, then let the agent work

When MCP tools are visible, agents should prefer aictx_resume and aictx_finalize. If MCP is unavailable, use CLI fallback. Generated instructions should not make users learn legacy memory subsystems.

Trust model

AICTX continuity is evidence, not truth.

Start here:

Core concepts:

Advanced: