yet another agent harness

Configure your coding agent once, use it everywhere.

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.

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 catches TODO: implement placeholders, and a session logger
• 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)

brew install dirien/tap/yaah

go install github.com/dirien/yet-another-agent-harness/cmd/yaah@latest

Grab a release from GitHub Releases. Binaries are signed with cosign and include SBOMs.

# 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

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.

/yaah:init → /yaah:discuss → /yaah:plan → /yaah:execute → /yaah:verify → /yaah:ship
                                                                    ↓
/yaah:next ← /yaah:progress ← /yaah:complete-milestone ← /yaah:docs

.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.

yaah isn't just a config generator — it also runs as a runtime alongside Claude Code.

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).

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

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.

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.

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.md extension.
• 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.

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

MIT