AOCI-CODE MCP
An MCP server and CLI in Go: the agent keeps an index of code and database schema in the repository, versions it in Git and reads it whole before each task
- 1,721 ★ on the repository
- Last commit
Broad access
Why this level
- Writes index files, agent rules and an `.aoci/` directory into the repository, and with `--hooks` edits the agent settings
- Connects to the database you declare through a connection string from an environment variable and reads table metadata
- Starts background processes: the MCP server and a local panel on a loopback address
Install
- Works in
Manual install
git clone https://github.com/aoci-spec/aoci-code.git && cd aoci-code && mkdir -p build && make buildBuilding from source needs the Go version declared in `go.mod` and `make`. Then place `aoci` at a stable absolute path.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Writes index files, agent rules and an `.aoci/` directory into the repository, and with `--hooks` edits the agent settings
- Connects to the database you declare through a connection string from an environment variable and reads table metadata
- Starts background processes: the MCP server and a local panel on a loopback address
This is third-party code. Review the repository files before installing.
What it does
AOCI-CODE is a local MCP server and a Go CLI, `aoci`, that helps an agent keep a map of the whole codebase and database schema in the repository. The model writes the map itself: one line per file or table saying what the file is responsible for, what it connects to, what callers depend on and what must not break. The index lives in plain text files next to the code, is versioned by Git and is tied to no model or session. A new session or another agent reads it whole and carries on from the same place. Setup takes four steps. `aoci init` creates the root file `aoci.txt`, `aoci.meta.txt` with the tag dictionary and an empty `aoci.code.txt`, adds rules for the agent and registers the MCP server in the configuration of Claude Code, Codex or OpenCode. For Cursor the command only prints a configuration snippet. `aoci scan` builds the baseline from the file list in Git. After the agent restarts, you ask it to build the index: it reads source, tests and configuration and writes the entries through the server's tools. Then `aoci verify` and `aoci check` confirm that the index and the code match. After that the index maintains itself without you. The server notices code changes and issues the entries that need updating, and the agent fills them in when the task is done. The server has nine tools over stdio: reading rules, the overview, entries and search, index maintenance and supporting reports. For PostgreSQL and MySQL databases, and openGauss 6.0.5, a separate table index is built from catalog metadata. The `aoci ui` command opens a local panel showing the index, the share of code it covers, drift and running servers.
Who it is for. For developers who work on large projects with Claude Code, Codex, Cursor or OpenCode, switch agents and sessions, and do not want to explain the system from scratch every time.
Good fit when
- A project has changed hands and the agent needs a picture of the whole system before the first edit
- Every new session spends time rereading the repository
- Several agents work on the code and need shared memory that you can diff and roll back through Git
- A PostgreSQL or MySQL database sits next to the code and the agent needs the links between code and tables
- You need a check that the description of the system has not fallen behind the code
Not a fit when
- You need exact lookup of calls and symbols: code graphs such as CodeGraph do that, and the description advises using both
- The project is small or just starting: the author suggests bringing the index in at roughly 10,000–30,000 lines
- Your database is MariaDB: AOCI-CODE does not support it, and MySQL must be 5.7.6 or newer
- You want to build it into a commercial product or service that substitutes for AOCI-CODE itself: the FSL-1.1-MIT license forbids that use
Example request
Check that the AOCI server is connected, build the index for this project and give me the panel linkMCP
- Transport
- stdio
- Authentication
- not required
Environment variables
AOCI_DB_PRIMARY_DSNsecret- Connection string for the source with the ID primary; needed only for the database index, the string itself is not stored
Limitations
- Version 0.1.0-rc21 is a release candidate. The author recommends building from source or taking a signed package from the release page and following the verification procedure in the installation guide.
- The first index takes a while: about an hour per 200,000 lines of code, depending on the model and the agent's speed. It runs in batches and resumes after an interruption, and the limit is the size of the index, not the line count.
- The license is FSL-1.1-MIT. The source is open, but direct use in a competing product is forbidden. Internal use, education and research without commercial purpose are allowed.
- An all-green result means the structure and rules hold, not that every statement the model wrote is correct. The content of the entries is the model's responsibility.
- `init` writes the agent configuration with absolute paths of this machine, so it must not be committed. The index files `aoci.txt`, `aoci.meta.txt` and `aoci.code.txt` must not go into `.gitignore`, or `scan` skips them.
How to disable. Remove the `aoci` server entry from the agent configuration: `.mcp.json`, `.codex/config.toml`, `opencode.json` or `.cursor/mcp.json`. If you installed hooks, delete them in the same place. Delete the index files `aoci.txt`, `aoci.meta.txt`, `aoci.code.txt` and the `.aoci/` folder by hand, they are ordinary repository files. The background panel is stopped with `aoci ui --stop`.
FAQ
How is AOCI-CODE different from CodeGraph?
CodeGraph parses code into a graph of symbols and calls and returns exact fragments on request. AOCI-CODE has the model write one line per file and table, and the agent reads the whole index before the task begins. The author advises using both: the index to know the system, the graph for exact code while working.
What data goes to the internet?
According to the project description, none. AOCI-CODE reads source and table structure but not business data, writes only to the project directory and the panel's cache, and opens connections only to the database you declare and to the local panel. The index text is written by your agent through the model channel you already use.
How do I build a repository map for Claude Code and Codex?
Run `aoci --repo . init --locale en-US --agent codex`, then `aoci --repo . scan`, restart the agent and ask it to build the index. For Claude Code pass `--agent claude`, and `--hooks` adds an optional guard before writes.
How do I add a database to the index?
Build the code index first, then declare the source with `aoci database` and pass the connection string through an environment variable. The string itself is not stored. If you omit `--credential-env`, the variable name is derived from the source ID: for `primary` it is `AOCI_DB_PRIMARY_DSN`.
What if the index falls behind the code?
Run `aoci --repo . verify` and `aoci --repo . check`: they report missing, orphan and stale entries. `aoci index agent guide` gives the next steps, and you do not need to write your own wrapper script.
Discussion
No questions or reviews yet.
Related
MCP serversLocal code graph for agents: an MCP server returns entry points, symbol links and change impact in one call
A Python terminal coding agent in the manner of Claude Code: reads the repository, edits files, runs commands, with memory, sub-agents and MCP
CodeGraph (Rust)
codegraph-rust
A Rust code graph for agents: four MCP tools show what an edit will touch, how the architecture fits together and where the fragile spots are
A local codebase index for agents: hybrid search, dependency graphs and change impact analysis
codesight maps a project in one run: routes, DB models, dependencies, env vars. It gives the map to an agent as files or through an MCP server
An MCP server that builds a code graph of functions, classes, calls and routes and answers the agent's structural queries locally
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| AOCI-CODE (this entry) | no | not required | 1,721 | |
| CodeGraph | no | not required | 74,886 | a graph of symbols and calls that returns exact code fragments on request |
| GitNexus | no | not required | 48,007 | builds a knowledge graph of the code and returns call links and the blast radius of edits |
| Repowise | yes | not required | 7,887 | a local index with ten MCP tools: dependency graph, git history and code health |
README in short
The repository holds the Go source in `cmd/aoci` and `internal`, an example in `examples/minimal-repository`, documentation in `docs`, a changelog, security and contribution policies, trademark and patent notices and the project's own index in `aoci*.txt`. The description, in English and Chinese, explains the principle, shows a sample entry and covers the entry format, integration with each agent, the panel and a command table. Separate sections compare the server with a repo map, RAG, LSP and a code graph.