reposkein

Introduction

RepoSkein gives your AI coding agent a map of your codebase — so it navigates structure instead of grepping and guessing.

It uses Tree-sitter to build a deterministic Code Property Graph of your repo — files, classes, functions, imports, and call edges — and serves it to any MCP-capable agent (Claude Code, Cursor, Codex, …). As the agent works, it writes short natural-language summaries onto graph nodes; those summaries are versioned in git alongside the code, so an agent's understanding becomes shared team memory that the next agent — or teammate — starts from.

Who it's for: developers using AI coding agents on real, large, or nested/polyglot codebases, who are tired of the agent burning its context window on grep; and teams who want that hard-won understanding to persist and be shared rather than re-derived every session.

• ⚡ Zero-infra — no database, no Docker. The graph lives in plain `.reposkein/*.jsonl` files, rebuilt from your working tree in seconds.
• 🔒 Deterministic — same code → byte-identical graph. No LLM in the construction path.
• 🌐 7 languages — Python, TypeScript, JavaScript, Rust, Go, Java, C#.
• 🧩 Local-first & git-native — the summaries your agents write are committed and travel with your code.

> In a deterministic, no-LLM benchmark, RepoSkein surfaces the right functions with a mean ~8.4× fewer context tokens than a grep-based agent on structural queries.

The bundled `reposkein-graph-rag` skill drives a `semantic_find → get_context_profile → impact → get_temporal_context → write_semantic_summary → reindex_file` loop, so you just ask in plain language. Full workflow, an example interaction, and the tool-by-tool + CLI reference: **`docs/TOOLS.md`**.

Table of contents

• For teams
• Prerequisites
• Installation
• Supported languages
• Documentation
• Contributing
• Acknowledgements
• Contact
• License

For teams

Joining a repo that already has RepoSkein set up? One command, no questions asked:

git clone  && cd  && npx @reposkein/mcp init

`init` detects the committed `.reposkein/meta.json`, reuses its config, and wires up your agent's MCP config automatically. Publish a durable, shareable view of the graph with a **hosted constellation** (GitHub Pages via `reposkein-mcp init --ci`) — and because summaries are committed to git, they're shared team memory: every teammate's agent starts from what previous agents already learned, not from scratch.

Support: if RepoSkein is useful, **Ko-fi** support funds hosted-constellation infrastructure and indexer maintenance — supporters get an ad-free experience once sponsorship tiers ship.

Prerequisites

• Node.js 18+ — to run `npx @reposkein/mcp` (the indexer binary is fetched automatically).
• An MCP-capable agent — Claude Code, Cursor, Codex, Zed, etc.
• A git repository to index (RepoSkein installs git hooks and reads git history for `get_temporal_context`).
• *Optional:* Docker (only for the embeddings server or the Neo4j backend); Rust (only to build from source).

Installation

Claude Code? Two commands, zero config:

/plugin marketplace add reposkein/reposkein
/plugin install reposkein

The plugin registers the MCP server against whatever repo you have open

(`REPOSKEIN_REPO_PATH` is wired to the project directory) and ships the

navigation skills as `/reposkein:reposkein-setup` and

`/reposkein:reposkein-graph-rag` — run the setup skill once per repo to

build the graph. Optional embeddings (Voyage AI or

any OpenAI-compatible endpoint) work by exporting the `REPOSKEIN_EMBED_*`

env vars in your shell — the plugin's server inherits them; the default is

fully local, zero-egress lexical search.

Any other agent — in the repo you want it to understand:

npx @reposkein/mcp init

This downloads the indexer for your platform, installs git hooks + the navigation skill, builds the initial code graph, and prints an MCP config block. Then:

1. Add the printed config to your agent (e.g. Claude Code's `.mcp.json`):

{
     "mcpServers": {
       "reposkein": {
         "command": "reposkein-mcp",
         "env": { "REPOSKEIN_REPO_PATH": "/path/to/your/repo" }
       }
     }
   }

2. Verify the graph (`init` already built it):

reposkein-mcp doctor .         # ✓ binary  ✓ indexed (N nodes)  ✓ ready
   git add .reposkein/meta.json .reposkein/config.toml && git commit -m "add RepoSkein config"

`nodes.jsonl` and `edges.jsonl` are derived from your working tree and git-ignored — a clone rebuilds them on first use. Re-index after big changes with `reposkein-mcp index .` (or the agent's `reindex_file` tool).

3. Ask your agent *"what calls this function?"* or *"what breaks if I change X?"* — it answers from the graph.

> Prefer to let your agent set it up? Install the skills and tell it to run the `reposkein-setup` skill — it installs, indexes, and verifies everything:

> ```sh

> npx skills add reposkein/reposkein --all

> ```

Platforms: prebuilt binaries for macOS (Apple Silicon), Linux (x64/arm64), and Windows (x64). Elsewhere, point `REPOSKEIN_INDEXER_BIN` at a from-source build.

Let your agent install it for you

For complex setups — multi-repo workspaces, Neo4j backend, the local embedding server, or wiring up agents besides Claude Code (OpenCode, Cursor, Codex, Continue, Cline, …) — paste this into any MCP-capable agent and it'll walk you through:

> Install RepoSkein in this workspace. Read `docs/INSTALL.md` (or `https://github.com/reposkein/reposkein/blob/main/docs/INSTALL.md`), walk me through the question tree in §1, then execute §2 onward. If anything fails, troubleshoot via §9 — don't silently skip steps. Confirm with `reposkein-mcp doctor .` per repo and a `semantic_find` smoke test before claiming done.

`docs/INSTALL.md` is written for agents: it covers the decision tree (one repo vs workspace, JSONL vs Neo4j, lexical vs cloud vs local embeddings, which agent CLIs to wire), per-agent config schemas (`.mcp.json`, `opencode.json`, `.cursor/mcp.json`, Continue, Codex, Cline, …), the Apple-Silicon `mps` native embed-server recipe, and a troubleshooting table.

Supported languages

Python, TypeScript, JavaScript, Rust, Go, Java, C# — with an honest per-language matrix of what resolves `exact` vs by-name vs `ambiguous`. Full table + the resolution rules: **`docs/ARCHITECTURE.md`**. Adding a language is a well-trodden path — contributions welcome.

Going deeper: how the graph is built + cross-repo federation · the constellation viewer · semantic embeddings · Neo4j backend · shared remote server · building from source + repo layout.

Documentation

Full index, task-oriented: **`docs/README.md`**.

Contributing

Contributions are welcome — bug fixes, new languages, docs. See **CONTRIBUTING.md for the dev setup, the determinism invariants you must preserve, and the step-by-step recipe for adding a new language** (it's a well-trodden path — Go, Java, and C# were each added the same way). RepoSkein uses Conventional Commits and keeps CI green (determinism gates + clippy + tests).

Acknowledgements

• Tree-sitter — the parsers behind every language extractor.
• Model Context Protocol — the agent integration standard.
• Voyage AI — `voyage-code-3` and the open-weight `voyage-4-nano` powering the optional embeddings tier.
• Discovery via Glama, skills.sh, mcpservers.org, and the awesome-mcp community lists.
• README header by capsule-render.

Contact

• 🐛 Bugs / features: open an issue
• 💬 Questions / ideas: GitHub Discussions

License

Apache-2.0.