# RepoPrimer

**English** · [简体中文](README.zh-CN.md)

**Fresh project context for every coding agent.**

RepoPrimer is a local-first, read-only project handoff layer. It combines the
Markdown documentation you already maintain with live Git state, then exposes
a compact startup brief to Codex, Claude, Cursor, and other MCP-compatible
coding agents.

<p align="center">
  <img src="https://raw.githubusercontent.com/repoprimer/repoprimer/main/.github/assets/demo.svg" alt="repoprimer context output: a compact brief with project state, tasks, decisions, and live Git status" width="720">
</p>

One `repoprimer context` call returns a bounded startup brief — project state,
open tasks, accepted decisions, and live Git status. On this repository the
compact brief measures about 3 KB (≈800 tokens, within the 6,000-character
default budget) instead of a multi-turn cold-start exploration.

> Status: early development. The npm package has not been published yet. The
> package commands below describe the intended public interface; use the
> source workflow while developing locally.

## Why RepoPrimer?

Coding agents repeatedly spend time rediscovering the same facts: what the
project does, what changed recently, what is in progress, and which decisions
must not be revisited. General-purpose AI memory products solve a broader
problem. RepoPrimer deliberately solves one narrow one:

> Before an agent starts work, tell it where this repository is now.

RepoPrimer is designed to be:

- **Local-first:** project files and the registry stay on your machine.
- **Read-only at runtime:** MCP tools do not modify project files or Git state.
- **Markdown-native:** no database, embeddings, or proprietary storage format.
- **Live:** the handoff includes current Git state rather than only cached notes.
- **Small:** four MCP tools, bounded responses, and no model API dependency.
- **Portable:** one context source can serve multiple MCP-compatible agents.

## How it works

```text
existing Markdown docs + live Git state
                    |
                    v
           compact project context
                    |
                    v
      Codex / Claude / Cursor / other MCP clients
```

RepoPrimer does not try to remember every conversation and does not replace a
knowledge base. It reads the project facts you choose to register and returns
only the context an agent asks for.

## MCP tools

The public MCP surface is intentionally limited to four read-only tools:

| Tool | Purpose |
| --- | --- |
| `list_projects` | Discover registered projects and their basic health. |
| `get_project_context` | Build a compact handoff from project docs and live Git state. |
| `search_project` | Search registered project Markdown and return bounded snippets. |
| `get_document` | Read one allowed project document with an optional size limit. |

Tools accept project identifiers, not arbitrary filesystem paths. RepoPrimer
resolves and validates paths against the local registry before reading.

## Quick start

### Public package

The current release is a pre-release published under the `alpha` dist-tag, so
install it with `@alpha` rather than `@latest`.

Initialize or register a project explicitly:

```sh
npx -y @repoprimer/mcp@alpha init
npx -y @repoprimer/mcp@alpha context
```

Add the MCP server to Codex:

```sh
codex mcp add repoprimer -- npx -y @repoprimer/mcp@alpha serve
```

For long-lived MCP configuration, pin an exact tested version instead of a
moving dist-tag.

### Local development

RepoPrimer requires Node.js 22 or 24.

```sh
git clone https://github.com/repoprimer/repoprimer.git
cd repoprimer
npm install
npm test
node dist/cli.js doctor
node dist/cli.js serve
```

## Project documents

RepoPrimer works with existing Markdown conventions. A minimal project can use:

```text
docs/
|-- PROJECT_STATE.md
|-- TASKS.md
`-- DECISIONS.md
```

Projects are not required to adopt those exact filenames. A project config can
map existing files such as `AGENTS.md`, `CLAUDE.md`, ADRs, or a Memory Bank into
the document set that RepoPrimer may read.

Generated context is assembled on demand. It is not another source of truth.

## Read-only and privacy boundaries

The MCP server:

- reads only registered projects and configured documents;
- reads Git metadata through bounded, non-mutating commands;
- does not write project files or alter the working tree;
- does not call model APIs, upload content, or collect telemetry;
- does not require a background database or cloud account.

The CLI has a separate, explicit setup boundary: commands such as `init`, `add`,
and `remove` may update RepoPrimer configuration or its user-level registry.
They are never invoked implicitly by an MCP read tool.

## Scope

RepoPrimer v0.1 focuses on project discovery, live context, document retrieval,
and text search. The following are intentionally out of scope:

- conversation capture and autonomous memory writes;
- embeddings, vector databases, or knowledge graphs;
- cloud sync, accounts, teams, or a hosted service;
- a web UI or IDE-specific extension;
- source-code indexing or autonomous repository analysis;
- model inference, API keys, or telemetry.

See [Architecture](docs/ARCHITECTURE.md), [Decisions](docs/DECISIONS.md), and
[Tasks](docs/TASKS.md) for the current design and implementation status.

## FAQ

### Why not just let the agent explore the repository itself?

It can, and RepoPrimer does not prevent that. The difference is the first
turn: exploration is re-run in every session by every agent, varies between
runs, and spends context-window tokens on rediscovery. RepoPrimer makes the
first turn deterministic and bounded — every agent starts from the same brief
within a fixed character budget, and deeper reads remain available through
`get_document` and `search_project`.

### How does this relate to CLAUDE.md or AGENTS.md?

They are complementary. Those files hold durable instructions for one
repository, read by the agents that support them. RepoPrimer adds what a
static file cannot: live Git state, a multi-project registry, bounded
responses, and one context source shared by every MCP-compatible agent. A
project config can map `CLAUDE.md` or `AGENTS.md` into the document set
RepoPrimer serves.

## Contributing

RepoPrimer is being prepared as an independent open-source project. Please read
[CONTRIBUTING.md](CONTRIBUTING.md) before proposing a change and follow the
[Code of Conduct](CODE_OF_CONDUCT.md). Security issues should follow
[SECURITY.md](SECURITY.md), not the public issue tracker.

English is the canonical language for repository metadata and project
governance. The complete Simplified Chinese README provides a secondary
onboarding path, and issues or feedback in Chinese are welcome.

## License

Licensed under the [Apache License 2.0](LICENSE).