repoctx

# repoctx

**Local-first code context for agents and reviewers — what does this change actually touch?**

[![npm](https://img.shields.io/npm/v/@nugehs/repoctx?style=flat-square)](https://www.npmjs.com/package/@nugehs/repoctx) [![CI](https://img.shields.io/github/actions/workflow/status/nugehs/repoctx/repoctx-ci.yml?style=flat-square&label=CI)](https://github.com/nugehs/repoctx/actions/workflows/repoctx-ci.yml) [![license: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE) [![node](https://img.shields.io/node/v/@nugehs/repoctx?style=flat-square)](https://www.npmjs.com/package/@nugehs/repoctx)

![repoctx demo](repoctx-demo.gif)

![repoctx](assets/repoctx-design-print.svg)

```text
 ____   _____   ____    ___    ____   _____  __  __
|  _ \ | ____| |  _ \  / _ \  / ___| |_   _| \ \/ /
| |_) ||  _|   | |_) || | | || |       | |    \  /
|  _ < | |___  |  __/ | |_| || |___    | |    /  \
|_| \_\|_____| |_|     \___/  \____|   |_|   /_/\_\
```

`repoctx` is a local-first code context system. It discovers repositories, builds local indexes, maintains a catalog, searches code context, and generates lightweight harnesses for coding agents and reviewers.

The legacy `dev-context` command remains available as an alias.

It does not try to replace `opensrc`, `code-structure`, Daytona, or Harnss. It gives developers and coding agents a single CLI that can:

Deterministic merge gates — the differentiated core:

- score merge readiness for local changes and pull requests with one `review_gate` tool (`gate` on the CLI)
- resolve CODEOWNERS to required reviewers and surface owner-decision warnings
- check branch-protection expectations and required checks before merge
- generate actionable PR review context from git diffs and optional GitHub comments

Local-first context — feeds the gates:

- inspect a repository
- discover and index local repositories
- maintain a local catalog and search across it
- generate task-aware context packets before an agent plans or edits
- generate AST-backed JSON-first code maps for agents
- generate a setup/validation/runtime harness for a repo
- produce Markdown or JSON reports
- estimate context-token size for generated artifacts
- run an MCP server for agent hosts with a persisted repo index cache
- expose simple agent-friendly tool metadata
- check tool availability
- generate TypeScript structure HTML through `code-structure`
- search dependency source through `opensrc`

## Documentation

repoctx now includes a publishable MkDocs documentation site, shaped as a practical discovery and delivery pack:

- [Home](docs/index.md)
- [Executive Summary](docs/EXECUTIVE-SUMMARY.md)
- [Context Foundation](docs/01-context-foundation/README.md)
- [MCP and Agent Workflows](docs/02-mcp-agent-workflows/README.md)
- [Contributor Governance](docs/03-contributor-governance/README.md)
- [Release Readiness](docs/04-release-readiness/README.md)
- [Trust-Layer Demo](docs/05-trust-layer-demo/README.md)
- [Builder-Founder Operating Loop](docs/06-builder-founder-operating-loop/README.md)
- [Glossary](docs/GLOSSARY.md)

When GitHub Pages is enabled for the repository, the published site is configured for:

```text
https://nugehs.github.io/repoctx/
```

## Quick Start

Code maps use the TypeScript compiler for JS/TS and dedicated language extractors for Go, C#, Python, Java, Ruby, and Rust (see `src/lib/code-map/ast-languages.js`). Optional external tools are only needed for dependency-source lookup and HTML structure reports.

Install from npm:

```bash
npm install -g @nugehs/repoctx
repoctx doctor
```

Or run without installing:

```bash
npx -y @nugehs/repoctx doctor
```

From a local checkout:

```bash
npm ci             # install dependencies
npm run ci         # run the full quality gate
npm install -g .   # install the repoctx CLI globally
repoctx doctor     # verify the install
```

```bash
node src/cli.js help
node src/cli.js doctor
node src/cli.js init /path/to/target-repo
node src/cli.js repo . --json
node src/cli.js discover ~/projects --depth 2 --json
node src/cli.js index ~/projects --discover
node src/cli.js catalog
node src/cli.js search "events controller"
node src/cli.js context "add a new MCP tool" --path .
node src/cli.js map . --json
node src/cli.js harness . --out .dev-context/harness.md
node src/cli.js pr . --base origin/main --out .dev-context/pr-review.md
node src/cli.js mcp
node src/cli.js matrix
node src/cli.js report . --out .dev-context/report.md
node src/cli.js workspace /path/to/web /path/to/api --out .dev-context/workspace.md
```

Optional external tools:

```bash
npm install -g opensrc code-structure
```

Then:

```bash
node src/cli.js deps zod --query parse
node src/cli.js structure . --out .dev-context/structure.html
```

## Usage Examples

| Goal | Command | Output |
| --- | --- | --- |
| Inspect one repo | `repoctx repo . --json` | Repo facts, scripts, languages, entrypoints, and git state |
| Build a code map | `repoctx map . --json` | Source files, domains, imports, exports, symbols, and routes |
| Prepare task context | `repoctx context "add a new MCP tool" --path .` | Primary files, related files, tests, patterns, and validation commands |
| Generate an agent harness | `repoctx harness . --out .dev-context/harness.md` | Setup, validation, runtime, and context commands |
| Review local changes | `repoctx pr . --base origin/main --out .dev-context/pr-review.md` | Changed files, risk prompts, review targets, and test hints |
| Index local projects | `repoctx index ~/projects --discover` | `.dev-context/index.json` files plus a local catalog |
| Search indexed repos | `repoctx search "events controller"` | Ranked matches across paths, domains, routes, imports, exports, and symbols |
| Run the MCP server | `repoctx mcp` | Stdio MCP server exposing repoctx tools |

For Claude Desktop, VS Code, Cursor, and generic stdio client snippets, see [MCP and Agent Workflows](docs/02-mcp-agent-workflows/README.md).

## repoctx vs alternatives

| Approach | Strengths | Where repoctx differs |
| --- | --- | --- |
| Sourcegraph / Cody context | Powerful hosted code search and embedding-based context across an org | repoctx is local-first and deterministic: no server, no account, no code leaves the machine, and the same query always yields the same packet |
| Hand-written `CLAUDE.md` / rules files | Curated, intent-rich guidance | Hand-written context goes stale; repoctx regenerates context from the actual code (symbols, imports, routes, tests) on every run and complements a short `CLAUDE.md` |
| `grep` / `ripgrep` | Fast, universal text matching | repoctx ranks whole files by task intent across paths, symbols, exports, and tests, then adds patterns and validation commands — a context packet, not a list of matching lines |

## Quality Gates

Use the full gate before opening a pull request or publishing a release:

```bash
npm run ci
```

The gate runs:

- `npm run format:check`
- `npm run lint`
- `npm run typecheck`
- `npm run version:check`
- `npm test`
- `npm run test:coverage`
- `npm run audit`
- `npm run smoke`

Coverage currently gates source files at 70% lines, 60% branches, and 75% functions. Generated artifacts under `.dev-context/` are ignored by git, linting, and formatting; keep durable reports there instead of committing them.

repoctx follows Semantic Versioning. Pull requests should identify whether they are no-version-impact, patch, minor, or major changes; maintainers apply the final package version during release.

For longer trust-layer work, use the [Builder-Founder Operating Loop](docs/06-builder-founder-operating-loop/README.md) to keep every session tied to context, focused changes, visible gates, human decisions, and durable evidence.

## Contributing

Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), open an issue or draft PR for substantial changes, and run `npm run ci` before requesting review.

All code changes must be reviewed by a maintainer/code owner before merge. The protected `main` branch requires maintainer approval, passing quality gates, and resolved PR conversations.

## Common Workflows

Agent repo harness:

```bash
node src/cli.js harness . --out .dev-context/harness.md
node src/cli.js map . --json
```

Local discovery, indexing, catalog, and search:

```bash
node src/cli.js discover ~/projects --depth 2
node src/cli.js index ~/projects --discover
node src/cli.js catalog
node src/cli.js search "submit rsvp"
```

Task-aware agent context:

```bash
node src/cli.js context "add a new MCP tool" --path . --json
node src/cli.js context "add a new MCP tool" --path . --out .dev-context/context-pack.md
```

PR review harness:

```bash
node src/cli.js pr . --base origin/main --out .dev-context/pr-review.md
node src/cli.js pr . --number 123 --comment
```

Merge gate (`gate` is the canonical v2 command; `pass` / `pass-pr` remain as legacy aliases):

```bash
node src/cli.js gate . --base origin/main          # local gate (no GitHub)
node src/cli.js gate --pr 123 --path .             # GitHub PR gate via gh
```

Multi-repo product context:

```bash
node src/cli.js workspace ../web ../api --out .dev-context/workspace.md
```

GitHub Actions bootstrap:

```bash
node src/cli.js init /path/to/target-repo
```

Local Ollama review:

```bash
node src/cli.js harness . --out .dev-context/harness.md

{
  echo "Use this repo harness to explain the project and suggest the next best engineering task."
  echo
  cat .dev-context/harness.md
} | ollama run qwen3:8b --think false --hidethinking --nowordwrap
```

Local Ollama PR review:

```bash
node src/cli.js pr . --base origin/main --out .dev-context/pr-review.md

{
  echo "Review this PR context. Focus on bugs, missing tests, and risky changes."
  echo
  cat .dev-context/pr-review.md
} | ollama run qwen3:8b --think false --hidethinking --nowordwrap
```

## Commands

### `doctor`

Checks the local runtime and optional external tools.

```bash
node src/cli.js doctor --json
```

### `install