# Repiscope

**A periscope for your repos — see everything, touch nothing.**

Repiscope is a read-only MCP server that gives your coding agent (Claude Code,
Cursor, or any MCP client) awareness of the *sibling repositories* next to the
one it's working in — without ever letting it modify them.

## Why

I built a personal assistant to help me decide where my time goes: for that
it needs to know the real state of every project — what changed, what
stalled, what the next step is. So it has to *see* all my repos. But telling
an agent "don't touch anything" is a request, not a guarantee. Repiscope
makes it a **guarantee**: the server exposes zero write tools, so the agent
structurally *cannot* modify your repos. And the same periscope helps any
coding agent working in project A that needs to know how a part of
project B works.

Sandboxes make this worse, not better: mine (rightly) stops the agent from
even *reading* outside the repo it started in without asking. Widening the
sandbox would grant write access too. Repiscope is the third way — the
agent gets structured, read-only sight of every sibling repo through one
MCP server, and the sandbox stays tight.

## See it in action

You're working in `project-a` and need to pull data from another project's
API. Instead of you digging through that codebase, the agent asks Repiscope
directly:

```
You:    Use Repiscope to find out what kind of data I can retrieve
        from billing-api through its API.

Agent:  (calls list_projects → sees "billing-api")
        (calls project_overview "billing-api" → spots src/routes/)
        (calls search "route" project="billing-api")
        (calls read_file "billing-api" "src/routes/invoices.py")

        billing-api exposes three endpoints: /invoices (list, filterable
        by customer and date), /invoices/{id} (full invoice with line
        items), and /customers/{id}/balance (current balance). All
        responses are JSON; auth is a bearer token.
```

The agent explored a repo it has **no ability to write to**. No copy-paste,
no "please don't edit anything," no risk.

## Tools

| Tool | Input | Returns |
|------|-------|---------|
| `list_projects()` | — | every sibling repo + one-line description |
| `project_overview(project)` | repo name | full overview: purpose, stack, structure, recent commits |
| `search(query, project?)` | text, optional repo | files & lines matching the query |
| `read_file(project, path)` | repo + file path | full file contents (size-capped) |
| `store_summary(project, summary)` | repo + your text | caches an agent-written summary (see below) |

## How it stays fresh

Overviews are cached as markdown and refreshed lazily: on each call Repiscope
compares the repo's current git commit hash against the one recorded when the
overview was built. Same hash → serve the cache. Different → rebuild just that
repo's overview. No cron, no daemons.

## Borrowed intelligence

Repiscope has no LLM of its own — no API key, no model calls, zero cost. But
it talks to LLMs all day, so it borrows them: when an overview has no fresh
agent-written summary, it ends with a note asking the *calling* agent to
write one and hand it back via `store_summary`. The summary then opens every
future overview of that project — written by one agent, read by all the
next — until the repo's next commit marks it outdated and the cycle repeats.

## Security by architecture

Repiscope is built so that the safe behaviour is not a promise — it's the
only behaviour possible:

- **Zero repo-write tools.** The server exposes no tool that can create,
  edit or delete anything inside your repositories. The one tool that
  accepts data, `store_summary`, can only write to Repiscope's own cache in
  `~/.cache/repiscope`. An agent cannot misuse a capability that doesn't
  exist.
- **Secrets are invisible.** A single filter (`privacy.py`) is enforced by
  every tool: private keys, certificates (`.pem`, `.pfx`, `.p12`, …),
  `.env*` files, keystores, and anything named like a credential never
  appear in overviews, trees, search results or file reads.
  *Honest limit:* the filter hides sensitive **files** — it does not scrub
  mentions of e.g. a password pasted inside an ordinary text file.
- **Symlinks can't smuggle.** A cloned repo is untrusted content — it may
  contain a symlink like `notes.txt → ~/.ssh/id_rsa`. Anything whose real
  location falls outside the project is invisible to every tool, the secret
  filter also checks a link's real target, and path traversal (`../`) is
  refused.
- **You define the perimeter.** Repiscope only sees the folder you
  explicitly pass (`--root`), and `--exclude` makes chosen repos fully
  invisible — they can't even be resolved by name.
- **It leaves no trace.** Overview caches live in `~/.cache/repiscope`,
  never inside your repositories.

Every claim above is enforced by the test suite in `tests/` — clone the
repo and run `pytest` to check them yourself.

## Quick start

```bash
pip install repiscope
claude mcp add repiscope --scope user -- repiscope --root ~/your/projects/folder
```

That's it — point `--root` at the folder *containing* your repos (not a repo
itself). Optionally hide repos with `--exclude repo-a --exclude repo-b`.
Works with any MCP client; for Claude Desktop there's also a one-click
`.mcpb` bundle (build it with `mcpb/build.sh`).

From source instead:

```bash
git clone https://github.com/3xpr1ment/repiscope.git
cd repiscope
python -m venv .venv && .venv/bin/pip install -e .[dev]
.venv/bin/pytest   # the security claims, as executable proof
```

## Limitations

Honesty section — what Repiscope deliberately does *not* do:

- **The secret filter works at file level.** Sensitive *files* are
  invisible, but a password pasted inside an ordinary `notes.md` will not
  be scrubbed. The perimeter is yours: only point `--root` at folders you
  are comfortable showing to your agent — whatever the tools can see, your
  LLM provider will see too.
- **Search is deliberately dumb.** Case-insensitive substring match, capped
  results, no index, no regex. The calling LLM supplies the intelligence at
  both ends; for heavy code search, use a real code-search tool.
- **Overviews are mechanical.** Without an agent-written summary they are
  README excerpts, language stats and git logs — useful, not insightful.
  The insight arrives once your agents start leaving summaries behind.
- **Read-only cuts both ways.** There is no refresh tool to call: caches
  refresh lazily on the next commit, and stale summaries are served marked
  as stale until an agent writes a new one.
- **Python ≥ 3.11**, developed and tested on macOS; Linux should behave
  identically, Windows symlink semantics are untested.

## Status

v0.2.2 — working and dogfooded daily. Four read-only tools plus borrowed-LLM
summaries, lazy cache refresh, sensitive-file filtering, and a test suite
proving the security claims (path traversal, symlink escapes, secret
filtering — see `tests/`). API may still change.

## How this was built

To be completely clear about authorship: I am not an engineer. Every
architecture decision in Repiscope is mine — what it does, what it refuses
to do, where the security gates live — but the coding itself is done by
Claude (Anthropic's Fable model). My rule for the collaboration: nothing
goes in that I don't understand. The commit history carries the
co-authorship openly, commit by commit.

## License

[MIT](LICENSE)

---

mcp-name: io.github.3xpr1ment/repiscope