MCP Tools Reference

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 and 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 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 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 and Shared 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 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 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 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.

Note

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.

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 for details.