Aictx – Repo-local continuity runtime for coding agents

Notifications You must be signed in to change notification settings

Fork 1

Star 10

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

150 Commits

150 Commits

.github

.github

bin

bin

docs

docs

scripts

scripts

src/aictx

src/aictx

tests

tests

.gitignore

.gitignore

AGENTS.md

AGENTS.md

CHANGELOG.md

CHANGELOG.md

CONTRIBUTING.md

CONTRIBUTING.md

LICENSE

LICENSE

Makefile

Makefile

README.md

README.md

note_template.md

note_template.md

pyproject.toml

pyproject.toml

Repository files navigation

Repo-local continuity runtime for coding agents.

AICTX lets a coding agent start the next session 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: 6.3.0

Product promise

AICTX gives coding agents a small, repo-local memory loop:

resume useful context -> do the work -> finalize factual evidence -> help the next session

It is for developers who repeatedly use coding agents in the same repository and want less cold-start rediscovery, explicit next actions, remembered failures, reusable successful strategies, and inspectable local artifacts instead of hidden cloud memory.

It is not a generic token compressor, autonomous coding system, hosted agent platform, or correctness guarantee.

AICTX combines continuity memory with structural repo lookup: Work State tells the agent what was happening; optional RepoMap tells it where to look first.

See it in 30 seconds

Without AICTX, the next agent session usually starts cold:

User: continue parser work Agent: scans repo, opens README, searches files, rediscovers tests...

With AICTX, the agent can start from a fresh resume capsule:

aictx resume --repo . --task "continue parser work" --json

Example shape:

Resuming: parser edge cases Last progress: BLOCKED status added Next: expand tests/test_parser.py Known failure: pytest unavailable outside .venv Suggested command: .venv/bin/python -m pytest -q

The exact fields depend on what previous sessions actually recorded. AICTX does not invent missing facts.

Demo result

In a two-session coding task, AICTX helped the second session resume from the intended work surface instead of rediscovering the repo.

Session 2 metric Without AICTX With AICTX

Files explored 10 5

Files edited 3 1

Commands run 15 8

Exploration before first edit 15 6

Time to complete 1'59'' 1'12''

First relevant file README.md tests/test_parser.py

This is not a universal benchmark. It is an observable continuity demo. See Demo.

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 makes that continuity repo-local, inspectable, and reusable.

Install

From inside the repository:

pip install aictx aictx install aictx init aictx --version

After that, keep using your coding agent.

The generated repo instructions and hooks guide supported agents to call AICTX automatically. The normal user experience is:

install -> init -> use your coding agent

See Installation and Quickstart.

How it works

At normal task startup, supported agents use one continuity query:

aictx resume --repo . --task "" --json

--task should contain only the work goal. --task is the only normal resume input in v6; legacy --request startup input has been removed.

After work, supported agents finalize factual evidence:

aictx finalize --repo . --status success|failure --summary "" --json

In JSON mode, resume also includes bounded loaded_context metadata that explains why Work State, carryover, failures, handoffs, decisions, strategies, and RepoMap hints were selected. Each item includes role/relevance metadata such as role, selection_reason, confidence, staleness, and related_paths. It is additive inspection/debugging metadata, not proof of correctness and not hidden agent reasoning.

When RepoMap is enabled and indexed, resume can also include compact structural_entry_points and structural_context. RepoMap status separates provider, index, query, and refresh availability, so an existing index can remain queryable even if the provider is unavailable. Execution contracts may include expected_first_files, and finalize can record structural_alignment. RepoMap remains optional; AICTX continues to work without it.

The runtime loop is:

resume capsule -> work -> finalize evidence -> next resume

Technical integrations can also use wrapped/internal execution surfaces. See Technical overview and Usage.

Core capabilities

Capability What it does Why it matters

Work State Preserves active task, hypothesis, files, next action, 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 compact structural entry points for “where should I look first?”

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

Contract Compliance Audits first action, edit scope, validation, and structural alignment Gaps can carry over into Work State instead of disappearing

Doctor Read-only repo/runtime diagnostic with aictx doctor --repo . --json; add --release-readiness for strict aictx release-gate checks Support uses a general repo diagnostic while releases keep stricter checks

Resume capsule Compiles continuity into one agent brief Agents do not need to discover AICTX internals at startup

How AICTX handles stale context

AICTX does not inject one permanent memory dump into every session.

Each task gets a fresh resume capsule built from repo-local artifacts: Work State, latest execution summary, decisions, known failures, strategy hints, and optional RepoMap data.

Old context is treated as context, not truth:

Work State is branch-safe.

Failures and strategies are observed evidence, not absolute instructions.

Resume capsules are regenerated per task.

Dedupe and staleness metadata help keep continuity bounded.

Missing or unsafe context is skipped, warned about, or marked not_evaluated rather than invented.

See Limitations and Technical overview.

Supported agents

AICTX is runner-aware, not runner-locked.

Codex-first: AGENTS.md, optional global Codex setup, CLI/runtime JSON contract.

Claude-aware: CLAUDE.md, .claude/settings.json, .claude/hooks/aictx_*.py.

Generic fallback: any agent that can read repo instructions, run CLI commands, and consume JSON/Markdown.

What AICTX is not

AICTX is not:

a hosted agent platform;

a dashboard or task manager;

a vector database;

hidden cloud memory;

an autonomous repo repair system;

a sandbox or enforcement layer;

a guarantee of productivity, token savings, speedups, or correctness.

Artifact contract

The stable repo-local continuity artifact contract in 6.3.0 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/continuity/contracts/* .aictx/strategy_memory/strategies.jsonl .aictx/failure_memory/failure_patterns.jsonl .aictx/metrics/execution_logs.jsonl .aictx/metrics/execution_feedback.jsonl .aictx/metrics/contract_compliance.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/continuity/resume_capsule.md .aictx/continuity/resume_capsule.json .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

For lifecycle details, startup banner semantics, branch-safe loading rules, internal runtime commands, and compliance auditing, see Technical overview.

Documentation

Start here:

Installation

Quickstart

Demo

Technical overview

Core concepts:

Work State

RepoMap

Failure Memory

Strategy Memory

Handoffs and Decisions

Execution Summary

Execution Contracts and Compliance

Doctor diagnostics

Operations and trust:

Usage

Cleanup

Safety

Limitations

Upgrade

Release checklist

Contributing

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.

About

Repo-local continuity runtime for coding agents. Helps new sessions continue prior work with remembered decisions, failures, and repo context.

Topics

python

open-source

ai

portable

developer-tools

ai-agents

ai-tools

llm-tools

llm-agents

context-management

coding-agents

context-engineering

continuity-ai

agent-continuity

repo-local

repo-native

Resources

Readme

License

MIT license

Contributing

Contributing

Uh oh!

There was an error while loading. Please reload this page.

Activity

Stars

10 stars

Watchers

1 watching

Forks

1 fork

Report repository

Releases 32

v6.3.0

Latest

May 13, 2026

+ 31 releases

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

Python 99.5%

Other 0.5%