devtap CLAUDE.md

CLAUDE.md

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

Build & Test Commands

# Build
go build ./cmd/devtap

# Test (unit only)
go test ./...

# Test with race detection (as CI runs)
go test ./... -race -count=1

# Run a single test
go test ./internal/store/file/ -run TestDrain

# Integration tests (requires local GreptimeDB on gRPC :4001, MySQL :4002)
go test -tags=integration ./internal/store/greptimedb/

# Lint
golangci-lint run ./...

Architecture

devtap captures stdout/stderr from build/dev commands and delivers them to AI coding tools via MCP (Model Context Protocol).

Data Flow

devtap -- <cmd>  →  capture (runner/longrun)  →  store.Write()  →  fan-out to all adapters
AI tool          ←  MCP server (get_build_errors) ←  store.Drain()  ←  per-adapter queue

Core Interfaces

Store (internal/store/store.go): Write/Drain/Status/Close. Two backends:

• File (default): JSONL at ~/.devtap/<session>/<adapter>/pending.jsonl, atomic rename for IPC
• GreptimeDB (optional): SQL queries + watermark cursor, tag is a reserved keyword and must be backtick-quoted in all SQL

Adapter (internal/adapter/adapter.go): Name/DiscoverSessions/Install. Five implementations:

• claudecode: .mcp.json + optional Stop hook in ~/.claude/settings.json
• codex: .codex/config.toml
• opencode: opencode.json
• gemini: .gemini/settings.json
• aider: lint wrapper script (no MCP)

Key Patterns

• Multi-adapter fan-out: Writers discover adapters via store.DiscoverAdapters(), write to all. Each tool drains independently.
• Multi-source drain: MCP server and drain command can read from up to 2 sources (local + configured remote). resolveDrainSources() in cmd/devtap/storefactory.go resolves sources and deduplicates when (backend, session) match. Messages are merged, deduplicated via mcp.DedupMessages(), and labeled with [host session] prefix in multi-source mode.
• Drain budget unit: Store.Drain(sessionID, maxLines) treats maxLines as a message count (not line count). The multi-source loop tracks remaining budget in messages. Line-level truncation is a separate pass via mcp.TruncateMessages().
• Host field: LogMessage.Host is set via cached os.Hostname() at capture startup. Used for multi-source origin labeling. GreptimeDB uses COALESCE(host, '') for backward compat with pre-existing rows.
• File store IPC: pending.jsonl → atomic rename to pending.jsonl.draining → read → delete. Leftover lines written back to prevent data loss.
• Config merge: .mcp.json / settings.json / opencode.json reads existing → upserts devtap entry → writes back. Never overwrites other tools' config.
• Instruction injection: Appends `