From 13e49bd4225eab7bb65e8f51c042fc14eb44039f Mon Sep 17 00:00:00 2001 From: Stefano Mioli Date: Sun, 26 Apr 2026 02:59:16 +0200 Subject: [PATCH] docs: agent-required framing in MCP section + AGENTS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README: - The MCP section now states explicitly that cli-bridge is the recommended path for agentic use, with the underlying reason (CLAUDE.md mentions decay under context pressure; MCP tools don't). Links to cli-bridge's "The problem" section for the full background instead of restating it. - Disambiguates the install.sh path (auto-generates spec, skip step 3) from the manual path. - Mentions cli-bridge's auto-refresh so users understand spec stays in sync after binary upgrades without re-registering. AGENTS.md (new): factual description of what gosymdb is, how the database is found, the freshness loop, the MCP integration via cli-bridge, known limitations, and related tools in the family (cli-bridge, cairn). Descriptive register — describes capabilities rather than directing agent behavior. Co-Authored-By: Claude Opus 4.7 (1M context) --- AGENTS.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 10 ++++++---- 2 files changed, 56 insertions(+), 4 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..f9d3b83 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,50 @@ +# AGENTS.md — gosymdb + +Documentation for AI agents (and anyone else) reading this repo. + +## What gosymdb is + +gosymdb is a Go-specific symbol and call-graph database backed by SQLite. It uses Go's own type-checker (`go/packages`, `go/types`) to build a persistent index of one or more Go modules, then answers structured queries: + +- `find` — search symbols by name, package, file, or kind +- `def` — exact single-symbol lookup +- `callers` / `callees` — direct or transitive call edges +- `blast-radius` — full transitive impact (with test/prod split) +- `dead` — symbols with no callers +- `implementors` — interface ↔ type satisfaction +- `references` — where a type appears (assertions, switches, literals, conversions) +- `packages`, `health`, `agent-context`, `version` — meta queries + +Every query supports `--json` for structured output. The full API is enumerated in one shot by `gosymdb agent-context`, which prints a JSON document with command signatures, flags, env block, and parsing notes. + +## How the database is found + +`gosymdb` walks parent directories looking for `gosymdb.sqlite`, the same way Go tools walk for `go.mod`. Pass `--db ` to override. If no database is found, commands return `error_code: no_database` with a hint to run `gosymdb index --root ` first. + +## The freshness loop + +The index goes stale the moment source files change. Every JSON response carries an `env.stale_packages` array listing packages whose source has drifted from what's indexed. The check uses a git fast-path (one `git diff` against the commit stamped at index time) with a per-file FNV-64a hash fallback when git isn't usable. + +Pass `--auto-reindex` to any query command to re-index stale modules in place before the query runs. The check itself is cheap enough to run on every call (sub-second on Kubernetes-scale codebases). + +## MCP integration + +gosymdb exposes `gosymdb cli-bridge-manifest` — a single subcommand that prints the canonical [cli-bridge](https://github.com/walkindude/cli-bridge) spec for this binary. When cli-bridge is installed and gosymdb's spec is registered, each command becomes an MCP tool named `gosymdb_` (e.g. `gosymdb_callers`, `gosymdb_blast_radius`). Setup steps are in the [main README's MCP section](./README.md#use-with-claude-code-mcp). + +Spec drift across gosymdb version bumps is handled automatically by cli-bridge's [auto-refresh on startup](https://github.com/walkindude/cli-bridge/blob/master/AGENTS.md#the-manifest-convention) once the convention is in place. + +## Known limitations + +gosymdb is a static symbolic index, not a runtime tracer: + +- Interface dispatch is not recorded as a direct call edge. The `callers` response includes a `hint` field flagging this when relevant. Use `implementors` to find concrete types, then `callers`/`callees` against the concrete method. +- Reflection (`reflect.Value.Call`, method-value lookups) is not statically resolved. +- `go:linkname`, plugin loading, and runtime dispatch are not modeled. +- Build tags affect what `go/packages` loads. Symbols behind tags not active for the host won't be indexed. + +## Related tools in this family + +- [walkindude/cli-bridge](https://github.com/walkindude/cli-bridge) — the MCP server that turns `gosymdb cli-bridge-manifest` into the registered MCP tools listed above. +- [walkindude/cairn](https://github.com/walkindude/cairn) — a separate tool for notes-to-future-me across stateless agent sessions. Also follows the cli-bridge manifest convention. + +These are listed as factual references — gosymdb works without them, and they're independent projects. diff --git a/README.md b/README.md index 3fe948d..4e27d33 100644 --- a/README.md +++ b/README.md @@ -90,15 +90,17 @@ gosymdb blast-radius --symbol 'github.com/you/repo/pkg.MyFunc' --depth 5 --json ## Use with Claude Code (MCP) -gosymdb exposes a self-describing manifest (`gosymdb cli-bridge-manifest`) that the [cli-bridge plugin](https://github.com/walkindude/cli-bridge) turns into first-class MCP tools. Once set up, your agent can call `gosymdb_callers`, `gosymdb_blast-radius`, `gosymdb_implementors` etc. directly — no grep fallbacks, structured output, typed answers. +gosymdb exposes a self-describing manifest (`gosymdb cli-bridge-manifest`) that the [cli-bridge plugin](https://github.com/walkindude/cli-bridge) turns into first-class MCP tools. Once set up, agents can call `gosymdb_callers`, `gosymdb_blast-radius`, `gosymdb_implementors` etc. as MCP tools — typed inputs, structured outputs, no `grep` fallback. + +This is the recommended path for agentic use. Agents lose track of CLI tools mentioned only in `CLAUDE.md` once the conversation gets long; MCP tools live in the agent's tool registry and don't decay under context pressure. (For background on why, see [cli-bridge's "The problem" section](https://github.com/walkindude/cli-bridge#the-problem).) **Three steps:** -1. `go install github.com/walkindude/gosymdb@latest` (or use the installer above). -2. Inside Claude Code: `/plugin marketplace add walkindude/cli-bridge && /plugin install cli-bridge@cli-bridge`. +1. `go install github.com/walkindude/gosymdb@latest` (or use the installer above; install.sh auto-generates the cli-bridge spec when Claude Code is detected, in which case skip step 3). +2. Install cli-bridge — either as a plugin (`/plugin marketplace add walkindude/cli-bridge && /plugin install cli-bridge@cli-bridge`) or standalone (`npm i -g cli-bridge && claude mcp add cli-bridge -s user -- cli-bridge`). 3. Inside Claude Code: `/cli-bridge:register gosymdb` (uses the canonical `cli-bridge-manifest` subcommand — no `--help` scraping). -Restart Claude Code and all `gosymdb_*` tools appear in the MCP tool list. +Restart Claude Code and all `gosymdb_*` tools appear in the MCP tool list. After upgrading the gosymdb binary, cli-bridge [auto-refreshes](https://github.com/walkindude/cli-bridge/blob/master/AGENTS.md#the-manifest-convention) the spec on its next startup — no manual re-register. ## Commands