yaah
yet another agent harness
Configure your coding agent once, use it everywhere.
The problem
Coding agent configuration is a mess. Settings live in JSON files, skills are markdown scattered across directories, hooks are shell scripts wired by hand, MCP servers need manual JSON entries. Multiply that by the number of repos and agents you use. Good luck keeping any of it consistent.
What yaah does
yaah generates configuration for four coding agents from a single Go codebase: Claude Code, OpenCode, Codex CLI, and GitHub Copilot CLI. One command per agent, every repo, same result.
yaah generate # all agents
yaah generate --agent claude # Claude Code only
yaah generate --agent opencode # OpenCode only
yaah generate --agent codex # Codex CLI only
yaah generate --agent copilot # GitHub Copilot CLI only
That single command gives you:
- 5 hooks out of the box: linting (golangci-lint, ruff, prettier, tsc), a command guard that blocks
rm -rf /and friends, a secret scanner for leaked keys, a comment checker that catchesTODO: implementplaceholders, and a session logger — plus an experimental tool-using fact-checker onStop/SubagentStop(opt in viaYAAH_EXPERIMENTAL_FACT_CHECK=1) - Middleware chains for composing handlers (e.g. secret scan + auto-remediation advice)
- MCP servers for Context7 and Pulumi, plus a built-in yaah MCP server exposing tools like secret scanning, linting, and command checking directly to the agent
- Multi-agent config generation with per-agent adaptations (MCP format, hook delivery, agent tools, skill frontmatter)
- LSP support for Go, Python, TypeScript, and C# via the official marketplace
- Session tracking that logs every tool call, blocked command, and file modification across sessions
- 3 built-in skills (commit, PR, review) plus 74 remote and workflow skills covering Pulumi IaC, Flux CD GitOps, Go, Python, TypeScript, Kubernetes, DevOps, SRE, security auditing, code quality, tech debt analysis, and more
- 16 agents: 3 built-in (executor, librarian, reviewer) plus 4 workflow agents (researcher, planner, doc-writer, verifier) and 9 remote agents from agency-agents covering AI engineering, backend architecture, security, code review, DevOps, SRE, and testing
- Plugin support with marketplace auto-enablement — ships with OpenAI Codex for code review and task delegation
Don't want all of it? Turn off what you don't need:
opts := harness.DefaultOptions{
EnableCommandGuard: true,
EnableSecretScanner: true,
EnableGopls: true,
EnableCommitSkill: true,
EnableYaahMCP: true,
}
h := harness.NewWithDefaults(opts)
Install
Homebrew
brew install dirien/tap/yaah
Go
go install github.com/dirien/yet-another-agent-harness/cmd/yaah@latest
Binary
Grab a release from GitHub Releases. Binaries are signed with cosign and include SBOMs.
Quick start
# Generate .claude/ with all defaults
cd your-repo
yaah generate
# Check that everything is installed
yaah doctor
yaah doctor tells you what's missing and how to install it:
LSP Servers:
✓ gopls /usr/local/bin/gopls
✓ pyright /usr/local/bin/pyright-langserver
✗ csharp not found → dotnet tool install -g csharp-ls
Workflow
yaah includes a structured project workflow with 29 slash commands. All commands are namespaced as /yaah:* and are registered as explicit user commands — the model never auto-triggers them.
Lifecycle
/yaah:init → /yaah:discuss → /yaah:plan → /yaah:execute → /yaah:verify → /yaah:ship
↓
/yaah:next ← /yaah:progress ← /yaah:complete-milestone ← /yaah:docs
Command reference
.planning/ directory structure
.planning/
├── PROJECT.md # Vision, goals, tech stack, constraints
├── REQUIREMENTS.md # Scoped requirements with REQ-IDs
├── ROADMAP.md # Phases with scope, success criteria, status
├── STATE.md # Current position and progress tracking
├── HANDOFF.md # Session pause/resume state
├── TODOS.md # Quick todo items
├── config.json # Workflow settings
├── research/ # Project-level research
├── phases/ # Per-phase artifacts
│ └── 01-auth/
│ ├── CONTEXT.md # Implementation decisions
│ ├── RESEARCH.md # Phase-specific research
│ ├── 01-01-PLAN.md # Task plan with wave grouping
│ ├── 01-01-SUMMARY.md # Execution outcomes
│ ├── VERIFICATION.md # Validation results
│ ├── REVIEW.md # Code review findings
│ ├── SECURITY.md # Threat model (STRIDE)
│ └── CHANGELOG.md # Milestone changelog
├── quick/ # Ad-hoc task records
└── notes/ # Idea captures
Four specialized agents back the workflow: researcher (sonnet, read-only), planner (opus, goal-backward decomposition), doc-writer (sonnet, codebase-verified docs), and verifier (sonnet, artifact validation). Two MCP tools are also exposed: yaah_planning_status and yaah_planning_init.
See Components documentation for full details.
Runtime features
yaah isn't just a config generator — it also runs as a runtime alongside Claude Code.
MCP server
yaah serve starts an MCP server over stdio, exposing yaah's capabilities as tools that Claude Code can call directly:
The MCP server is auto-discovered by Claude Code via .mcp.json at the project root (generated by yaah generate).
Session tracking
Every hook event is recorded to .claude/sessions/<session-id>.json. This gives you a full audit trail of what Claude Code did in each session: tool calls, blocked commands, files modified, and security findings.
yaah session list # List recent sessions
yaah session show <id> # Full details for a session
yaah session clean # Remove sessions older than 7 days
Middleware chains
Compose handlers into sequential pipelines with conditional logic:
chain := hooks.NewChain("secret-remediation",
[]schema.HookEvent{schema.HookPostToolUse},
regexp.MustCompile(`(?i)^(Edit|Write)$`),
hooks.HandlerLink(handlers.NewSecretScanner()),
hooks.OnBlock(func(ctx context.Context, input *hooks.Input, prev *hooks.Result) (*hooks.Result, error) {
prev.Output += "\n\nRemediation: Move the secret to an env var or secrets manager."
return prev, nil
}),
)
h.Hooks().Register(chain)
Available combinators: HandlerLink, OnBlock, OnError, Transform.
How it works
yaah has a simple mental model: interfaces and registries. Each component type (hooks, MCP, LSP, skills, agents, commands) has an interface you implement and a registry you add it to. The Harness wires them all together and the per-agent generators produce the right files.
Multi-agent output
Each agent gets files in its native format:
Key adaptations per agent:
- OpenCode: MCP uses
"mcp"key with"local"/"remote"types and"command"as array. Agent tools rendered as a disable-map. Hooks delivered via JS plugin (execFileSync). - Copilot: MCP uses
"stdio"/"http"transport types. Env vars passed through. Agent files use.agent.mdextension. - Codex: MCP embedded in TOML. Hooks limited to
SessionStart/Stop— linting and security checks available via yaah MCP tools. - Claude: Native format, all features supported.
Write your own hook? Implement hooks.Handler. Custom MCP server? Implement mcp.Provider. Same pattern everywhere.
Documentation
The detailed reference lives in docs/:
- Components -- hooks, MCP, LSP, skills, agents, commands, plugins, MCP server, session store, middleware chains
- Configuration -- settings, CLI commands, project structure