RepoPrimer

English · 简体中文

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

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:

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

Add the MCP server to Codex:

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.

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:

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, Decisions, and Tasks 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 before proposing a change and follow the Code of Conduct. Security issues should follow 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.