aictx 4.7.1

Repo-local continuity runtime for coding agents

AICTX

Repo-local continuity runtime for coding agents.

AICTX lives inside your repository so each new coding-agent session can start from the operational state left by previous work: active task state, next action, known failures, decisions, execution evidence, structural repo hints, and branch-safe Work State.

Install it once, initialize the repo, then keep using your coding agent normally.

AICTX is Codex-first, Claude-aware, and generic-agent compatible.

Current documented implementation: 4.7.1

---

Why this exists

Coding agents are powerful, but most sessions still start cold.

They rediscover repository structure, repeat failed paths, lose track of what was already verified, and depend on chat history for unfinished work.

AICTX gives them a repo-local continuity layer.

---

What changes with AICTX

Without AICTX:

• the next session starts from a prompt and a fresh repo scan;
• failed approaches are easy to repeat;
• unfinished task state lives in chat history;
• the next action is easy to lose;
• branch switches can resume the wrong context.

With AICTX:

• the next session can load a compact continuity brief;
• active Work State preserves goal, hypothesis, files, next action, risks, and verified/unverified work;
• Failure Memory warns about known patterns;
• RepoMap can provide structural entry points so agents know where to look first;
• summaries preserve what changed and what can be reused;
• branch-safe loading avoids resuming active work on the wrong branch.

---

Core capabilities

Capability	What it does	Why it matters
Work State	Preserves the active task, hypothesis, next action, files, risks, and verification state	The next session knows what was in progress
Failure Memory	Stores observed command/test/build/type/lint failures as structured patterns	Agents can avoid repeating known mistakes
RepoMap	Optional Tree-sitter structural map of files and symbols	Agents get better “where should I look first?” context
Strategy Memory	Reuses successful prior execution patterns	Known-good approaches can be suggested again
Handoff / Decisions	Keeps operational summaries and explicit project decisions	Architecture and intent survive session boundaries
Execution Summary	Captures what happened at finalize time	The next session starts from factual continuity

Work State = what is currently in progress.
Failure Memory = what failed before.
RepoMap = where useful code likely lives.
Strategy Memory = what worked before.
Execution Summary = what changed in the last run.

---

Normal workflow

AICTX is designed to be agent-driven after setup.

From inside the repository, the normal setup is:

pip install aictx
aictx install
aictx init
aictx --version

aictx --version prints the installed CLI version so you can verify which AICTX release is active.

aictx init --repo . is the explicit form and is useful in scripts, CI, documentation, or when running from outside the target repository. When you are already inside the repo, aictx init is the simplest path.

After that, keep using your coding agent.

The generated repo instructions and hooks guide supported agents to call AICTX automatically. The user should not have to run AICTX command after command during normal work.

---

What the agent calls

In normal supported workflows, AICTX is runtime plumbing for the agent.

The agent or runner integration may call:

aictx internal boot --repo .
aictx internal execution prepare ...
aictx internal execution finalize ...

For wrapped execution it may use:

aictx internal run-execution --repo . --request "..." -- ...

For inspection or explicit guidance, it may call public surfaces:

aictx next --json
aictx map query "..."
aictx task status --json
aictx report real-usage

Manual commands remain available for debugging, demos, power users, and integrations, but the product experience is:

install -> init -> use your coding agent

internal boot is a runtime/bootstrap diagnostic surface. The compact user-visible startup continuity banner is surfaced through prepare/startup continuity as startup_banner_text.

See Installation.

Git-portable continuity

AICTX continuity can be made git-portable.

When enabled during aictx init, AICTX writes a selective .gitignore policy so a safe subset of canonical .aictx/ artifacts can be committed with the repo. Another machine can clone/pull, run aictx init, and continue with the same repo-local continuity.

Git is the transport. AICTX does not require cloud sync.

See Portability.

---

RepoMap has real weight

RepoMap is optional, but important.

Work State tells the agent what it was trying to do.
RepoMap helps the agent know where to continue.

When installed with aictx[repomap], AICTX can maintain a lightweight Tree-sitter-based structural index and expose file/symbol hints through:

aictx map status
aictx map refresh
aictx map query "startup banner"

AICTX works without RepoMap. With RepoMap enabled, the “cold repo discovery” part of agent sessions has a stronger structural starting point.

See RepoMap.

---

Supported agent model

AICTX is runner-aware, not runner-locked.

Codex-first

Primary target:

• AGENTS.md repo instructions;
• optional global Codex install with aictx install --install-codex-global;
• CLI/runtime JSON contract;
• startup and summary guidance.

Claude-aware

Supported through:

• CLAUDE.md;
• .claude/settings.json;
• .claude/hooks/aictx_*.py.

Generic fallback

Any coding agent can use AICTX if it can read repo instructions, call CLI commands, and consume JSON/Markdown output.

---

What you see

Startup continuity

AICTX produces a compact canonical startup banner in English. Supported agents may localize labels and connective wording to the current user language, but must preserve facts, file paths, commands, flags, test names, package names, and code identifiers.

Canonical runtime example:

codex@aictx · session #40 · awake

Resuming: branch-safe Work State finalize behavior.
Last progress: finalize behavior aligned with tests.
Entry point: tests/test_work_state_runtime.py
Active task: Improve public docs. Next: update installation guide.

Optional agent-rendered localized example:

codex@aictx · sesión #40 · despierto

Retomando: branch-safe Work State finalize behavior.
Último avance: finalize behavior aligned with tests.
Punto de entrada: tests/test_work_state_runtime.py
Tarea activa: Improve public docs. Siguiente: update installation guide.

Semantics:

• Next: means real pending work, for example next_steps, open_items, blocked items, or an active Work State next_action.
• Entry point: means a technical resume location from recommended_starting_points when there is no real pending work.

Final summary

After execution, AICTX returns a compact factual summary for the agent’s final response.

Example shape:

AICTX summary

Context: reused previous strategy + loaded handoff/decisions/preferences.
Map: RepoMap quick ok.
Saved: updated handoff.
Entry point: src/aictx/continuity.py, src/aictx/middleware.py.
Details: [last_execution_summary.md](.aictx/continuity/last_execution_summary.md)

---

Branch-safe Work State

AICTX stores minimal git context with Work State:

• branch;
• HEAD commit;
• dirty flag;
• changed files;
• capture timestamp.

Loading rules:

• same branch -> load;
• different branch + saved commit is ancestor of current HEAD -> load with warning;
• different branch + saved commit is not ancestor -> skip;
• dirty saved state + different branch -> skip;
• old Work State or non-git repo -> load conservatively.

This is safety, not branch-aware task management.

---

Artifact contract

The stable repo-local continuity artifact contract in 4.7.1 is:

.aictx/continuity/session.json
.aictx/continuity/handoff.json
.aictx/continuity/decisions.jsonl
.aictx/continuity/semantic_repo.json
.aictx/continuity/dedupe_report.json
.aictx/continuity/staleness.json
.aictx/continuity/continuity_metrics.json
.aictx/strategy_memory/strategies.jsonl
.aictx/failure_memory/failure_patterns.jsonl
.aictx/metrics/execution_logs.jsonl
.aictx/metrics/execution_feedback.jsonl
.aictx/tasks/active.json
.aictx/tasks/threads/*

Optional or latest-run artifacts may also appear:

.aictx/continuity/handoffs.jsonl
.aictx/continuity/last_execution_summary.md
.aictx/area_memory/areas.json
.aictx/repo_map/config.json
.aictx/repo_map/manifest.json
.aictx/repo_map/index.json
.aictx/repo_map/status.json

---

Who should use AICTX?

AICTX is for developers who repeatedly use coding agents in the same repository and want continuity without hidden cloud memory.

It is especially useful if you want agents to preserve:

• active task state;
• prior failures;
• verified and unverified work;
• relevant files and commands;
• repo structure hints;
• decisions and handoffs;
• next actions.

AICTX is not:

• a hosted agent platform;
• a dashboard or task manager;
• a vector database;
• hidden cloud memory;
• an autonomous repo repair system;
• a guarantee of productivity or token savings.

---

Documentation

Start here:

• Installation
• Quickstart
• Technical overview

Core concepts:

• Work State
• RepoMap
• Failure Memory
• Strategy Memory
• Handoffs and Decisions
• Execution Summary

Operations and trust:

• Usage
• Cleanup
• Safety
• Limitations
• Upgrade
• Demo
• Release checklist

---

Current limits

AICTX improves continuity only when agents or integrations cooperate with the runtime contract. File access, commands, tests, and failures are strongest when passed explicitly or captured through wrapped execution.

AICTX does not claim measured productivity gains, guaranteed speedups, or automatic correctness.

It makes continuity visible, inspectable, and reusable.