testagent: Instructions file for Claude Code

AGENTS.md

Context for AI agents working on this repo. (Cursor, Claude Code, and others read this file.)

What is testagent?

A fake CLI agent for testing orchestration tooling that drives real coding agents (Claude Code, Codex, Gemini, GitHub Copilot CLI, etc.). Runs as an interactive PTY process; emits the same kinds of terminal artifacts (boxed tool-use blocks, streaming text, in-place updates) and the same protocol traffic (HTTP hooks, MCP JSON-RPC) as a real agent — without calling any LLM.

The product framing is deterministic output for tests, not "no LLM" as a virtue. Wiring a local LLM into a test harness is a valid choice for some workflows; testagent is explicitly not that. Every assertion-relevant byte (slash dispatch, hook payloads, MCP frames, stream-json shapes) is scripted by the user, not generated, so tests stay stable across runs.

v1 ships a drop-in fake for Claude Code: argv compatibility for the flags orchestrators commonly emit, HTTP and command hooks (UserPromptSubmit / PreToolUse / PostToolUse / Stop / SessionStart / SessionEnd / PreCompact / PostCompact), an MCP HTTP client that handshakes and dispatches tools/call, --print --output-format stream-json for non-interactive callers, a slash-command grammar for driving UI primitives interactively (including /clear and /compact which fire the corresponding hook lifecycles without restarting the process), and lipgloss-rendered plausible-shape output.

Future phases

Design conventions

• Schema types are duplicated, not imported. Settings and MCPConfig mirror Claude Code's on-disk shapes and live in cmd/claude/settings.go (vendor-specific, not shared with the engine).
• Stdlib-first; deps are deliberate. Each non-stdlib dep is justified in the commit message that adds it (mark3labs/mcp-go, lipgloss, bubbletea, bubbles, go-isatty, spf13/cobra).
• Interactive vs non-interactive split. TTY stdin → bubbletea TUI (internal/engine/tui.go, inline rendering with native terminal scrollback, concurrent input during the thinking spinner). Piped stdin → scanner loop (internal/engine/scanner.go, line-based, inline rendering). --print/-p is a third path (cmd/claude/print.go, one-shot output formatter). The mattn/go-isatty check on os.Stdin is the TUI/scanner gate; e2e tests pipe stdin so they always hit the scanner path.
• Conventional Commits. One commit per phase. Each phase's commit leaves the tree buildable and tested.
• Tests: t.Parallel(), table-driven, real httptest/exec-driven integration over mocks where possible (see e2e_test.go). Fixtures in testdata/. Time-dependent helpers (anything that calls time.Sleep / time.NewTimer / tea.Tick outside real network IO) use testing/synctest so virtual time advances without real wall-clock waits — see internal/engine/{spinner,stream}_test.go for the pattern.
• Debug output goes to stderr. Verbose / debug logging (e.g. --verbose hook traces) is plain text, one event per line, never ANSI-styled — it gets grepped and piped. Stdout stays reserved for stream-json frames and TUI rendering.
• COMPATIBILITY.md is the contract artifact. It is the per-vendor source of record for which flags, slash commands, and REPL behaviors testagent implements, accepts, or omits. Update it when adding vendor-facing features. Use the update-compatibility skill (one skill, dispatches by vendor — claude, codex, or cursor) to refresh a section after an upstream release or when drift is detected. Per-vendor source URLs, probing recipes, and matrix templates live under the skill's vendors/<name>/ subdirectories. Cursor adapter is in early-stage planning — the template is ready; vendor wiring lands in a future phase.
• RELEASING.md is the release-policy doc (semver scope, bump table, runbooks). When cutting a release, drive it through the publish-release skill, which executes RELEASING.md step by step and gates on the two human decisions (version number, release-notes copy).