---
title: MCP Tools Reference
description: Complete catalog of basemind's nine domain tools, one section per domain.
---
import { Aside, Badge } from '@astrojs/starlight/components';
basemind exposes **nine domain tools** over stdio MCP — `code`, `graph`, `git`, `memory`, `admin`,
`web`, `agents`, `workspace`, `shell` — each dispatching on a required `mode` rather than one tool
per operation. The CLI mirrors the same nine groups (`basemind <domain> <mode>`), enforced as a
strict bijection by the test suite. All paths are byte-precise repo-relative (`RelPath`). Lists are
capped at 1000 items, 100 by default; index scans use `scan_cap = limit * 8` to bound work on common
names. Mode descriptions state matching semantics (substring, prefix, scope-aware) and what's
indexed (name-only vs scope-resolved) — they're the routing surface an agent searches by, so read
them before guessing.
## `code` — code-map lookups
Query your project's structure across **300+ languages** via tree-sitter: symbols, references,
calls, and definitions.
| Mode | Purpose | Matching |
|---|---|---|
| `outline` | A file's full structure: symbols, line/col, signatures, imports — read this instead of the file. | scope-aware |
| `symbols` | Find a definition by name across every indexed file. | substring |
| `grep` | Pattern search across the workspace, filtered by language or path. | regex |
| `files` | Enumerate indexed files, optional `path_contains` and `language` filters. | substring |
| `find` | Locate a file by a fuzzy fragment of its name or path (fzf/fd-style, nucleo-matcher ranked). | fuzzy substring |
| `definition` | Resolve a reference position to the definition it binds to. | scope-aware |
| `references` | Every call site of a name — no scope resolution; `Foo::bar()` and `bar()` both match `name="bar"`. | substring |
| `callers` | Callers of one specific definition, disambiguated by path — resolves the definition first, then runs the same name-based scan as `references`. | resolves def, then name-only |
| `implementations` | Types implementing or inheriting a trait, interface or base class. | substring |
| `dependents` | Heuristic reverse lookup: what imports a given module. | import-based |
| `expand` | One symbol's raw source body — the inverse of an outline entry. | — |
| `semantic` | Search code by meaning over indexed chunks; returns pointers, fetch bodies with `chunk`. Needs `--features code-search`. | vector + BM25 + symbol |
| `chunk` | Fetch one code chunk's source body (pairs with `semantic`). | — |
See [Code Intelligence](/capabilities/code-intelligence/) and [Code Search](/capabilities/code-search/)
for detailed examples.
## `graph` — the unified code graph
Walk the typed code graph built from resolved calls, imports, and containment. Every edge carries
provenance and confidence; every result is deterministic and bounded.
| Mode | Purpose |
|---|---|
| `calls` | Rooted call BFS: walk the call chain up (`callers`) or down (`callees`) from one definition, depth-bounded. |
| `neighbors` | The n-hop neighborhood around a symbol (`direction` / `edges` / `depth` / `min_confidence` / `max_nodes`). |
| `path` | The confidence-weighted shortest path between two symbols; containment excluded unless `include_contains`. |
| `subgraph` | A symbol's neighborhood cut to its most central nodes. |
| `communities` | Cluster the graph into its de-facto modules (`label_propagation` default, `louvain` opt-in). |
| `map` | Whole-repo architecture: hub modules ranked by PageRank + git churn, plus dependency cycles (SCCs). |
| `export` | Render the graph as node-link JSON, DOT, Mermaid, GraphML, Cypher, or offline interactive HTML. |
| `display` | Open a rendered view in a human's desktop viewer. |
| `open` | Return a live browsable URL for the interactive graph page. Both `display` and `open` accept `open: false` to return the path/URL without launching anything. |
See [Code Intelligence](/capabilities/code-intelligence/) for examples.
## `git` — git history
Query your repository's history, blame, diffs, and churn — powered by `gix` with a built-in history
index for microsecond latency.
| Mode | Purpose | Scope |
|---|---|---|
| `status` | Staged and unstaged files right now. | — |
| `recent` | Recent commits with their touched paths and summaries. | branch depth |
| `touching` | Commits that modified a given path. | posting-list (indexed) |
| `by_path` | Path-filtered commit log (regex over changed paths). | branch depth |
| `churn` | Files ranked by how often they change. | branch depth |
| `diff` | A file's textual diff between two revisions. | — |
| `diff_outline` | Which symbols a file gained, lost, or changed between revisions. | scope-aware |
| `blame` | Who last changed each line of a file. | per-line |
| `blame_symbol` | Who last changed one symbol, resolved to its line span. | per-symbol |
| `symbol_history` | When a symbol's body actually changed, by structural hash. | commit walk |
| `search` | Full-text search over commit messages and authors, at full branch depth. | branch depth |
See [Git Intelligence](/capabilities/git-intelligence/) for examples.
## `memory` — shared memory, documents, and proposals
A per-repo memory agents write to and search by meaning (clones of the same repo share it, unrelated
repos stay separate), semantic search over indexed documents, and a review queue of notes mined from
files that change together.
| Mode | Purpose | Scope |
|---|---|---|
| `put` | Write a durable note other sessions and agents will read. | per-repo |
| `get` | Read one memory entry by key. | per-repo |
| `list` | Enumerate memory entries, newest first, optional prefix/tag filter. | per-repo |
| `search` | Semantic search across stored memory. | per-repo |
| `delete` | Remove a memory entry by key. | per-repo |
| `audit` | The write history behind a memory entry; also recomputes verdicts and archives stale entries. | per-repo |
| `documents` | Semantic search over indexed PDFs, Office files, and HTML instead of opening them. Needs `--features documents` (or `full`). | per-scope |
| `mine` | Derive co-change proposals from git history. | per-repo |
| `proposals` | List proposals awaiting review. | per-repo |
| `accept` | Accept a proposal into memory. | per-repo |
| `reject` | Reject a proposal. | per-repo |
See [Document Search](/capabilities/document-search/) and [Shared memory](/concepts/memory/) for
examples.
## `admin` — server and cache administration
Refresh the index, inspect health and cache footprint, and shrink what an agent carries.
| Mode | Purpose |
|---|---|
| `status` | Index health for this workspace: file counts, languages, scan age. |
| `repo` | Repository identity and layout: root, git remote, branch, view. |
| `rescan` | Re-index changed files, or the whole workspace when no paths are given. |
| `cache_stats` | On-disk size and entry counts for the machine-global cache. |
| `gc` | Report blobs no live view references — non-destructive, deletes nothing. |
| `cache_clear` | Delete this workspace's cached index outright. |
| `telemetry` | Aggregate recorded tool calls into a usage and token-savings summary. |
| `compress` | Shrink a prior tool response, a file's outline, or prose for re-use in a smaller context. |
| `delta` | What changed in a response since a named checkpoint. |
| `checkpoint` | Name the current response so a later delta can diff against it. |
| `waste` | Flag repeated or redundant tool calls in this session. |
## `web` — web crawl
Fetch and index web pages; results join the document search index. Requires `--features crawl`.
| Mode | Purpose |
|---|---|
| `scrape` | Fetch one URL, extract markdown, and index it into the documents store. |
| `crawl` | Follow links breadth-first from a seed URL and index every page. |
| `map` | Discover a site's URLs from its sitemap and link map, without fetching bodies. |
See [Web Crawl](/capabilities/web-crawl/) for examples.
## `agents` — multi-agent coordination
A shared chat layer for agents on the same repo: threads addressed by at least two of subject /
path-glob / members, discovered by scope (member, cwd path-match, or subject filter — never global),
with a recency-filtered inbox. Requires `--features comms`.
| Mode | Purpose |
|---|---|
| `register` | Publish or update this agent's identity card with the broker. |
| `list` | The agents the broker knows, optionally restricted to one thread. |
| `thread_start` | Open a thread addressed by subject, path-glob and/or members. |
| `thread_list` | Threads discoverable to you: membership, cwd path-match, or subject. |
| `join` | Join a thread so its messages reach your inbox. |
| `leave` | Leave a thread you joined. |
| `members` | Who belongs to a thread. |
| `add_member` | Add an agent to a thread you created. |
| `remove_member` | Remove an agent from a thread you created. |
| `archive` | Close a thread; creator or human admin only. |
| `post` | Send a message to a thread. |
| `history` | A thread's messages as front-matter only; bodies come from `message`. |
| `message` | Read one message body by id — the only path to a body. |
| `inbox` | Unread messages across your joined threads, front-matter only. |
| `ack` | Clear messages you have read from your inbox. |
| `wait` | Block until a peer posts, or until the timeout elapses — a long-poll replacement for looping `inbox` / `thread_list`. |
See [Agent Comms](/concepts/agent-comms/) for orchestration examples.
## `workspace` — machine registry
Coordinate across every repo and worktree the daemon knows about on this machine. The registry is
daemon-managed; claims are advisory (no locking) but help avoid collisions. Requires
`--features comms`.
| Mode | Purpose |
|---|---|
| `workspaces` | Every repository the machine daemon has indexed. |
| `worktrees` | Git worktrees of this repository, with their branches and claims. |
| `branches` | Branches known to this repository. |
| `claim` | Take ownership of a worktree so another session does not edit it. |
| `release` | Give up a worktree claim this session holds. |
See CLI: `basemind workspace` (worktree/branch listing), `basemind statusline` (current status).
## `shell` — agent shells
Let agents spawn, type into, and read terminal sessions in the background. Requires
`--features shells`.
| Mode | Purpose |
|---|---|
| `spawn` | Start a background terminal session running a command (`--cwd`, `--env`, `--title`). Returns `session_id`. |
| `send` | Type into a live session (`--no-enter` to suppress the trailing newline). |
| `capture` | Read back what a session has printed (`--lines` to limit). |
| `kill` | Terminate a session. |
| `list` | Every session the shell daemon currently hosts, with liveness. |
| `broadcast` | Type the same input into several sessions at once. |
See [Agent Shells](/capabilities/agent-shells/) for examples.
## Metadata & pagination
All list-returning modes:
- **`limit`** parameter: 1–1000 items (default 100).
- **`cursor`** for pagination: opaque token returned in response; pass back to continue.
- **`any_truncated`** flag: set to `true` if the result hit the limit and more results exist.
For index scans (`code` modes `symbols` / `references` / `callers` / `implementations`), basemind
internally uses `scan_cap = limit * 8` to bound work on common names.
<Aside>
Mode descriptions are the routing surface for agents. Read them carefully — they describe matching
semantics (substring vs. prefix), scope resolution (name-only vs. scope-aware), and what each mode
trades off. This helps agents pick the right mode for the question.
</Aside>
## Lifecycle notices
`basemind serve` warms the code map in the background after answering the MCP handshake. While
it isn't fully ready, `admin status` and every `code` read mode may include a `notice` object instead
of, or alongside, their normal result:
| Field | Meaning |
|---|---|
| `state` | One of `warming_up`, `building_index`, `rescanning`. |
| `message` | Human/agent-readable explanation of what's happening. |
| `retry` | `true` to retry shortly for complete results; `false` if the result is usable but may be stale. |
`admin status` additionally reports `warming` / `warm_ms` (in-memory preload of an existing index)
and `indexing` / `index_build_ms` (first-time index build). Treat an empty or partial result carrying
a `notice` as "retry shortly," not "no matches." See
[Index lifecycle and freshness](/concepts/how-it-works/#index-lifecycle-and-freshness) for details.