CLAUDE.md

1# 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