View on GitHub

AICTX

Repo-local continuity runtime for coding agents

RepoMap

RepoMap is AICTX’s optional structural lookup layer.

It helps answer:

Where should the agent look first?

Work State tells the agent what was happening. RepoMap helps locate relevant files and symbols.

What RepoMap does

When enabled, RepoMap can maintain a lightweight structural map of a repository using Tree-sitter support.

It can expose:

Commands:

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

RepoMap in resume

When RepoMap is enabled and indexed, aictx resume can include structural entry points for the current task:

aictx resume --repo . --task "improve startup banner handling"

Output may include:

Structural entry points:
- src/aictx/middleware/__init__.py
  symbols: prepare_execution
  reasons: repo_map:symbol_match

In JSON mode, resume exposes the same bounded hints as structural_entry_points plus a compact structural_context status. Execution contracts can also include expected_first_files so finalize/contract compliance can record structural_alignment.

RepoMap remains optional. If it is disabled, unavailable, stale, or unindexed, AICTX still loads Work State, Handoffs, Decisions, Failure Memory, Strategy Memory, and the rest of the continuity capsule.

Installation

pip install "aictx[repomap]"
aictx install --with-repomap
aictx init

Check status:

aictx map status --json

Status separates provider/refresh capability from index/query capability:

{
  "provider_available": false,
  "index_available": true,
  "query_available": true,
  "refresh_available": false,
  "last_refresh_status": "skipped",
  "files_indexed": 167,
  "symbols_indexed": 1665
}

Why it matters

Agents often spend time rediscovering where relevant code lives.

RepoMap gives AICTX a structural source for entry-point hints:

Work State -> continue this task.
Failure Memory -> avoid this known problem.
RepoMap -> start looking here.

Runtime artifacts

RepoMap may create:

.aictx/repo_map/config.json
.aictx/repo_map/manifest.json
.aictx/repo_map/index.json
.aictx/repo_map/status.json

If Tree-sitter support is unavailable, RepoMap refresh can remain unavailable while the rest of AICTX still works. If a prior index exists, query can still be available even when provider/refresh is not.

Limits

RepoMap: