# AI use cases for Aoci Code (aoci-spec/aoci-code)

Repo: [aoci-spec/aoci-code](https://github.com/aoci-spec/aoci-code) | Use cases: 4 | Page: https://dedupedai.com/use-cases/aoci-spec-aoci-code/

AOCI-CODE is a local-first MCP server and Go CLI that has your coding agent write a Git-versioned index of your codebase and optional database schema, which agents read before they change anything.

This file holds every use case of this repo. Each one starts with a "## " heading and ends with its URL.

- Take over an existing codebase with an agent in one pass: https://dedupedai.com/use-cases/aoci-spec-aoci-code/take-over-existing-codebase-in-one-step/
- Resume a project in a new agent or chat without starting over: https://dedupedai.com/use-cases/aoci-spec-aoci-code/hand-off-project-to-new-agent-or-session/
- Index PostgreSQL or MySQL table structures next to the code: https://dedupedai.com/use-cases/aoci-spec-aoci-code/index-database-schema-alongside-code/
- Keep the codebase index current as the agent changes code: https://dedupedai.com/use-cases/aoci-spec-aoci-code/keep-index-aligned-after-each-change/

## How to take over an existing codebase with an agent in one pass with Aoci Code

Repo: [aoci-spec/aoci-code](https://github.com/aoci-spec/aoci-code) | Difficulty: Intermediate | Time: 1 hour 30 minutes | Basis: From the README

Build a Git-versioned index of a codebase of up to about 500,000 lines so the agent can start working from known context.

**Who it is for:** A developer or team lead who inherits a large existing system and needs an agent to learn it quickly before making changes.

**The problem:** Agents re-read and re-search the repository for every task, and a new project owner has no written map of what each file does or what must not break.

**The outcome:** An index with one entry per managed file, a coverage report of how well the agent knows each area, and a link to the AOCI panel for review.

### Steps

1. Download the latest release package for your operating system and CPU from https://github.com/aoci-spec/aoci-code/releases and verify it using the installation guide.
2. Place aoci (aoci.exe on Windows) at a stable absolute path, then run (inferred) `aoci init` in the project to set up AOCI and MCP for your host. (inferred, check the README)
3. Run (inferred) `aoci scan` and make sure the AOCI cognition files are not ignored by .gitignore or .git/info/exclude. (inferred, check the README)
4. Restart the agent so the new MCP server loads, then send the build instruction to build the index.
5. Run `aoci ui --detach --json` (or ask the agent to) to open the AOCI panel and review coverage by area.

### Prompt to paste into your agent

```text
In the repo <project-path>, confirm the AOCI MCP server is connected, then build the AOCI index for the whole project. Report the coverage level for each area and give me the AOCI panel link. Verify that aoci.txt and aoci.code.txt exist after the build.
```

### Caveat

The first index takes about an hour per 200,000 lines of code, depending on the model and agent speed, and the index quality depends on what the agent writes.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/aoci-spec-aoci-code/take-over-existing-codebase-in-one-step/

## How to resume a project in a new agent or chat without starting over with Aoci Code

Repo: [aoci-spec/aoci-code](https://github.com/aoci-spec/aoci-code) | Difficulty: Beginner | Time: 15 minutes | Basis: From the README

Use the committed index so a new agent, host, or conversation picks up the system context in one read.

**Who it is for:** A developer switching to a different coding agent, or opening a fresh conversation after context was compacted on a project that already has an index.

**The problem:** Each new session or agent has to re-learn the system from scratch, which costs time and produces inconsistent changes.

**The outcome:** The agent reports its mastery of each area as a percentage and states whether it can take over development from the index alone.

### Steps

1. Confirm the index files (aoci.txt, aoci.meta.txt, aoci.code.txt) are committed in the repository next to the code.
2. Open the project in the new agent or start a new conversation with the host that has the AOCI MCP server configured.
3. Send the rebuild instruction: "Using only AOCI, establish whole-framework cognition of this project, tell me your mastery of each area as a percentage, and whether you can take over development."
4. Review the percentages, and ask the agent to fill in any weak area from source before assigning it work.

### Prompt to paste into your agent

```text
Using only the AOCI index in <project-path>, describe the system, report your mastery of each area as a percentage, and say whether you can take over development. List any area below 80 percent and the source files you would read first.
```

### Caveat

The index is only as current as the last aligned update, so an agent should check it against source before relying on an area that has changed recently.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/aoci-spec-aoci-code/hand-off-project-to-new-agent-or-session/

## How to index PostgreSQL or MySQL table structures next to the code with Aoci Code

Repo: [aoci-spec/aoci-code](https://github.com/aoci-spec/aoci-code) | Difficulty: Advanced | Time: 1 hour 15 minutes | Basis: From the README

Add a table-level database index so the agent sees both code and schema before it changes either.

**Who it is for:** A developer whose application logic depends heavily on database tables and who wants the agent to understand the schema before writing queries or migrations.

**The problem:** An agent that reads only code can miss table relationships and constraints, which leads to queries or changes that break the data model.

**The outcome:** A separate table-level index (aoci.database.txt) built from catalog metadata, delivered together with the code index.

### Steps

1. Finish the code index first, since the README recommends building it before the database index.
2. Declare the database source as described under Database Cognition in the AOCI-CODE README.
3. Set the connection-string environment variable in the host environment. AOCI stores no credentials and references them only by variable name.
4. Send the instruction: "Build the AOCI database index for this project."

### Prompt to paste into your agent

```text
In the repo <project-path>, using the declared PostgreSQL or MySQL source and its connection-string environment variable, build the AOCI database index. Confirm that aoci.database.txt was written and that no credential value appears in any AOCI file.
```

### Caveat

MariaDB is not supported, and MySQL must be 5.7.6 or later.

Risk, credentials: The database connection string must be provided through an environment variable in the host, and the database user should have only the read access needed for catalog metadata.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/aoci-spec-aoci-code/index-database-schema-alongside-code/

## How to keep the codebase index current as the agent changes code with Aoci Code

Repo: [aoci-spec/aoci-code](https://github.com/aoci-spec/aoci-code) | Difficulty: Intermediate | Time: 30 minutes | Basis: From the README

Let the MCP workflow flag changed files and have the agent update their entries after each verified task.

**Who it is for:** A developer who runs many agent tasks on one project and does not want to stop and maintain the index by hand.

**The problem:** Code changes make the index stale, and manual upkeep is easy to skip, so later agents read outdated descriptions.

**The outcome:** After each verified change, the affected entries are updated and the index returns to an aligned state.

### Steps

1. Complete the first index build so every managed object has an entry.
2. Ask the agent to make a change as usual, with no separate index instruction.
3. Let the MCP server detect the changed files and let the agent update the affected entries after tests pass.
4. Review the Git diff of aoci.code.txt with the code diff before committing.

### Prompt to paste into your agent

```text
In the repo <project-path>, make the requested change, run the tests, then update the AOCI entries for every changed managed file so the index is aligned. Report the list of updated entries and confirm the index is aligned.
```

### Caveat

The README describes maintenance as automatic, but the agent still writes the entries, so the diff should be reviewed for accuracy.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/aoci-spec-aoci-code/keep-index-aligned-after-each-change/