Agent skill

Basemind Code Context

by Goldziher in Goldziher/basemind

Answers structural questions about a repository, such as where a symbol is defined, what calls it and what changed recently, through the basemind MCP server.

MITAuto-check passedDevelopment

Install Basemind Code Context

skills CLI
$ npx skills add Goldziher/basemind --skill basemind -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install Goldziher/basemind basemind --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/Goldziher/basemind.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/basemind .claude/skills/basemind && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
basemind
GitHub stars
108
Token cost
~2.6k tokens
SKILL.md length
1,296 words
Files
1
Skills in repo
10
Repo updated
First seen
Licence
MIT

At a glance

Answers structural questions about a repository, such as where a symbol is defined, what calls it and what changed recently, through the basemind MCP server.

  • Asking where a function or type is defined in an unfamiliar codebase
  • SKILL.md covers Capabilities, Dedicated per-capability skills, When to reach for it (instead… and Context economy — the…, plus 4 more sections
  • Calls git; reaches github.com
  • Finding what calls a function or which modules depend on it

What it does

Basemind pre-indexes a repository into a local store and serves it over MCP, so the agent can request outlines, symbol search, references, callers, call graphs, history, blame and diffs instead of reading whole files. The skill tells the agent to use it before opening more than two or three files just to learn structure. The tools return paths and line numbers, and files are read only where a closer look is needed.

Beyond the code map, which spans 300+ languages through tree-sitter, the same server offers full-text and symbol search, git history and blame at symbol level, document search over 90+ file formats including PDFs, Office files and images with OCR, shared per-repo memory across sessions, and web crawling into a searchable store. Narrower companion skills cover code search, git history, documents, communication between agents and the CLI.

When your agent uses it

  • Asking where a function or type is defined in an unfamiliar codebase
  • Finding what calls a function or which modules depend on it
  • Checking what changed recently in a file or who last touched a line
  • Getting a file's outline before deciding whether to read it

Example prompts

  • “Where is process_file defined, and what calls it?”
  • “What changed in foo.rs over the last 20 commits?”
  • “Show me every type whose name ends in Service.”

Requirements

  • The basemind MCP server with an index of the repository

What it can do on your machine

Read from SKILL.md and the folder at commit 2f6da31. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • git

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Hosts in commands or code, which the agent is likely to contact:

    • github.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Basemind Code Context loads about 2.6k tokens when it runs. Until then it costs about 95 tokens; SKILL.md has 1,296 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~95
When it runs · the whole SKILL.md, loaded when a task matches
~2.6k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from Goldziher/basemind at commit 2f6da31, republished under its MIT licence (© Goldziher). 1,296 words, ~2,553 tokens.

Download SKILL.mdSave it as .claude/skills/basemind/SKILL.md (or your agent's skills folder).
name
basemind
description
Navigate large or unfamiliar codebases via the basemind MCP server — outlines, symbol search, reference/caller lookups, commit history, blame, and diffs without reading source files. Reach for it whenever the user asks "where is X defined", "what calls Y", "what changed recently in Z", or whenever you're about to grep or open many files to find structural information.

basemind — the indexed context layer

basemind is the full context layer for this repository, served over MCP. It pre-indexes the repo into a content-addressed blob store + Fjall inverted index (and, when enabled, a LanceDB vector store) so structural, historical, and semantic questions resolve in milliseconds — without you reading whole files.

Capabilities

  • Code map across 300+ languages — tree-sitter outlines, symbol search, references, callers, call graphs, implementations, dependents.
  • Full-text + symbol search — code modes grep and symbols.
  • Git intelligence — history, blame, and structural diffs at symbol resolution, plus churn.
  • Document RAG over 90+ file formats — PDFs, Office, HTML, email, images (OCR) → semantic search with cross-encoder reranking (memory mode documents).
  • Shared memory — per-repo, scope-keyed key-value + semantic memory across sessions.
  • Web crawl — scrape / follow-link crawl into the same searchable document store.

Dedicated per-capability skills

This umbrella skill covers the whole surface. For focused workflows, reach for the dedicated skills:

  • basemind-code-search — outlines, symbol search, references, callers, call graphs.
  • basemind-git-history — history, blame, structural diffs, churn.
  • basemind-documents — document RAG (memory mode documents), web ingestion, memory.
  • basemind-comms — coordinating with other agents in the same repo over the broker.
  • basemind-cli — the same surface driven headlessly from the CLI.

When to reach for it (instead of grep / read_file)

Use basemind for:

  • Locating a symbol: "where is Foo defined?", "find the constructor for Bar", "show me every type ending in Service".
  • Following call graphs: "what calls process_file?", "who depends on this module?".
  • Mapping a file's shape before reading it: which symbols, in what order, with what signatures.
  • Walking recent history: "what changed in this file in the last 20 commits?", "when did this symbol last change?".
  • Blame and ownership: "who last touched this function?", "what commit introduced this line?".
  • Diffing across revisions: "what symbols did this branch add?", "show the hunks for foo.rs between HEAD~5 and HEAD".

If you are about to open more than two or three files just to learn structure, stop and use basemind first. The tools return paths + line numbers; you only read_file once you know exactly which span you need.

Context economy — the operating discipline

basemind tools return paths, line numbers, and signatures — not file bodies, so a structural answer costs a fraction of the tokens of reading source. Treat that as the default workflow, not an optimization:

  • Use code mode outline before you open a file. Read the whole file only when you have already identified the exact span you need from the outline; then read_file that range, not the file.
  • Use code mode symbols instead of grep/rg for a definition. It matches indexed symbol names and returns path:line, skipping the comment/string/test-name noise grep drowns you in.
  • Use code modes references / callers instead of grepping call sites. Indexed call edges, not text matches.
  • Use code mode grep instead of shelling out to ripgrep when you genuinely need regex over content — it runs over the in-RAM index and returns capped, structured hits.
  • Use admin mode rescan after you edit code, not a server reconnect. Pass paths: [...] to limit it to the files you touched.
  • Do not re-read a file basemind already mapped. If the outline answered the question, stop.

Rule of thumb: if a question is about where, what calls, what shape, who changed, or what's indexed, a basemind tool answers it cheaper than reading files. Reach for read_file only to see the actual implementation of a span you have already located.

basemind first, shell/grep/git fallback. Prefer basemind over reading files, over grep/rg, and over naked git: use it for code parsing (outlines, references, callers), git history / blame / diffs, document extraction / RAG / keyword + entity (NER) / summary (memory mode documents), and web modes scrape / crawl / map. Drop to raw shell, grep, or git only when no basemind tool covers the question.

Tool routing (copy this into your mental model)

QuestionTool
"Where is X defined?"code { mode: "symbols", name: X } (substring; optional kind)
"Jump to the definition of X used here?"code { mode: "definition", path, line, column? }
"What's the high-level architecture / module map?"graph { mode: "map" }
"What's the shape of file F?"code { mode: "outline", path: F, l2?: true }
"What calls X?" (any name)code { mode: "references", name: X }
"What calls this specific definition?"code { mode: "callers", path: F, name: X }
"Trace the call graph from a function?"graph { mode: "calls", name: X }
"What implements / extends / inherits from X?"code { mode: "implementations", trait_name: X }
"What imports module M?"code { mode: "dependents", module: M }
"What files are indexed?"code { mode: "files" }
"What changed recently?"git modes recent, touching, or by_path
"When did symbol X last change?"git { mode: "symbol_history", path: F, name: X }
"Who wrote this line / symbol?"git mode blame or blame_symbol
"Where's the churn?"git { mode: "churn" }
"What's dirty in the working tree?"git { mode: "status" }
"What's HEAD / branch?"admin { mode: "repo" }
"Show diff between revs for file F"git mode diff or diff_outline
"What's indexed?"admin { mode: "status" }
"Semantic search over PDFs / Office docs?"memory { mode: "documents", query }
"Recall something the agent stored earlier?"memory mode get, list, or search
"Remember this for future sessions?"memory { mode: "put", key, value }
"Refresh the index after editing code?"admin { mode: "rescan", paths?: […] }
"Fetch next page of results?"Pass next_cursor from prior response as cursor
"Pull this URL into RAG?"web { mode: "scrape", url } — single page, robots-aware
"Ingest a docs site section?"web { mode: "crawl", url } — link-following from a seed
"What URLs exist on this site?"web { mode: "map", url } — discovery without bodies
"How much has basemind helped today?"admin { mode: "telemetry", window: "today" }
Show full SKILL.md (391 more words)Show less

Setup (one-time per repo)

basemind needs an index before it can answer queries. The index lives in a machine-global cache (Linux ~/.local/share/basemind/, macOS ~/Library/Application Support/basemind/; override BASEMIND_DATA_HOME), keyed by workspace — never inside your repo. From the repo root:

sh
basemind scan

This walks the tree, parses with tree-sitter, and writes a content-addressed blob store + Fjall inverted index into the machine-global cache. A few seconds for small repos, ~22 s for an ~80k-file TypeScript monorepo.

The MCP server is launched by the host (basemind serve — wired up in .claude-plugin/plugin.json for you). You do not start it manually.

Re-run basemind scan after large changes, or run basemind watch to keep the index fresh on file save.

If a tool returns "no indexed files", that means basemind scan hasn't been run in this repo yet.

Examples

Locating a symbol
text
code { mode: "symbols", name: "MapCache" }
→ src/mcp/mod.rs:79:1 MapCache (struct)
  src/mcp/mod.rs:88:1 MapCache (impl)

Now you know exactly where to read.

Following references
text
code { mode: "references", name: "process_file" }
→ src/scanner.rs:142:9 process_file
  src/scanner.rs:201:13 process_file
  ...

No need to grep — the index already knows.

Outline a file before reading
text
code { mode: "outline", path: "src/mcp/tools.rs" }
→ 21 code router (function)
   112 code helper (function)
   ...

A 1000-line file becomes a 30-line table of contents.

Notes

  • All paths are repository-relative with forward-slash separators.
  • Lists are capped (limit, default 100, max 1000). Index scanners use scan_cap = limit * 8 to bound work on common names.
  • Matching is substring on names — code mode references with name: "bar" matches Foo::bar() and bar() alike. There is no scope resolution; cross-check with mode outline if disambiguation matters.
  • Git tools require basemind serve to be running inside a git repository. Outside a git repo they return a clear error.
  • memory modes require basemind to be built with --features full (or the individual documents / memory flags). Without them the tools dispatch but return an MCP error. Memory is scoped by the normalised origin remote URL (git@github.com:Foo/bar.git and https://github.com/Foo/bar/ collapse to the same scope key) — clones of the same repo share memory; unrelated repos do not see each other's entries.
  • web modes scrape, crawl, and map require --features crawl. When that feature is off they are NOT registered on the server at all — agents will simply not see them in the tool list. Crawled pages land in the documents LanceDB table tagged with scope web:<host>; memory mode documents finds them alongside every other ingested document. It searches across ALL documents and has no scope parameter — you cannot filter results to a single host at query time. robots.txt is honoured by default; only [crawl].respect_robots_txt = false in the repo-root basemind.toml (config-file-only) disables it.

© Goldziher, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/basemind of Goldziher/basemind.

Open the folder on GitHubat commit 2f6da31

Compare with similar skills

Basemind Code Context next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Basemind Code Context compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Basemind Code Context this skillGoldziher/basemind108—~2.6kAutomated safety check: PassMIT
trace-mcp Code Navigationnikolai-vysotskyi/trace-mcp188—~1.6kAutomated safety check: NotesMIT
Codebase SearchHelweg/open-codebase-index216—~1.3kAutomated safety check: PassMIT
Codebase Search WorkflowHelweg/open-codebase-index216—~822Automated safety check: PassMIT
Lumen Doctorory/lumen307—~339Automated safety check: PassCustom licence
tilth Code Reading CLIjahala/tilth352—~1.1kAutomated safety check: PassMIT

Similar skills

  • trace-mcp Code Navigation

    nikolai-vysotskyi/trace-mcp

    Routes code exploration through trace-mcp's indexed dependency graph, using symbol search, outlines, call graphs and change-impact tools instead of Read, Grep and Glob.

    188 GitHub stars~1.6k tokensUpdated today
    DevelopmentAuto-check: notes
  • Codebase Search

    Helweg/open-codebase-index

    Chooses the right retrieval tool for code questions: compact context for unfamiliar repos, direct lookup for known symbols, call graphs for relationships and grep for exhaustive matches.

    216 GitHub stars~1.3k tokensUpdated today
    Agent WorkflowsAuto-check passed
  • Codebase Search Workflow

    Helweg/open-codebase-index

    Directs an agent to use a local codebase index for repository orientation, definition lookups, call graphs and semantic search before turning to web lookups.

    216 GitHub stars~822 tokensUpdated today
    Agent WorkflowsAuto-check passed
  • Lumen Doctor

    ory/lumen

    Checks the Lumen semantic search setup for the current project: embedding service reachability, index freshness and storage totals, with remediation notes.

    307 GitHub stars~339 tokensUpdated 1 mo ago
    Agent WorkflowsAuto-check passed
  • Replaces grep, cat, find and ls with the tilth CLI, which returns AST-aware outlines, definitions, usages and callers across many languages in one call.

    352 GitHub stars~1.1k tokensUpdated 12 days ago
    DevelopmentAuto-check passed
  • Smart Explore Code Search

    thedotmack/claude-mem

    Explores code structure with tree-sitter AST search tools, getting a ranked symbol map and file outlines before reading full source, to save tokens.

    99k GitHub stars~2.3k tokensUpdated today
    DevelopmentAuto-check passed

More from Goldziher/basemind

All 10 skills in this repo
  • Basemind Usage Stats

    Goldziher/basemind

    Shows a markdown dashboard of basemind activity in the session: tool call counts, top operations and estimated tokens saved against a grep and Read baseline.

    108 GitHub stars~558 tokensUpdated yesterday
    Auto-check passed
  • Basemind Index Scan

    Goldziher/basemind

    Builds or refreshes the basemind code index from the command line, for when basemind reports no index or its MCP server is not running.

    108 GitHub stars~997 tokensUpdated yesterday
    Auto-check: warnings
  • Drives the basemind code-intelligence tool from the command line for symbol search, callers, git history and blame, document search and web crawling, sharing its cache with the MCP server.

    108 GitHub stars~2k tokensUpdated yesterday
    Auto-check passed
  • Basemind Code Search

    Goldziher/basemind

    Answers where code is defined, who calls it and what shape a file has from a pre-built index, returning paths and line numbers instead of file contents.

    108 GitHub stars~1.3k tokensUpdated yesterday
    Auto-check passed
  • Basemind Doctor

    Goldziher/basemind

    Diagnose and recover basemind when it isn't working — MCP tools missing or erroring, "no index" / "no indexed files", empty results that shouldn't be empty, or the MCP server seems dead.

    108 GitHub stars~1.1k tokensUpdated yesterday
    Auto-check passed
  • Basemind Documents

    Goldziher/basemind

    Semantic + full-text search over documents and the web via basemind's RAG store — PDFs, Office, HTML, email, images (OCR), plus scraped/crawled web pages, with cross-encoder reranking, keyword and…

    108 GitHub stars~1.2k tokensUpdated yesterday
    Auto-check passed

Questions about Basemind Code Context

What does Basemind Code Context do?

Answers structural questions about a repository, such as where a symbol is defined, what calls it and what changed recently, through the basemind MCP server. Basemind pre-indexes a repository into a local store and serves it over MCP, so the agent can request outlines, symbol search, references, callers, call graphs, history, blame and diffs instead of reading whole files. The skill tells the agent to use it before opening more than two or three files just to learn structure.

When should I use Basemind Code Context?

Basemind Code Context fits situations like: asking where a function or type is defined in an unfamiliar codebase; finding what calls a function or which modules depend on it; checking what changed recently in a file or who last touched a line; getting a file's outline before deciding whether to read it.

How do I install Basemind Code Context in Claude Code?

Run `npx skills add Goldziher/basemind --skill basemind -a claude-code`. Or copy the skill folder (skills/basemind in Goldziher/basemind) into .claude/skills/basemind in your project. Claude Code loads it when a task matches its description.

How do I install Basemind Code Context in Codex?

Run `npx skills add Goldziher/basemind --skill basemind -a codex`. Or copy the skill folder (skills/basemind in Goldziher/basemind) into .agents/skills/basemind in your project. Codex loads it when a task matches its description.

Can I use Basemind Code Context in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add Goldziher/basemind --skill basemind -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/basemind, .gemini/skills/basemind, .github/skills/basemind and .opencode/skills/basemind in your project.

What does Basemind Code Context need to run?

Going by SKILL.md and its folder, Basemind Code Context needs the command-line tools its instructions call (git). Our summary lists: The basemind MCP server with an index of the repository.

Does Basemind Code Context access the network?

SKILL.md names 1 domain. In commands or code: github.com; the agent is likely to contact it when it follows the instructions. This is read from the text; nothing was executed.

Is Basemind Code Context safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Basemind Code Context use?

Basemind Code Context is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Basemind Code Context use?

About 2.6k tokens (SKILL.md is roughly 10k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Basemind Code Context?

Skills that share tags, products or a category with Basemind Code Context: trace-mcp Code Navigation (nikolai-vysotskyi/trace-mcp, 188 stars), Codebase Search (Helweg/open-codebase-index, 216 stars), Codebase Search Workflow (Helweg/open-codebase-index, 216 stars) and Lumen Doctor (ory/lumen, 307 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Basemind Code Context?

Goldziher (a GitHub user) maintains it in Goldziher/basemind, which has 108 GitHub stars. The repository holds 10 skills in this directory. The repository was last updated on October 8, 2026.

Source: Goldziher/basemind on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.