AOCI‑CODE – Persistent, Git‑versioned code‑base index for AI coding agents

What it is

AOCI‑CODE is a small Go‑based command‑line tool and a local MCP (Model‑Control‑Protocol) server that creates a plain‑text index of a software project. The index records, for every source file, its purpose, its dependencies, the public symbols it provides and any non‑obvious constraints. The index lives next to the code, is version‑controlled with Git, and is kept up‑to‑date automatically as the code changes.

Why it matters for AI agents

• One‑shot understanding – An LLM‑based coding assistant (e.g., Claude Code, Cursor, OpenCode, Codex) can read the whole project in a single pass by loading the AOCI index instead of repeatedly scanning the repository.
• Fast hand‑over – When a new developer or a new agent takes over a codebase, they only need to point the agent at the existing index; the agent instantly knows each file’s role, contracts and constraints.
• Continuous maintenance – The MCP server watches the repo; after a change it flags the affected entries and the agent updates them, so the index stays aligned with the actual code.
• Local‑only, privacy‑first – All processing happens on the developer’s machine; no source code or credentials are sent anywhere.

Core concepts

Concept	Description
FRAS entry	One line per file: F (function/purpose), R (required reads), A (available symbols), S (safety constraints). Example: atomic.go[CG9L]: F:Provides durable replace CAS …
Root file (aoci.txt)	Declares which index files belong to the current “CognitionSet”.
Meta file (aoci.meta.txt)	Holds the tag dictionary, FRAS rules and authoring constraints.
Code file (aoci.code.txt)	The model‑generated FRAS entries for source files.
Database file (aoci.database.txt)	Optional table‑level entries for MySQL/PostgreSQL/openGauss.
MCP server	A local process that mediates between the coding agent and the index, handling init, scan, maintain, etc.

Typical workflow

1. Install the binary (download a signed release or make build).
2. Initialize the repository: aoci init --locale en-US --agent codex. This writes the configuration, .gitignore entries and empty index skeleton.
3. Scan the repo: aoci scan. The agent reads every managed file, the model writes FRAS entries, and the index files are created.
4. Start the UI (optional): aoci ui --detach --json – gives a web panel showing index health, coverage percentages, and pending updates.
5. Develop as usual. When code or tests change, the MCP server flags the impacted entries; the agent updates them automatically.
6. Verify alignment anytime with aoci verify or aoci check.

Supported environments

• Operating systems – Linux, macOS, Windows (single‑binary, CGO‑free).
• Agents – Any LLM‑based coding agent that can speak the MCP protocol (Codex, Claude Code, Cursor, OpenCode, etc.).
• Databases – MySQL, PostgreSQL, openGauss 6.0.5 (table‑level cognition optional).

How it fits into the AI‑toolchain

AOCI‑CODE sits between the LLM model and the codebase:

LLM model → (writes) → AOCI index (plain‑text) → MCP server → Coding agent → Code / Tests

The model only needs to generate concise FRAS entries; the agent consumes the index to plan changes, reducing context size and eliminating repeated repository scans.

Getting started (quick‑start snippet)

# 1. Download a signed release or build from source
# 2. Place the binary at a stable absolute path, e.g. /usr/local/bin/aoci
# 3. In the project root run:

aoci init --locale en-US --agent codex

aoci scan

# 4. Ask the agent to start the UI and build the index
First confirm the AOCI MCP server is connected, then build the AOCI index for this project.

The UI will return a link like http://127.0.0.1:8080/#/project showing coverage, pending updates and a searchable view of the FRAS entries.

License & status

• Version – v0.1.0‑rc17 (release candidate).
• License – Fair Source License 1.1 + MIT (FSL‑1.1‑MIT).
• Maturity – Early‑stage but already used on commercial codebases of up to 700 k lines.

---

All details above are taken directly from the repository’s README; no additional features are inferred.