# AOCI-CODE caps repositories at 500,000 lines, then describes a 700,000-line one

> A Go CLI plus MCP server that has a coding agent write a one-line-per-file map of a repository into Git, and refuses to look at business data. The install is a prompt rather than a command, and three release candidates landed in five days.

**aoci-spec/aoci-code** — Distills code and database knowledge into a persistent, governed map of the entire repository—helping AI coding agents understand complex systems faster and carry development forward with greater precision.

- Repository: https://github.com/aoci-spec/aoci-code
- Stars: 754 · Forks: 126
- Language: Go
- License: NOASSERTION
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/aoci-spec-aoci-code

## The 500,000 line ceiling and the 700,000 line example

The adoption pitch has two numbers in it and they do not agree.

The first says you can point the agent at an existing codebase of up to about 500,000 lines and ask it to build the index. The second says the practical limit is the size of the index rather than the line count, and gives its own evidence: a 700,000-line commercial system is developed this way today, with an index of about 300K tokens.

So the worked example overshoots the stated ceiling by 200,000 lines. The two claims are reconcilable, since the second explicitly says line count is not the binding constraint, but they sit in adjacent paragraphs and the first reads as a hard number.

The index size is the number worth planning against. A few hundred lines of plain text cover a whole system, and that is what an agent reads in one pass before it starts work.

The build cost is given per unit of input: 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, which matters more than the total because this is an operation you may have to abandon and restart.

One line of output per input file. At 200,000 lines of code with an average of 30 lines a file, that is on the order of 6,700 entries to produce, one per file, all written through MCP tool calls.

## The quick start is a prompt to an agent, not an install command

There is no shell command in the README that installs this tool. The quick start is a block of natural-language instruction that you hand to your coding agent, and the agent does the installing.

The instruction names the project URL, tells the agent to download the latest release package for the current operating system and CPU architecture from the releases page, and to follow the installation instructions on the Release page to verify it. If no compatible package exists, or if you explicitly ask for the latest source, it builds from the official repository. Then the agent is told to place the binary, named `aoci` and `aoci.exe` on Windows, at a stable absolute path, and to run `init` with that path.

Two consequences. The verification steps are not in the README at all; they are on a release page that the README does not reproduce, so the README is not self-contained for anyone auditing it. And the first thing an agent does with an unknown binary is run it, on a machine, with an absolute path it chose.

There is a second prompt after the restart, asking the agent to confirm the MCP server is connected and then build the index, and to hand back the panel link. The panel is started in the background with `aoci ui --detach --json`.

Two more prompts exist for later. One builds the database index. One is for after context compaction, asking the agent to establish whole-framework cognition using only AOCI, to report its mastery of each area as a percentage, and to say whether it can take over development.

## The MCP server that init writes is not loaded in the session that ran init

The restart requirement is explained rather than apologised for. The index is written through AOCI's MCP tools, and the session that ran `init` has not loaded the MCP server that `init` just wrote. So the same conversation that installed the thing cannot use it, and you have to start a new one.

The documentation adds a useful qualifier: a host that loads MCP servers dynamically may not need the restart, and there is a section on host integration for telling which kind you have.

That qualifier is doing a lot of work, because the named hosts are Codex, Claude Code, Cursor and OpenCode, and whether each of them picks up a new server file mid-session is exactly the kind of detail that changes between releases.

The named hosts also frame the target user. The pitch covers two audiences at once: people who are not professional developers iterating on their own systems, and professional developers handing a whole system to an agent so they can keep their attention on architecture and design.

The stated host list is worth reading as a compatibility claim rather than a certification. Nothing in the document says which versions of which hosts were tested.

## go.mod requires the openGauss driver and immediately replaces it with a local copy

The Go module has seven direct dependencies, and one of them is immediately overridden.

The require block lists `gitcode.com/opengauss/openGauss-connector-go-pq` at v1.0.8, and the very next line is a replace directive pointing that module path at `./third_party/openGauss-connector-go-pq`, a directory in this repository. The version in the require line is therefore decorative; the build uses whatever is in `third_party/`. There is a `THIRD-PARTY-NOTICES` file at the top level, which is where a vendored replacement should be accounted for, and the makefile's `safety` target is described in its own comment as a scan of the project's public copy.

The database story is three drivers for three databases: `pgx/v5` at v5.11.0 for PostgreSQL, `go-sql-driver/mysql` at v1.10.1 for MySQL, and the vendored openGauss connector. The README states MySQL and PostgreSQL are supported and openGauss 6.0.5 is supported with constraints.

The rest of the module is small and current: the official Model Context Protocol Go SDK at v1.6.1, cobra at v1.10.2, pflag at v1.0.9 and `golang.org/x/sys` at v0.48.0.

The indirect list is where the age shows. `golang.org/x/crypto` is pinned to a pseudo-version dated 2021-07-11, `golang.org/x/xerrors` to one from 2020, and `jackc/pgservicefile` to mid-2024, while everything else sits at current versions.

## go.mod pins the toolchain to a patch release

The go directive reads `go 1.26.6`. Language version directives are usually a major and minor pair, and Go has allowed a patch component since 1.21, so this is legal but stricter than the usual form.

The effect is concrete: anyone on Go 1.26.5 cannot build this without upgrading first, even though nothing in the module plausibly needs a specific patch. It also means the toolchain line is doing double duty as a compatibility statement and a release-gate lock.

That matters more than usual here, because the makefile explicitly defends against the Go toolchain being missing from PATH. Each tool is resolved through a fallback chain: `go` from PATH, then `/usr/local/go/bin/go`, then the bare name. The comment explains why, noting that non-login automation shells may omit an installed Go toolchain from PATH.

The same pattern applies to `gofmt`, to `goreleaser` and to `syft`. Two of those four are worth singling out. `goreleaser` is the release builder, matching the `.goreleaser.yml` at the top level. `syft` is a software bill of materials generator, and its presence in the fallback chain means the build is expected to produce an SBOM rather than only a binary.

`staticcheck` is resolved the same way, and `BUILD_BIN` defaults to `build/aoci` with the platform executable suffix appended, so the output is a single file with no install step beyond copying it somewhere stable.

## Seventeen release candidates and no stable tag

Three of the visible release tags are consecutive candidates: v0.1.0-rc15 on 2026-09-25, rc16 on 2026-09-28 and rc17 on 2026-09-29. Three releases in five days, all at the same version with a different suffix.

That cadence is fine for a pre-1.0 tool, but it interacts with how the README tells you to install. The instruction is to download the latest release package, and the release notes are where the verification steps live. A project moving that fast is going to rewrite those notes more often than most users reread them.

The makefile's version handling is the interesting part. It prefers `git describe --tags --always --dirty`, so a build from a tagged commit gets the tag, an untagged commit gets a short hash, and a build with local modifications is marked dirty. The commit and a UTC timestamp are injected alongside it through linker flags into the CLI package, which means a binary can report what it was built from even when nothing recorded the build.

The comment above that block describes three commit gates in Chinese: `fast` as the normal commit gate, `full` as the complete confidence gate, and `release-check` as the stable release gate. Alongside them sit `build`, `test`, `vet` and `safety`.

A release candidate stream this dense with a `release-check` gate suggests the team knows the difference between a candidate and a release, and has not yet decided which one to ship.

## The repository indexes itself, and commits three index files at the root

The sample entry in the README is not invented. It says so, and it comes from this repository's own index, describing `atomic.go` and referencing three sibling files under an internal filesystem package for the Linux and Windows implementations plus a lock file.

The format is the whole idea. Four fields separated by pipes: `F` is what the file is responsible for, `R` is what you have to read alongside it, `A` is what callers depend on, and `S` is what you cannot infer from the code but must not get wrong. A bracketed tag places the file by layer, domain, importance and size, and in the example it reads `CG9L`.

The dogfooding is complete enough to check. Three index files are committed at the top level, `aoci.txt`, `aoci.code.txt` and `aoci.meta.txt`, beside a `.aoci/` directory. The published entry reads:

```text
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
```

Three index files at the root is also the clearest signal of how the format is meant to be split, since three variants of the same idea are being kept side by side rather than one.

The top level also holds `PATENTS`, `TRADEMARKS`, `NOTICE` and `THIRD-PARTY-NOTICES` alongside a `LICENSE`, while the repository itself records no identifiable licence. For a tool whose main asset is a derived text file, a patent grant and a trademark claim are worth reading before you adopt the index format in your own organisation.

Two more structural notes. The documentation is bilingual with `README.zh-CN.md` beside `README.md`, and the makefile's comments are written in Chinese, so a contributor who does not read it is working from uncommented build logic.

The `examples/` directory holds a single entry, a minimal repository, which is a small thing to ship for a tool whose first-run experience is a restart and an hour of indexing.

## Conclusion

AOCI-CODE is worth trying on a codebase your agents keep re-reading, and the honest parts of its design are the read-only claim, the credentials-by-name rule and the index living in Git where you can diff it. Two things to check before you commit. Your repository size, because the stated 500,000 line ceiling is exceeded by the tool's own worked example, so the real limit is the token size of the index and you should measure that. And the restart, because the MCP server that init installs is not loaded in the session that ran init, which is a strange first-run experience on any host that does not load MCP servers dynamically.

## FAQ

### How large a codebase can AOCI-CODE index?

The README describes roughly 500,000 lines as the ceiling for an existing codebase, then says the binding constraint is index size rather than line count and cites a 700,000-line commercial system indexed at about 300K tokens. Building the first index costs about an hour per 200,000 lines and resumes in batches if interrupted.

### How do I install AOCI-CODE?

There is no install command in the README. You hand your coding agent an instruction to download the latest release package for your operating system and CPU architecture from the releases page, follow the installation instructions on that page to verify it, place the binary at a stable absolute path, and run init with that path.

### Why does AOCI-CODE need an agent restart after init?

The index is written through AOCI's MCP tools, and the session that ran init has not loaded the MCP server that init wrote. A host that loads MCP servers dynamically may not need the restart, and the documentation has a host integration section for working out which case you are in.

### Does AOCI-CODE send my code or database contents anywhere?

The stated behaviour is local and read-only: it reads source code and database table structures but never business data, never reaches the Internet, and uploads nothing. Connections are limited to the database you declare for catalog metadata and to its own loopback status page. Credentials are referenced by environment-variable name and never stored.

### What does one AOCI-CODE index entry contain?

One line per file with four fields: F for what the file is responsible for, R for what to read alongside it, A for what callers depend on, and S for what cannot be inferred from the code but must not get wrong. A bracketed tag classifies the file by layer, domain, importance and size.

## Sources

- [aoci-spec/aoci-code on GitHub](https://github.com/aoci-spec/aoci-code)
- [Issues](https://github.com/aoci-spec/aoci-code/issues)
- [README](https://github.com/aoci-spec/aoci-code/blob/main/README.md)
- [Releases](https://github.com/aoci-spec/aoci-code/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/aoci-spec-aoci-code