RepoResident

Make any coding agent think like it has lived in your codebase.

RepoResident is a Git-native harness that turns a general coding agent into a project-aware
maintainer. It gives every session the project's goals, current state, architecture map,
decisions, and engineering workflows before work begins.

The agent reasons from the project, not only from the latest prompt.

No server. No database. No MCP dependency. No vendor lock-in. RepoResident is a small collection
of Markdown files that lives beside the code, travels with Git, and remains readable to both
people and agents.

Why RepoResident

Coding agents are capable engineers, but each new session usually begins as an outsider. The
agent may understand the language and framework while knowing nothing about the project's
direction, current work, prior decisions, or quality expectations.

RepoResident supplies that missing operating context.

The result feels less like prompting a temporary assistant and more like assigning work to the
maintainer of the codebase.

Results in practice

RepoResident was shaped through continued use on real project work. The most visible effects have
been:

• More than 50% lower token usage in observed project sessions. Directed navigation and
  bounded context reduce repeated repository exploration. This is an observed result, not a
  universal benchmark. Results depend on the model, repository, and task.
• Higher prompt-cache reuse. Stable operating instructions and repeatable workflows keep a
  large portion of each session consistent.
• Stronger technical designs. The agent designs with the project's goals, architecture,
  constraints, prior decisions, and known issues available.
• Less shortcut-driven implementation. Workflows explicitly reject stubs, silent scope
  reduction, and avoiding necessary complexity.
• More maintainable code. The operating manual prioritizes readability, obvious control flow,
  boundary handling, tests, and consistency with surrounding code.

RepoResident does not modify the model. It gives the model a better operating environment.

Quick start

Start a new project

1. Select Use this template on GitHub.
2. Create your new repository.
3. Open it with your coding agent.
4. Provide a short project brief:

Bootstrap this project.

Goal: <what the project should achieve>
Stack: <languages and frameworks>
Constraints: <important technical or product requirements>

The bootstrap workflow verifies the project setup, records the initial architecture and commands,
and prepares the repository for normal work.

For a new project, bootstrap replaces this template README with the project's own README. The
RepoResident manual remains available in .agent/README.md.

Adopt an existing project

Copy these items into the repository root:

CLAUDE.md
AGENTS.md
.agent/

Then ask the coding agent:

Bootstrap: adopt this repository.

The agent inspects the existing project, verifies its commands, builds the initial map, and records
only facts supported by the repository.

Daily use

No special commands are required. Ask for work normally:

How it works

request
  -> task routing
  -> current project state
  -> targeted project knowledge
  -> task-specific workflow
  -> verification and review
  -> durable project record

Project awareness

STATE.md tells the agent what is active, what happens next, and what must not be forgotten.
PROJECT.md records architecture, constraints, domain terms, and cross-cutting risks.
DECISIONS.md prevents settled choices from being rediscovered or contradicted without cause.

Directed navigation

MAP.md points the agent to the relevant modules before it searches the source. Area documents
hold deeper knowledge only where a module genuinely needs it. The agent reads the smallest useful
working set instead of surveying the whole repository.

Workflow discipline

Each task type has its own procedure:

• Features require a complete design, approval, implementation, verification, and review.
• Known fixes stay small and focused.
• Unknown defects require reproduction and evidence before a fix.
• Refactors preserve behavior and proceed through verifiable mechanical steps.
• Reviews report confirmed findings with concrete failure scenarios.

This removes repeated process decisions from the prompt and gives the model a clear definition of
complete work.

Bounded context

Project knowledge is split into layers. Every file has a specific role and most hot files have a
hard size limit.

Old session history stays in an append-only journal and is searched only when needed. Project age
does not automatically increase the context loaded for a small task.

Quality contracts

RepoResident makes engineering expectations explicit:

• No stubs, placeholder implementations, or silently reduced scope.
• Necessary complexity is designed and justified instead of avoided.
• Behavior changes include tests that would fail without the change.
• Boundaries account for empty input, invalid input, dependency failures, and timeouts.
• Code favors readability, maintainability, and consistency with local patterns.
• Completed work leaves verification evidence and an inspectable file trail.

Repository layout

CLAUDE.md
AGENTS.md
.agent/
  README.md
  STATE.md
  MAP.md
  PROJECT.md
  DECISIONS.md
  ISSUES.md
  workflows/
  designs/
  areas/
  journal/
  scratch/

The full human manual is available at .agent/README.md.

Agent compatibility

RepoResident uses the instruction files already recognized by common coding tools.

The harness itself is model-independent. A tool must be able to read repository files and follow
the operating manual for the full workflow to apply.

Team mode

The default branch assumes one writer at a time. The multi-team branch adds an advisory claim
board, a branch integration workflow, and merge rules for shared harness files.

Team mode is optional. Solo projects keep the smaller default setup.

Limitations

• RepoResident is an instruction and documentation system, not a security boundary.
• Workflow rules are visible and auditable, but the coding agent can still make mistakes.
• Project knowledge remains useful only when sessions maintain it as required.
• Quantitative improvements vary across repositories, models, and task types.
• The default setup is designed for one active writer. Use team mode for parallel branches.

Contributing

Bug reports, workflow improvements, compatibility findings, and documentation corrections are
welcome. See CONTRIBUTING.md before opening a pull request.

License

RepoResident is available under the MIT License.