CLAUDE.md in stacklok/toolhive runs 731 words across 14 headings.
ToolHive is an enterprise-grade platform for running and managing Model Context Protocol (MCP) servers.
GoCovers
8 of the 20 section tags
In the order a file is read inHeadings
14 headings, in the order the file writes them
01CLAUDE.md
02Project Overview
03Build and Development Commands
04Available Subagents
05Core Development
06Specialized Domains
07Support
08When to Use Subagents
09Key Conventions
10Commit Guidelines
11Pull Request Guidelines
12Architecture Documentation
13Things That Will Bite You
14Evolving Conventions
Commands
16 commands this file writes down
Extracted from the file, verbatimtask build
task install
task lint
task lint-fix
task test
task test-e2e
task test-all
task test-coverage
task gen
task docs
task build-image
task build-all-images
task
go test
go build
go test ./...
The file
CLAUDE.md
107 lines1# CLAUDE.md
2
3This file provides guidance to Claude Code when working with this repository.
4
5## Project Overview
6
7ToolHive is a lightweight, secure manager for MCP (Model Context Protocol: https://modelcontextprotocol.io) servers written in Go. It provides a CLI (`thv`), a Kubernetes operator (`thv-operator`), and a proxy runner (`thv-proxyrunner`) for container-based MCP server isolation.
8
9**To understand the system, start with the [Architecture Documentation](docs/arch/README.md).** Begin at the [Architecture Overview](docs/arch/00-overview.md) and [Core Concepts](docs/arch/02-core-concepts.md), then read the component deep-dives relevant to your task — [Deployment Modes](docs/arch/01-deployment-modes.md), [Transport Architecture](docs/arch/03-transport-architecture.md), [Kubernetes Operator](docs/arch/09-operator-architecture.md), [Virtual MCP](docs/arch/10-virtual-mcp-architecture.md), and more. The [architecture index](docs/arch/README.md) has a full map and by-topic navigation.
10
11## Build and Development Commands
12
13```bash
14task build # Build the main binary
15task install # Install binary to GOPATH/bin
16task lint # Run linting
17task lint-fix # Fix linting issues (preferred over lint)
18task test # Unit tests (excluding e2e)
19task test-e2e # E2E tests (requires build first)
20task test-all # All tests (unit + e2e)
21task test-coverage # Tests with coverage analysis
22task gen # Generate mocks
23task docs # Generate CLI documentation
24task build-image # Build container image
25task build-all-images # Build all container images
26```
27
28**IMPORTANT**: Always use `task` commands. Never run `go test`, `go build`, or `golangci-lint` directly -- the Taskfile has correct flags, exclusions, and environment setup that direct commands miss.
29
30**Testing**: Ginkgo/Gomega for BDD-style tests. Unit tests for `pkg/` business logic; E2E tests for CLI commands.
31
32## Available Subagents
33
34Agents are in `.claude/agents/` and MUST be invoked for tasks matching their expertise:
35
36### Core Development
37- **toolhive-expert**: Architecture, codebase navigation, implementation guidance
38- **golang-code-writer**: Writing new Go code (functions, structs, interfaces, packages)
39- **unit-test-writer**: Writing comprehensive unit tests
40- **code-reviewer**: Code review for best practices, security, conventions
41- **tech-lead-orchestrator**: Architectural oversight, task delegation, complex features
42
43### Specialized Domains
44- **kubernetes-expert**: Operator patterns, CRDs, controllers, cloud-native architecture
45- **mcp-protocol-expert**: MCP spec compliance, transport protocols, JSON-RPC
46- **oauth-expert**: OAuth 2.0, OIDC, token exchange, authentication flows
47- **site-reliability-engineer**: Observability, OpenTelemetry, monitoring
48
49### Support
50- **documentation-writer**: Documentation updates, CLI docs
51- **security-advisor**: Security guidance, code review, threat modeling
52
53### When to Use Subagents
54- Writing new code: golang-code-writer
55- Creating tests: unit-test-writer
56- Orchestrating multi-component work: tech-lead-orchestrator
57- Reviewing code: code-reviewer
58- Domain expertise: kubernetes-expert, oauth-expert, mcp-protocol-expert, site-reliability-engineer
59
60## Key Conventions
61
62Detailed rules are in `.claude/rules/` (loaded automatically when matching files are read):
63- **Go style, errors, logging, SPDX headers**: `.claude/rules/go-style.md`
64- **CLI architecture**: `.claude/rules/cli-commands.md`
65- **Testing**: `.claude/rules/testing.md`
66- **Operator/CRDs**: `.claude/rules/operator.md`
67- **PR creation**: `.claude/rules/pr-creation.md`
68
69**Plan review**: Before presenting an implementation plan, review all applicable `.claude/rules/` files for the languages and components involved. Plans must conform to existing conventions.
70
71## Commit Guidelines
72
73- Imperative mood, capitalize subject, no trailing period
74- 50-char subject line limit
75- Explain what and why, not how
76- Do NOT use Conventional Commits (`feat:`, `fix:`, `chore:`, etc.)
77- See `CONTRIBUTING.md` for full guidelines
78
79## Pull Request Guidelines
80
81- Follow `.claude/rules/pr-creation.md` and `.github/pull_request_template.md`
82- Max **400 lines** of code changes, **10 files** changed (excluding tests/docs/generated)
83- Each PR = one logical change (one feature, one bug fix, or one refactoring)
84- If changes exceed limits, use `/split-pr` skill to propose a split strategy
85- Large PRs acceptable for: generated code, dependency updates, docs-only, test-only changes (with user confirmation)
86
87## Architecture Documentation
88
89When making changes that affect architecture, update relevant docs in `docs/arch/`. See the [architecture documentation index](docs/arch/README.md) for structure and the per-component documents.
90
91## Things That Will Bite You
92
93- Running `go test ./...` or `golangci-lint run` directly skips Taskfile configuration (exclusions, flags, formatting). Always use `task test`, `task lint-fix`, etc.
94- After modifying API handlers or CLI commands, run `task docs` to regenerate CLI documentation.
95
96## Evolving Conventions
97
98When a developer states a preference, convention, or correction during conversation (e.g., "we should use X instead of Y", "don't do Z", "always prefer A over B"), you MUST:
99
1001. **Apply it immediately** in the current conversation
1012. **Suggest codifying it** — identify which `.claude/rules/` file or `.claude/agents/` file it belongs in and propose the edit
1023. **Offer to apply** with a one-line confirmation (e.g., "Want me to add this to `.claude/rules/go-style.md`?")
103
104Use the `/add-rule` skill to formalize conventions. This ensures tribal knowledge gets captured in version-controlled config, not lost in chat history.
105
106**Personal vs team conventions**: Personal preferences (e.g., "I like verbose output") belong in `~/.claude/` personal memory. Team-wide conventions (e.g., "always use `errors.Is()` for error checks") belong in `.claude/rules/` so all team members benefit.
107
This listing
Whoever runs stacklok/toolhive can claim it
This is yours? Claim this config and we will write to you when the measurement moves. The check is one token placed where only you can place it, and there is no account and no password.