AOCI-CODE

A persistent, Git-versioned map of your entire codebase — written by your coding agent, governed by a local MCP server. Agents read it once and know the system, instead of re-reading the repo on every task.

🇺🇸 English | 🇨🇳 简体中文

What it does

Build large systems without losing the plot. In Codex, Claude Code, Cursor, OpenCode, and similar agents, your agent starts every task already knowing the whole system: what each file is for, what it depends on, and what must not break. It stops searching and re-reading the codebase for every request. People who are not professional developers can keep iterating on their own systems; professional developers can hand the whole system to an agent and keep their attention on architecture and design.

Take over an existing system in one step. Point the agent at an existing codebase of up to about 500,000 lines and ask it to build the index. It reports how well it knows each area, then picks up development from there. The practical limit is the size of the index, not the line count: a 700,000-line commercial system is developed this way today, with an index of about 300K tokens.

Change people, agents, or conversations without starting over. The index lives in the repository next to the code and is versioned by Git. When a project changes hands, switches agents, or opens a new conversation, one read of the index picks up where things left off.

After the first index, maintenance is automatic. The MCP server detects code changes and issues the entries that need updating. The agent fills them in as it finishes each task, so the index matches the current code and you never stop to maintain it.

What it looks like

One line per file, written by the model from the actual source. This is a real entry from this repository's own index:

atomic.go[CG9L]: F:Provides durable replace CAS, create CAS, atomic writes, and no-clobber recovery moves | R:code:internal/fs/atomic_exchange_linux.go,code:internal/fs/atomic_exchange_windows.go,code:internal/fs/lock.go | A:AtomicWrite,AtomicWriteCAS,AtomicCreateCAS,AtomicMoveCAS | S:Native publication never degrades to an overwriting rename; on a race, unsafe type, or unverifiable bytes, preserve third-party state

F is what the file is responsible for, R is what you have to read along with it, A is what callers depend on, and S is what you cannot infer from the code but must not get wrong. The tag [CG9L] places the file by layer, domain, importance, and size. A few hundred lines like this cover a whole system, and an agent can read them in one pass. The entry format explains each field.

What to expect

The first index takes a while. The agent reads every managed file and writes one entry per file: about an hour per 200,000 lines of code, depending on the model and the agent's speed. It runs in batches and resumes where it stopped if interrupted.

Have a database? Index it too. MySQL and PostgreSQL are supported, and openGauss 6.0.5 with constraints. Build the code index first, then the database index. With code and table-level knowledge delivered together, the agent understands the system more completely.

Local only: read-only on your system, no Internet, no stored credentials. AOCI-CODE reads your source code and database table structures, never business data. It writes its index files and its own state inside the project directory, plus the status page's registration in your user cache directory. It never reaches the Internet and uploads nothing: the only connections it opens are to the database you declare, for catalog metadata, and to its own loopback status page. Database credentials are referenced by environment-variable name and never stored. The index text is written locally by your own agent through the model channel you already use; AOCI-CODE adds no new data exit.

Quick start

Give your agent the following instruction to download AOCI-CODE and wire it up. After you restart the agent, send the second instruction to build the index.

AOCI-CODE project: https://github.com/aoci-spec/aoci-code

Download the latest release package for this operating system and CPU architecture from
https://github.com/aoci-spec/aoci-code/releases, and follow the installation instructions
on the Release page to verify it. If no compatible release package exists, or if I
explicitly request the latest source, build it from the official repository.

After extracting the package, place aoci (aoci.exe on Windows) at a stable absolute path.
Then use that absolute path to do the following for my project:

1. Run init to initialize AOCI and integrate MCP for the current host; if this host does
   not write project configuration (Cursor, for example), give me the configuration I
   need to paste myself
2. Run scan

   scan takes its file inventory from Git, so do not add the cognition assets
   init writes (aoci.txt, aoci.meta.txt, aoci.code.txt, AGENTS.md) to .gitignore
   or .git/info/exclude — an ignored asset is silently skipped and the index
   cannot be built. Leave the host-config ignore init writes for itself as it is.

3. Tell me to restart the agent so the newly written MCP server takes effect

Stop after those three steps and do not build the index yet — I will tell you to continue
after the restart.

After restarting the agent, send this one:

First confirm the AOCI MCP server is connected, then build the AOCI index for this project. When it is complete, give me the AOCI panel link.

The agent starts the panel in the background with aoci ui --detach --json and hands you the link. AOCI panel covers what it shows and its other commands.

Why the restart: the index is written through AOCI's MCP tools, and the session that ran init has not loaded the MCP server init just wrote. A host that loads MCP servers dynamically may not need a restart; [Host integ