repo-mesh

Give your AI coding agent awareness of your other repos.

When you work across multiple services, your AI agent only sees the current repo. It guesses about external services instead of reading the actual code. repo-mesh fixes this by scanning your codebase, finding every external service dependency, and generating context files that tell your AI agent exactly where to look.

No config. No network calls. Just static analysis.

Install

npx repo-mesh init

How it works

1. Scans your codebase for service dependencies (HTTP calls, env vars, docker-compose, gRPC, k8s manifests, GraphQL, message queues)
2. Asks you to map each discovered service to its local directory
3. Generates context files so your AI agent knows where everything lives

It creates four files:

| File | Purpose | |------|---------| | .repomesh.json | Service manifest with paths and endpoints | | CLAUDE.md | Context block for Claude Code | | .cursorrules | Context block for Cursor | | .claude/skills/cross-repo-context.md | Skill that teaches Claude how to navigate linked repos |

Commands

npx repo-mesh init     # Discover services, set up mappings, install skill
npx repo-mesh scan     # Re-scan for changes since last init
npx repo-mesh doctor   # Validate paths and check for CLAUDE.md in targets

What it detects

| Source | Examples | |--------|----------| | HTTP clients | fetch(), axios, got, requests.get() | | Environment variables | *_SERVICE_URL, *_API_BASE, *_ENDPOINT | | Docker Compose | depends_on relationships | | gRPC / Protobuf | .proto service definitions, client instantiations | | Kubernetes | Service and Deployment manifests, env var references | | GraphQL / OpenAPI | Apollo, urql, Swagger/OpenAPI specs | | Message queues | RabbitMQ, Kafka, SQS/SNS, Redis pub/sub, BullMQ, NATS, Celery |

Analysis modes

• Basic — service names + local paths
• Detailed — also tracks specific endpoints and source files

Example

$ npx repo-mesh init

Scanning for service dependencies...

Found 3 services:
  1. user-service (docker-compose, env-var)
  2. payments (http, env-var)
  3. notifications (message-queue)

Analysis mode: Basic

Where is user-service located? ~/repos/user-service
Where is payments located? ~/repos/payments-api
Where is notifications located? skip

✓ .repomesh.json
✓ CLAUDE.md
✓ .cursorrules

Now your AI agent knows that when it sees a call to user-service, the implementation lives at ~/repos/user-service.

Cross-repo context

repo-mesh checks whether each linked repo has a CLAUDE.md file. When it does, the generated context includes a direct pointer:

### user-service
- **Path:** `/repos/user-service`
- **Context file:** `/repos/user-service/CLAUDE.md`

It also installs a Claude Code skill (.claude/skills/cross-repo-context.md) that teaches your AI agent to:

1. Read .repomesh.json to find service paths
2. Read the target repo's CLAUDE.md for high-level context
3. Explore target source files when deeper detail is needed

The doctor command warns when a linked repo is missing a CLAUDE.md, and scan detects when one is added or removed.

License

MIT