basemind-opencode 0.0.1

package/README.md

@@ -0,0 +1,45 @@
+# basemind-opencode
+
+OpenCode plugin for [basemind](https://github.com/Goldziher/basemind) — a
+tree-sitter code-map + git context MCP server.
+
+## Install
+
+Add to your `opencode.json` (global or project-level):
+
+```json
+{
+  "plugin": ["basemind-opencode@latest"]
+}
+```
+
+Restart OpenCode. The plugin registers the basemind MCP server and the bundled
+skills directory.
+
+You also need the `basemind` binary on your `PATH`:
+
+```bash
+npm install -g basemind        # or: pip install basemind / cargo install basemind
+```
+
+Then scan your repo once before starting OpenCode:
+
+```bash
+cd /path/to/your/repo
+basemind scan
+```
+
+## What this registers
+
+- **MCP server** named `basemind` running `basemind serve` over stdio. Exposes
+  the full code-map and git toolset — `outline`, `search_symbols`,
+  `find_references`, `find_callers`, `recent_changes`, `blame_symbol`, etc.
+- **Skills directory** with two pre-authored skills (`basemind`,
+  `basemind-stats`) that document how to drive the MCP toolset.
+
+See the [root README](https://github.com/Goldziher/basemind#readme) for the
+full MCP tool table, architecture notes, and per-language coverage.
+
+## License
+
+MIT

package/basemind.js

@@ -0,0 +1,51 @@
+/**
+ * basemind plugin for OpenCode.ai
+ *
+ * Registers the basemind MCP server (`basemind serve`) and the skills
+ * directory shipped with the repo. OpenCode discovers the plugin via the
+ * `plugin` array in `opencode.json`; the function exported here is called
+ * once at startup with the live client + directory and returns a config
+ * hook that mutates OpenCode's resolved config in place.
+ *
+ * Exported as both the default and a named export so OpenCode picks it up
+ * regardless of which convention its plugin loader resolves first.
+ */
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Resolve the skills directory across both install modes:
+//   - npm install: skills/ sits next to basemind.js inside
+//     node_modules/basemind-opencode/ (the prepack hook copies it in).
+//   - git+URL / monorepo dev: skills/ lives at the repo root, one level above
+//     opencode-plugin/.
+// Whichever exists wins; this keeps both install paths working without
+// duplicating the dev tree.
+const bundledSkillsDir = path.join(__dirname, "skills");
+const repoSkillsDir = path.join(__dirname, "..", "skills");
+const skillsDir = fs.existsSync(bundledSkillsDir) ? bundledSkillsDir : repoSkillsDir;
+
+const hooks = () => ({
+  config: async (config) => {
+    config.skills = config.skills || {};
+    config.skills.paths = config.skills.paths || [];
+    if (!config.skills.paths.includes(skillsDir)) {
+      config.skills.paths.push(skillsDir);
+    }
+
+    config.mcp = config.mcp || {};
+    if (!config.mcp.basemind) {
+      config.mcp.basemind = {
+        type: "local",
+        command: ["basemind", "serve"],
+        enabled: true,
+      };
+    }
+  },
+});
+
+export const BasemindPlugin = async () => hooks();
+export default async () => hooks();

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "basemind-opencode",
+  "version": "0.0.1",
+  "description": "Tree-sitter code-map + git context MCP server. Use for navigating large or unfamiliar codebases: outline files, find references/callers, search symbols, walk recent history, blame and diff at the symbol level.",
+  "type": "module",
+  "main": "basemind.js",
+  "keywords": [
+    "mcp",
+    "tree-sitter",
+    "code-map",
+    "scanner",
+    "indexer"
+  ],
+  "author": {
+    "name": "Na'aman Hirschfeld",
+    "email": "nhirschfeld@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Goldziher/basemind.git",
+    "directory": "opencode-plugin"
+  },
+  "homepage": "https://github.com/Goldziher/basemind#opencode",
+  "bugs": {
+    "url": "https://github.com/Goldziher/basemind/issues"
+  },
+  "scripts": {
+    "prepack": "rm -rf skills && cp -R ../skills skills",
+    "postpack": "rm -rf skills"
+  },
+  "files": [
+    "basemind.js",
+    "skills/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skills/basemind/SKILL.md

@@ -0,0 +1,135 @@
+---
+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 — code-map MCP server
+
+basemind is a tree-sitter-backed code map plus git context, served over MCP. It
+pre-indexes a repository into a Fjall inverted index so structural and historical
+questions resolve in milliseconds — without you reading whole files.
+
+## 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.
+
+## Tool routing (copy this into your mental model)
+
+| Question | Tool |
+|---|---|
+| "Where is X defined?" | `search_symbols` (substring match, optional `kind` filter) |
+| "What's the shape of file F?" | `outline` (add `l2: true` for calls + docs) |
+| "What calls X?" (any name) | `find_references` |
+| "What calls this specific definition?" | `find_callers` (path + name + optional kind) |
+| "Trace the call graph from a function?" | `call_graph` (BFS up or down, bounded by `max_depth` / `max_nodes`) |
+| "What implements / extends / inherits from X?" | `find_implementations` (Rust, Python, TS/TSX, JS) |
+| "What imports module M?" | `dependents` |
+| "What files are indexed?" | `list_files` (filter by `language` or `path_contains`) |
+| "What changed recently?" | `recent_changes`, `commits_touching`, `find_commits_by_path` |
+| "When did symbol X last change?" | `symbol_history` |
+| "Who wrote this line / symbol?" | `blame_file`, `blame_symbol` |
+| "Where's the churn?" | `hot_files` |
+| "What's dirty in the working tree?" | `working_tree_status` |
+| "What's HEAD / branch?" | `repo_info` |
+| "Show diff between revs for file F" | `diff_file`, `diff_outline` |
+| "What's indexed?" | `status` |
+| "Semantic search over PDFs / Office docs in the repo?" | `search_documents` (requires `--features documents`) |
+| "Recall something the agent stored earlier?" | `memory_get` exact, `memory_list` prefix, `memory_search` KNN |
+| "Remember this for future sessions?" | `memory_put` (delete with `memory_delete`) |
+| "Refresh the index after editing code?" | `rescan` — no MCP disconnect needed; optional `paths` arg |
+| "Fetch next page of results?" | Pass `next_cursor` from prior response as `cursor` |
+| "Pull this URL into RAG?" | `web_scrape` (requires `--features crawl`) — single page, robots-aware |
+| "Ingest a docs site section?" | `web_crawl` — link-following from a seed URL |
+| "What URLs exist on this site?" | `web_map` — sitemap + link discovery, no bodies fetched |
+| "How much has basemind helped today?" | `telemetry_summary` — per-tool histogram + estimated tokens saved |
+
+## Setup (one-time per repo)
+
+basemind needs an index at `.basemind/` before it can answer queries. 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 under `.basemind/`. 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
+search_symbols { needle: "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
+find_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
+outline { path: "src/mcp/tools.rs" }
+→ 21 #[tool] outline (function)
+   112 #[tool] search_symbols (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 — `find_references("bar")` matches `Foo::bar()`
+  and `bar()` alike. There is no scope resolution; cross-check with `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.
+- Intelligence tools (`search_documents`, `memory_*`) 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 ingestion tools (`web_scrape`, `web_crawl`, `web_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 under
+  scope `web:<host>`; `search_documents { query: ..., scope: "web:<host>" }` retrieves them.
+  robots.txt is honoured by default; only `[crawl].respect_robots_txt = false` in
+  `.basemind/basemind.toml` (config-file-only) disables it.

package/skills/basemind-stats/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: basemind-stats
+description: >-
+  Show a quick dashboard of basemind activity in this session: how many code-map
+  tool calls have run, the per-tool histogram, and the estimated tokens saved vs
+  a hypothetical grep+Read baseline. Use when the user asks "what has basemind
+  done?", "how much is basemind helping?", "show me basemind stats", or invokes
+  `/basemind-stats` directly.
+---
+
+# basemind-stats — on-demand usage dashboard
+
+Call the `telemetry_summary` MCP tool and render the result as a markdown report.
+
+## What to do
+
+1. Call `telemetry_summary` with `{ "window": "today" }` (the default). If the
+   user asks for a specific range, map it to one of `"today"`, `"1h"`, `"24h"`,
+   `"all"`.
+2. Render a markdown block in this shape:
+
+   ```text
+   ## basemind activity (today)
+   - **N tool calls** ; top tools: outline (18), search_symbols (12), …
+   - **~K tokens saved** vs grep + Read baseline
+   - recent: outline (4ms, 312B), search_symbols (2ms, 180B), …
+   ```
+
+3. If `total_calls` is 0, say so plainly ("no basemind activity in the window yet").
+   Don't pretend to have data.
+4. **Always disclose the savings model.** Add one sentence at the end:
+
+   > Savings are heuristics. Tools with no realistic baseline (memory, document
+   > search, git wrappers) report 0 saved — see the `saved_baseline` column on
+   > each row.
+
+   The exact wording can vary; the principle (it's an estimate, here's why) cannot.
+
+## When the user asks "--explain"
+
+If they invoke `/basemind-stats --explain` or ask how the savings number is
+derived, include the per-baseline breakdown from the `per_baseline` field of the
+response and call out which tools fall into which bucket. The estimator lives in
+`src/mcp/savings.rs` if they want to read the code.
+
+## Don't
+
+- Don't auto-display the dashboard at the start of every conversation. This skill
+  is strictly user-invoked.
+- Don't pad missing data. If `recent` is empty, say so; don't invent example rows.
+- Don't claim a token-savings number without the disclosure sentence.