llmwiki: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

go build ./...                        # build everything
go build -o llmwiki .                 # build the binary
go test ./...                         # run all tests
go test ./internal/ingestion/... -v   # run a specific package
go test ./... -run TestFoo -v         # run a single test by name
go vet ./...                          # static analysis

llmwiki setup                         # interactive global config wizard (~/.llmwiki/config.yaml)
llmwiki init                          # interactive per-project wizard (no flags + TTY)

Architecture

The binary is a single cobra CLI. main.go wires the subcommands from internal/cmd/. The core data flow is:

ingest: scanner (+ extractor) → ingestion → llm → wiki

1. internal/scanner — walks a project directory and collects relevant files (README, go.mod, docker-compose, .proto, etc.) into a single text summary. DetectServices auto-detects multi-service layouts from docker-compose.yml first, then subdirectory heuristics. ScanProject(ctx, dir, opts...) takes a WithExtractor option; when set, binary document files (.pdf/.docx/.odt/.epub) are converted to text and folded into the summary (capped at 50 files / ~50 KB each).
   • internal/extractor — shells out to configurable external converters (pandoc, pdftotext) to turn document files into text. CommandExtractor maps an extension to a command template ({{input}} placeholder, run without a shell), mirroring the subprocess pattern in llm/cli_backend.go. A missing tool yields ErrToolNotFound and the scanner skips the file rather than failing.
2. internal/ingestion — orchestrates the pipeline: scan → prompt → LLM call → write. IngestProject branches on whether services were detected: zero services = single project file, one+ services = one file per service.
3. internal/llm — three backends behind the LLM interface (Generate(ctx, prompt) (string, error)): claude-code (shells to claude -p), claude-api (Anthropic SDK), ollama (REST). NewFakeLLM is the test double used throughout.
4. internal/wiki — reads/writes markdown files with YAML front matter. WriteProjectEntry/WriteServiceEntry own the file format. UpsertIndex maintains the master _index.md. query.go adds a read-only, LLM-free query layer: Store (rooted at the wiki dir) with Search(client, project) (filters _index.md; client = exact case-insensitive, project = substring), GetProject(client, project, service), and ListServices. It composes the existing ReadIndex/Parse*Entry/ExtractSection helpers and backs the MCP server.
   • knowledge.go — the knowledge-layer axis (see Wiki Storage Layout). SearchKnowledge(layers, query) (empty query = list), GetKnowledge(layer, topic), ListKnowledgeLayers(). Filesystem-walked rather than index-driven, so front matter is optional and a layer can be a git submodule. Layer names are validated with validation.NameComponent because they're joined into paths; safeio.ReadRegularFile refuses symlinks; .git dirs are skipped.
5. internal/config — three-level config: global (~/.llmwiki/config.yaml), per-client (~/.llmwiki/clients/<customer>.yaml), and per-project (llmwiki.yaml). Merge resolves them project > client > global. Slice-valued fields (Extraction.Sections, Knowledge) replace rather than append.
6. internal/tracker — change tracking via git history. cochange.go clusters files that change together (union-find, 30% co-occurrence threshold) into Areas; area.go computes a content-addressed hash from git ls-tree HEAD output; freshness.go compares a stored hash against the current one. GitRunner is the injectable git-subprocess interface (real impl shells to git, fakeGitRunner in tests). At ingest time ingestion.buildTracking writes the resulting wiki.TrackingMeta into entry front matter; cmd/check.go re-checks it.