ezzy1630/argyph

---

Most developers stitch together a half-dozen MCP servers to give an AI agent context over a codebase — one for grep, one for embeddings, one for symbol search, one for repo packing. Each is a separate install, a separate process, and (often) a separate cloud account. Argyph replaces all of them with a single local binary. It indexes incrementally and is ready in under a second on previously-indexed repos — no daemon, no account, no API key.

The name is a portmanteau of Argus (the hundred-eyed watcher of Greek myth) and Glyph (a carved symbol with bound meaning) — a server that watches a codebase and gives the agent its symbols.

✨ What it does

Argyph exposes three pillars of context behind one MCP endpoint:

[!NOTE] Everything is read-only. Argyph never edits, commits, or executes code.

Local-first by design. Every tier runs on the developer’s machine — your proprietary code never touches a cloud vector DB or a remote embedding API, and a bundled embedding model means full functionality with zero keys.

📥 Install

Current release: v1.0.4 — published on npm, crates.io, the Homebrew tap, and as prebuilt GitHub-release binaries.

Claude Code (recommended):

claude mcp add argyph -- npx argyph@latest

npm / npx:

npx argyph

🚀 Quick start

# In any repo
cd ~/code/your-repo
argyph init
claude mcp add argyph -- npx argyph@latest
claude

In the chat:

What does this codebase do, and where is session expiration controlled?

Behind the scenes the agent calls ask, and Argyph returns bounded spans — not whole files — so the agent reads only what matters:

{
  "spans": [
    {
      "file": "src/auth/session.rs",
      "start_line": 41,
      "end_line": 55,
      "text": "fn is_expired(&self, now: Instant) -> bool { ... }",
      "kind": "definition",
      "symbol": "is_expired",
      "language": "rust"
    }
  ],
  "strategy_used": "definition"
}

Argyph indexes Tier 0 in under a second on first run, Tier 1 (symbol graph) in seconds, and Tier 2 (embeddings) in the background. You can query immediately — tools return what’s available now plus an index_coverage field so the agent knows.

⚙️ How it works

Argyph builds the index in three tiers, each useful before the next completes:

The 80/20 insight: most agent queries are structural (where is parseConfig defined?, what calls validateUser?) and don’t need embeddings. Argyph serves those from Tier 1 in milliseconds, even while Tier 2 is still building.

After the first index, the on-disk .argyph/ directory persists and only changed files are reprocessed on subsequent runs. A filesystem watcher keeps everything live.

🧰 Tools

🆚 Why Argyph (vs alternatives)

Argyph is the only one that’s all five — symbol graph and semantic search, local-first, one install, incremental.

📊 Benchmarks

Full methodology and reproduction steps are in docs/benchmarks.md — reproduce locally with cargo bench --workspace. Numbers below are the median of three runs on the reference hardware tagged m4-air (Apple M4 MacBook Air, 16 GB RAM, macOS 26) unless stated otherwise.

🏗️ Architecture

Argyph is a Rust workspace of twelve focused crates with strict module ownership. The full architecture — including the Supervisor lifecycle, the three-tier indexing model, and per-crate responsibility boundaries — is documented in ARCHITECTURE.md.

📦 Project status

Stable. v1.0.x is published on all channels. Active development continues against the milestones at the top of ROADMAP.md; the build plan is in docs/BUILD_PLAN.md.

🤝 Contributing

Argyph is built with substantial AI assistance, but human-architected and human-reviewed. Contribution guide and the (strict) AI agent rules are in CONTRIBUTING.md. Commit conventions, including the project’s attribution policy, are in docs/COMMIT_CONVENTIONS.md.

👤 Author

Built by Ezzy1630. See AUTHORS.md.

📄 License

Dual-licensed under either of:

• MIT License (LICENSE-MIT)
• Apache License 2.0 (LICENSE-APACHE)

at your option.