Compress any code repository into a structured context package that AI programming agents can read and verify — saving tokens and avoiding context loss.
https://github.com/whut09/Repo-to-Agent-Context…

A TypeScript CLI tool that scans repositories and generates context packages directly usable by AI agents.
Output includes AGENTS.md and a .agent-context/ folder containing repository summaries, module relationship graphs, dependency graphs, architecture documentation, token savings reports, and readiness scores.

whut09/Repo-to-Agent-Context

Source: https://github.com/whut09/Repo-to-Agent-Context

Repo-to-Agent-Context

中文 | English

Repo-to-Agent-Context is a repository context harness for coding agents. It generates minimal, verifiable context packages with evidence chains for specific tasks, and reduces the risk of irrelevant context, mis-edit, and regression through test/change/dependency constraints.

The first version follows an offline-first design: scan the repo, extract lightweight code structure, rank key files, build a dependency graph, and output Markdown/JSON context files — no heavy reliance on large models.

Usage via AI Agent

You can also ask Codex, Claude Code, Cursor, or any other programming agent to run this project for you. For example, in Codex you can directly say:

Use https://github.com/whut09/Repo-to-Agent-Context to generate AGENTS.md and .agent-context context packages for xxx project. First check the target repository structure, then install or clone the tool as needed. Force enable LLM summarization: create or update repo-context.local.yml in the target repo, do not commit that file, prefer using the model API configuration available in the current AI tool environment or the key/baseUrl/model I provide; if configuration is missing, ask me first. Then run repo-context build <target-repo> --target codex --llm, then run repo-context validate <target-repo>, and finally explain which files were generated and whether LLM summary mode succeeded.

Replace xxx project with a local path, GitHub repository, or the current workspace name. If you only need a root-level description, say “generate AGENTS.md”; if you need the full context package, say “generate AGENTS.md and .agent-context”.

Note: The current AI tool must provide a callable model API key, base URL, and model for Repo-to-Agent-Context to actually execute LLM summarization. If Codex/Claude/Cursor does not expose its own model as an API, let the agent ask you for the configuration; the real key should only be written into repo-context.local.yml.

Quick Start

After publishing to npm, you can run:

npx repo-to-agent-context build ./path/to/repo

Run from source:

npm install
npm run build
node dist/cli/index.js build ./path/to/repo

During development you can run directly:

npm run dev -- build ./path/to/repo

Will large models automatically read AGENTS.md?

It depends on the programming tool you use, not the large model itself. AGENTS.md is a convention used by agent clients to inject repository instructions into the model context.

• By default, the generated AGENTS.md uses agents.mode: minimal, keeping only the mandatory operational rules, entry files, necessary commands, and a .agent-context/ index.
• Longer repository summaries, module graphs, dependency graphs, readiness scores, and task packages are placed in .agent-context/ to avoid making the root context file too long.
• Codex: Yes. Codex reads AGENTS.md before starting work and can merge global and project-level instructions into the context.
• Claude Code: Does not read AGENTS.md directly. Claude Code’s project instructions file is CLAUDE.md. If you want to reuse the instructions generated by this tool, you can create CLAUDE.md in the repository root with the content @AGENTS.md and then append Claude-specific instructions.
• Cursor: Supported. Place AGENTS.md in the project root to use it as a simple project rule. For path-scoped, conditional triggers, or multi-file rules, it’s recommended to use .cursor/rules.
• Other tools: Support varies. If the tool does not automatically load AGENTS.md, you can manually reference or attach the file in your prompt.

For detailed usage, see docs/agents-md.zh-CN.md.

Output

AGENTS.md
.agent-context/
  repo-summary.md
  key-files.md
  module-map.md
  dependency-graph.md
  architecture.md
  onboarding.md
  readiness.md
  readiness.json
  token-savings.md
  token-savings.json
  contracts/
    architecture.contract.json
    module-boundaries.json
    commands.contract.json
    test.contract.json
    safety.contract.json
  tasks/
    bugfix-context.md
    feature-context.md
    refactor-context.md
    bugfix.json
    feature.json
    refactor.json
  rag/
    README.md
    manifest.json
    documents.jsonl
  evidence/
    file-evidence.json
  index/
    files.json
    symbols.json
    modules.json
    chunks.json
  graphs/
    dependencies.json
    dependencies.mmd

Context Layers

Generated context is split into L0–L3 so agents do not load the full .agent-context/ directory by default:

• L0: AGENTS.md — the shortest operating rules and default workflow, always loaded.
• L1: .agent-context/repo-summary.md, .agent-context/onboarding.md, and .agent-context/context-layers.md — loaded when a new task starts.
• L2: .agent-context/tasks/ — loaded only for the concrete task.
• L3: .agent-context/key-files.md, index/, evidence/, graphs/, and rag/ — loaded on demand for deeper analysis, symbol lookup, or evidence tracing.

AGENTS.md explicitly states the default workflow: read only AGENTS.md first; for a concrete task, run repo-context plan or inspect the task pack; do not load the full .agent-context/ directory by default; prefer source files over generated summaries for behavior decisions.

Manual environment and deployment notes stay in AGENTS.manual.md and are loaded only for environment, deployment, configuration, or operations tasks.

Commands

repo-context init [repo]
repo-context build [repo]
repo-context graph [repo]
repo-context explain [repo]
repo-context savings [repo]
repo-context readiness [repo]
repo-context validate [repo]
repo-context plan "<task>" [repo]
repo-context pack "<task>" [repo]
repo-context verify --diff [repo]
repo-context impact [repo] --base main
repo-context tests [repo] --for <file>
repo-context tests [repo] --diff --base main
repo-context benchmark [benchmarkDir] --top-k 8
repo-context task "<task>" [repo]
repo-context task "<task>" --repo <repo>
repo-context diff [repo] --base main
repo-context update [repo] --since main
repo-context rag export [repo]

Examples:

repo-context build . --target codex
repo-context build . --target codex --tokenizer chars-approx
repo-context build . --target codex --model gpt-4.1
repo-context build . --llm
repo-context build ../my-app --target all --token-budget 80000
repo-context explain src/server.ts .
repo-context explain auth .
repo-context readiness .
repo-context validate .
repo-context savings . --token-budget 60000
repo-context savings . --actual --model gpt-4.1
repo-context plan "fix login timeout bug" . --type bugfix
repo-context pack "fix login timeout bug" . --type bugfix --token-budget 12000
repo-context verify --diff .
repo-context impact . --base main
repo-context tests . --for src/auth/session.ts
repo-context tests . --diff --base main
repo-context task "fix login timeout bug" . --type bugfix --token-budget 12000
repo-context task fix login timeout bug --repo "../my app/中文项目" --type bugfix
repo-context diff . --base main
repo-context rag export . --token-budget 60000

Token Savings Report

Every build generates a token savings report:

Original repo (estimated, chars_approx): 2,400,000 tokens
Estimated context pack (chars_approx): 42,000 tokens
Actual context pack (o200k_base, gpt-4.1): 41,832 tokens
Compression: 57x
Token budget: 60,000 (within budget)

The report distinguishes between original repository estimates, theoretical compact context estimates, and actual written token counts for Markdown, Mermaid, and RAG JSONL. Machine-readable indexes are not counted in the actual output tokens; the scope is clearly described in the report. When a real tokenizer is configured, js-tiktoken is used for counting; it falls back to chars_approx when not available.

Generated files:

• .agent-context/token-savings.md
• .agent-context/token-savings.json

Agent Readiness Score

The readiness report is an engineering diagnostic score, not a guarantee of agent success rate. It aggregates six categories of low-level signals into three layers and applies hard caps to prevent easy perfect scores:

Agent Readiness: B / 82
Dimensions:
  - Operational: 90/100
  - Context Quality: 75/100
  - Agent Safety: 70/100
Hard caps:
  - max 90 when no CI workflow is detected
  - max 90 when token counting uses chars_approx instead of a model tokenizer
  - max 85 when no high-confidence AST/compiler analyzer evidence exists

Generated files:

• .agent-context/readiness.md
• .agent-context/readiness.json

Optional LLM Summarization

Large models are an optional capability. The CLI works offline by default.

Configuration committed to the repository should only contain placeholders:

llm:
  enabled: false
  provider: openai-compatible
  baseUrl: xx
  apiKey: xx
  model: xx

For local use, copy repo-context.local.example.yml to repo-context.local.yml and write the real key and URL. repo-context.local.yml is already in .gitignore and will not be committed.

llm:
  enabled: true
  provider: openai-compatible
  baseUrl: xx
  apiKey: xx
  model: xx

Then run:

repo-context build . --llm

When LLM is not enabled, Repo-to-Agent-Context uses offline summarization. When enabled, if the key, URL, or model is missing or still xx, a clear actionable configuration error is given; if the runtime request fails, it falls back to offline summarization and logs the reason.

Run repo-context validate . to check configuration, generate JSON, dependency edges, analysis confidence, and token budget.

Analysis Confidence and Evidence

• TypeScript/JavaScript: Uses the TypeScript Compiler API to parse import type, dynamic import(), re-exports, symbols, barrel exports, tsconfig path aliases, workspace package aliases, and common Next.js/Express/Fastify/Hono/NestJS route patterns.
• Python: Prefers stdlib ast when a Python runtime is available locally, falls back to lightweight parsing; supports local absolute and relative imports like from .models import User, from app.services.auth import login.
• Analyses for unsupported languages or fallback cases are marked as low confidence.

Each index file includes analyzer, confidence, analysisStats (parser, resolved/unresolved imports, symbols, routes), and line-numbered evidence. Aggregate evidence is output to .agent-context/evidence/file-evidence.json.

Task Context Packs

The task workflow is split into four stages: plan, pack, verify, and tests; the older task command is kept as a compatibility entry point. The tests command selects minimal tests, regression tests, and full-confidence commands for a file or diff. The task mode is not a simple keyword-to-file list; it is a three-phase context packer:

1. Direct retrieval: match path, module, summary, exports, symbols, tests, and docs.
2. Graph expansion: add direct imports, direct importers, sibling tests, entrypoints, config files, and owning module docs.
3. Budget packing: bucket into direct source, tests, dependency neighbors, config/docs, and entrypoints within the token budget.

repo-context plan "fix login timeout bug" . --type bugfix
repo-context pack "fix login timeout bug" . --type bugfix --token-budget 12000
repo-context verify --diff .
repo-context impact . --base main
repo-context tests . --for src/auth/session.ts
repo-context tests . --diff --base main
repo-context task "fix login timeout bug" . --type bugfix --token-budget 12000
repo-context task fix login timeout bug --repo "../my app/中文项目" --type bugfix
repo-context task "add SSO login" . --type feature
repo-context task "split auth module" . --type refactor

Markdown output provides the agent with Read First, Then Inspect If Needed, Why These Files, Budget Packing, and Suggested Commands. Machine-readable task packs are generated in .agent-context/tasks/*.json.

Benchmark

The repository includes a demo context-quality benchmark under benchmarks/. It evaluates task-aware context packs against expected relevant files and required tests across small TypeScript, React, FastAPI, and monorepo fixtures.

npm run benchmark
repo-context benchmark benchmarks --top-k 8
repo-context benchmark benchmarks --json

Reported metrics include Recall@K, Precision@K, token compression ratio, test recommendation accuracy, and an agentSuccessDeltaProxy comparing task-pack coverage with a non-task-aware key-file baseline. The proxy is deterministic and repeatable; it is not a live agent execution benchmark.

Optional RAG: LightRAG

RAG is recommended as an addition, but should not replace static context packages. The recommended architecture is:

Generate static context package first -> AGENTS.md, summary, dependency graph, key files
Then an optional RAG adapter layer -> export LightRAG-friendly JSONL, later import into LightRAG Server

Repo-to-Agent-Context generates:

• .agent-context/rag/documents.jsonl
• .agent-context/rag/manifest.json
• .agent-context/rag/README.md

LightRAG remains optional because it typically requires a separate Python/Server environment and consistent embedding configuration during indexing and querying.

The current version exports documents suitable for LightRAG ingestion but does not yet synchronize directly to a LightRAG Server.

Architecture

Implementation design: docs/architecture.md
AGENTS.md usage instructions: docs/agents-md.zh-CN.md
Future roadmap: docs/roadmap.md

Configuration

Create repo-context.config.yml:

target: codex
tokenBudget: 60000
tokenizer:
  mode: chars_approx
  # mode: cl100k_base
  # model: gpt-4.1
agents:
  mode: minimal   # minimal | balanced | full
  maxTokens: 1200
  include:
    - commands
    - safety
    - entrypoints
    - contextLinks
include:
  - src/**
  - docs/**
  - package.json
exclude:
  - node_modules/**
  - dist/**
  - coverage/**
outputs:
  agents: true
  modules: true
  graph: true
  tasks: true
  readiness: true
  rag: true

agents controls the information density of the root AGENTS.md. The default minimal keeps the root file to minimum operational constraints; balanced/full includes more overview content. The outputs switches control optional generated artifacts. When a switch is off, previously generated files in that group are also cleaned. Repository summaries, key files, onboarding, token savings reports, and machine-readable indexes are always generated.

Development

npm run build
npm run check
npm test
npm pack --dry-run