Gw

Three things it does that reading source directly cannot:

1. Persistent graph — relationships stored in .gw/state.json survive across sessions. Query architecture weeks later without re-reading source.
2. 70x token reduction — skeletons (signatures + rationale comments only, no bodies) replace full source files for LLM context.
3. Incremental sync — only changed files are re-analyzed. A 50-file repo syncs in seconds after the first run.

The MCP server (gw serve) exposes four tools that agents call natively:

• query_graph — BFS/DFS reachability from files matching a query string
• shortest_path — minimum-hop dependency chain between two files
• god_nodes — PageRank-ranked architectural hubs
• get_community — Tarjan SCC cluster or direct neighbours for a file

No API key is needed for any of these tools. gw serve reads only .gw/state.json. The LLM API key (GW_API_KEY) is only needed for gw sync (the initial wiki-building step).

What You Must Do When Invoked

If no path was given, use . (current directory). Do not ask for a path.

Follow these steps in order. Do not skip steps.

Step 1 — Ensure gw is installed

which gw 2>/dev/null && gw version 2>/dev/null || echo "NOT_INSTALLED"

If NOT_INSTALLED:

# Try go install first
go install github.com/sourcewiki/gw@latest 2>&1 | tail -5
which gw 2>/dev/null || echo "INSTALL_FAILED"

If install fails, stop and tell the user:

gw is not installed. Install it with:
  go install github.com/sourcewiki/gw@latest

Or build from source:
  git clone https://github.com/sourcewiki/gw
  cd gw && make install

Requires Go 1.21+.

If installed, print nothing and move to Step 2.

Step 2 — Check wiki state

ls .gw/state.json 2>/dev/null && echo "WIKI_EXISTS" || echo "WIKI_MISSING"

Then check the entry count:

gw doctor 2>&1 | head -10

Print a clean summary:

Wiki: N files tracked, last synced <date>
State: .gw/state.json

If WIKI_MISSING, proceed to Step 3 (sync). Otherwise skip to Step 4.

Step 3 — Build the wiki (only if wiki missing or --sync given)

This step requires an LLM API key (GW_API_KEY). Check first:

echo "${GW_API_KEY:+KEY_SET}${GW_API_KEY:-KEY_MISSING}"

If KEY_MISSING, check if it was passed as an argument. If neither, stop and tell the user:

gw sync requires an LLM API key to analyze Go source files.

Set it once:
  export GW_API_KEY=sk-ant-...     # Anthropic (default)
  export GW_API_KEY=sk-...         # OpenAI (set --llm openai too)

Or run a dry-run (no LLM, stub output):
  gw sync --dry-run

Once the wiki is built, all MCP queries work without any API key.

If KEY_SET, run sync:

gw sync --path . 2>&1 | tail -20

For --force / full rebuild:

gw sync --path . 2>&1 | tail -20

Sync prints progress. Wait for it to complete. On success, print:

Wiki built: N files analyzed → wiki/pages/

On error, show the last 20 lines of output and stop.

Step 4 — Configure MCP server (no API key needed)

Check if .mcp.json already has the gopherwiki server:

cat .mcp.json 2>/dev/null | grep -q gopherwiki && echo "MCP_CONFIGURED" || echo "MCP_MISSING"

If MCP_MISSING, write the config using gw install --platform claude-code, which writes .mcp.json automatically (no API key needed):

gw install --platform claude-code 2>&1

If gw install is not yet available or you need to write it manually:

cat > .mcp.json << 'EOF'
{
  "mcpServers": {
    "gopherwiki": {
      "command": "gw",
      "args": ["serve"],
      "type": "stdio"
    }
  }
}
EOF

Then tell the user:

MCP server configured in .mcp.json.
Restart your editor/agent to load the gopherwiki MCP tools.

Available tools (no API key needed):
  query_graph     — BFS/DFS search by file path substring
  shortest_path   — minimum-hop dependency chain
  god_nodes       — top architectural hubs by PageRank
  get_community   — dependency cluster for a file

If MCP_CONFIGURED, skip the write and go directly to Step 5.

Step 5 — Answer the query

Only reach this step if the user passed a query flag. If they just ran /gw or /gw --mcp, stop after Step 4.

--query <question>

Use the query_graph MCP tool with the question as the query parameter.

If the MCP tool is available (server connected), call it directly:

Tool: query_graph
  query: <question>
  mode: BFS        (use DFS if --dfs was given)
  max_depth: 0     (unlimited unless --depth N given)

If MCP is not yet connected (first run, editor not restarted), fall back to reading the wiki directly:

cat wiki/index.md 2>/dev/null | head -100

Then read the relevant page(s) from wiki/pages/.

Present results as:

Reachable from "<question>" (BFS, N files):
  1. cmd/sync.go
     Orchestrates the one-shot reconciliation pipeline.
  2. internal/reconciler/reconciler.go
     ...

--path <source> <target>

Use the shortest_path MCP tool:

Tool: shortest_path
  source: <source>
  target: <target>

Present results as:

Shortest dependency path (N hops):
  1. cmd/sync.go
       └─[imports]─>
  2. internal/reconciler/reconciler.go
       └─[imports]─>
  3. internal/state/state.go

--hubs [N]

Use the god_nodes MCP tool:

Tool: god_nodes
  top_n: 10   (or N if given)

Present results as:

Top N architectural hubs (PageRank):
  1. internal/state/state.go  (score: 0.2341)
     Persistent brain of the reconciler — loaded by every command.
  2. ...

--explain <file>

Use the get_community MCP tool:

Tool: get_community
  module: <file>

Present results as either:

<file> is part of a cyclic cluster (N files):
  internal/state/state.go
  internal/reconciler/reconciler.go
  ...