repo2agent

ESLint for AI coding agents.

Make every repository agent-ready before AI touches your code.

npx repo2agent init
npx repo2agent doctor

repo2agent scans your project, generates instruction files for the major coding-agent tools, checks drift, and gives CI a score it can enforce.

It generates:

AGENTS.md
CLAUDE.md
.cursor/rules/repo.mdc
.github/copilot-instructions.md

It also gives you:

npx repo2agent check
npx repo2agent doctor --min-score 70
npx repo2agent doctor --json

Why Developers Star This

AI coding agents are everywhere, but most repositories still do not tell them how to work safely.

repo2agent gives every repo a portable agent context:

• one command to generate agent instruction files
• doctor score for agent-readiness quality gates
• zero API keys and zero model calls
• works in private repos
• detects test, lint, build, and typecheck commands
• adds a fingerprint so CI can detect stale instructions
• supports the tools developers already use

Quick Start

Generate all supported files:

npx repo2agent init

Typical output:

created AGENTS.md
created CLAUDE.md
created .cursor/rules/repo.mdc
created .github/copilot-instructions.md
agent readiness: 78/100

Generate only Codex and Claude Code files:

npx repo2agent init --targets codex,claude

Preview without writing:

npx repo2agent init --dry-run

Check whether generated files are stale:

npx repo2agent check

Diagnose what keeps the repo from being agent-ready:

npx repo2agent doctor

Use it as a quality gate:

npx repo2agent doctor --min-score 70

Emit JSON for bots and dashboards:

npx repo2agent doctor --json

Emit Shields.io-compatible badge JSON:

npx repo2agent doctor --badge

Print one target to stdout:

npx repo2agent print codex

Scan the current repo:

npx repo2agent scan

Supported Targets

| Target | Output | | --- | --- | | Codex | AGENTS.md | | Claude Code | CLAUDE.md | | Cursor | .cursor/rules/repo.mdc | | GitHub Copilot | .github/copilot-instructions.md |

Examples

Try the scanner against included sample repos:

node ./bin/repo2agent.js doctor --dir examples/nextjs
node ./bin/repo2agent.js doctor --dir examples/python-fastapi

The Next.js example detects React, Next.js, TypeScript, test, lint, build, and typecheck commands. The Python example detects Python and pytest-style verification.

Use --dry-run to preview generated files:

node ./bin/repo2agent.js init --dir examples/nextjs --dry-run

Example Output

Generated files include:

• repository stack and package manager
• source/test/docs directory map
• common commands such as npm run test, pnpm lint, python -m pytest, go test ./..., or cargo test
• workflow rules for safe coding-agent behavior
• safety rules around secrets, auth, migrations, generated files, and lockfiles
• a repo2agent fingerprint for drift detection

Example snippet:

## Common Commands

- test: `pnpm test`
- lint: `pnpm lint`
- typecheck: `pnpm typecheck`

## Agent Workflow

- Read the relevant files before editing.
- Prefer existing patterns, naming, and architecture over new abstractions.
- Keep changes scoped to the user request.

Doctor

repo2agent doctor turns the scan into an actionable readiness report:

repo2agent doctor

Score: 65/100 (close)

Agent files
- ok: AGENTS.md
- missing: CLAUDE.md
- missing: .cursor/rules/repo.mdc
- missing: .github/copilot-instructions.md

Suggestions
- [high] Generate missing agent instruction files
  Fix: repo2agent init
- [medium] Add a TypeScript typecheck command
  Fix: Add a typecheck script such as tsc --noEmit, then rerun repo2agent init --force.

Use Markdown output in issues, PRs, or docs:

npx repo2agent doctor --markdown

Use JSON output in automations:

{
  "score": 75,
  "grade": "close",
  "repository": {
    "name": "my-app",
    "packageManager": "pnpm",
    "stack": ["Next.js", "React", "TypeScript"]
  },
  "suggestions": []
}

CI

Keep agent instructions fresh:

- run: npx repo2agent check
- run: npx repo2agent doctor --min-score 70

Use the bundled GitHub Action:

- uses: repo2agent/repo2agent@v1
  with:
    min-score: 70

When the repo structure or commands change, run:

npx repo2agent init --force

Local Development

npm test
node ./bin/repo2agent.js init --dry-run
node ./bin/repo2agent.js check

Positioning

This is not another coding agent.

It is the missing quality gate for agents: small, local, deterministic, and easy to add to every repository.

That makes it a good fit for:

• open-source maintainers who want better agent PRs
• teams standardizing Codex / Claude Code / Cursor behavior
• template repos, internal starters, and monorepos
• CI checks that keep agent instructions from drifting

Roadmap

• monorepo package/workspace command detection
• pull request bot that comments when agent instructions are stale
• framework-specific rule packs for Next.js, FastAPI, Rails, Go, and Rust
• MCP server so agents can ask for live repository context