Ark
Code intelligence engine for AI coding agents.
Code intelligence engine for AI coding agents.
日本語 · Getting started · MCP tools · Resolution model · Architecture
Ark parses a repository, extracts its declarations and references, resolves what each reference points to, and serves the resulting graph to coding agents over the Model Context Protocol. An agent can ask who calls a function, what a change may affect, or which code it needs to read before editing — and get an answer that states how certain it is.
Ark is a single static binary. It analyzes Go, TypeScript, TSX, PHP, Terraform, Rust, Java, Zig, JavaScript, Python, YAML (including GitHub Actions workflows and actions), TOML (Cargo, pyproject), XML (Maven POM) and Markdown without running any code from the repository.
Why Ark
An agent working in a large repository usually navigates by text search and by reading whole files. That has costs that grow with the repository:
- Context is spent on irrelevant code. Finding one function means reading the files around every match.
- Names are ambiguous.
Savemay be declared in five packages; a text match cannot tell which one a call reaches. - Relationships are guessed. A function with the same name in another package, or another language, looks like a caller.
- Unknowns look like answers. "No other callers found" may mean there are none, or that the search could not see them.
Ark addresses these with structure and evidence:
| Problem | What Ark provides |
|---|---|
| Too much text | Declarations, call relationships and token-budgeted context for one symbol, instead of whole files |
| Ambiguous names | Every declaration has its own symbolId; ambiguous queries return the list of declarations, never a silent pick |
| Guessed relationships | References resolved by each language's scoping rules: imports, packages, receivers, namespaces. Names never match across languages |
| Hidden unknowns | Every answer carries a confidence level and counts what Ark saw but could not resolve |
How it works
repository files
│
▼
language providers Tree-sitter parsing (HTML: x/net/html; CSS: CSS Syntax 3), one file at a time:
│ declarations, references, imports, language evidence
▼
index builder symbols with stable IDs, containment
│
▼
resolver evidence → candidates + confidence (exact / strong / candidate)
│
▼
graph edges only from a unique exact or strong resolution;
│ everything else counted, never dropped
▼
context · impact · repository map · search
│
▼
MCP server ──────► coding agent
The index is built on the first request and reused while the source files are unchanged; extraction results are cached on disk between sessions. Details: ARCHITECTURE.md, Operations.
Quick start
1. Install
brew install magicdrive/tap/ark
Or, on macOS and Linux without Homebrew, the install script (into ~/.local/bin; see
Installation for its options and checks, the archives and building from
source):
curl -fsSLO https://raw.githubusercontent.com/magicdrive/ark/main/install.sh
sh install.sh
2. Connect your agent — in the repository root:
ark setup claude # Claude Code
ark setup cursor # Cursor
ark setup codex # Codex
ark setup cline # Cline CLI
ark setup copilot-vscode # GitHub Copilot in VS Code
ark setup copilot-cli # GitHub Copilot CLI
setup adds Ark's entry to the client's MCP configuration and leaves every
other entry untouched. Restart the client and approve the server.
3. Tell the agent how to use it (optional, recommended):
From the project's README.