Guren Harness

Guren Harness

Guren ships its agent harness inside the app's own @guren/cli, installed by guren agent:init and refreshed by guren agent:sync. This skill gets that installed and tells you how to use it. The installed harness — the rules directory, the entry document, the hooks — is authoritative once present; this skill is the on-ramp to it, not a replacement.

Detect a Guren app

Positive evidence only: a package.json here (or in a parent) whose dependencies or devDependencies include @guren/core. If there is none, stop and use the guren-new-app skill. If the dependencies are declared but node_modules/@guren/cli is missing, run bun install first — nothing below works without it.

Probe the CLI version before installing

Run:

bunx guren --version

Multi-agent targets need @guren/cli 2.5.0 or newer. Older CLIs silently ignore an unrecognized --target flag: agent:init --target codex,cursor on such a CLI installs a Claude-only harness, prints "AI agent harness is ready", and exits 0. A fallback keyed on a non-zero exit would report multi-agent success that never happened, so decide from the version first:

• Version parses and is ≥ 2.5.0 → proceed with --target.
• Version is older, or --version itself fails or prints no version (a CLI older still) → treat as older than 2.5.0: run plain bunx guren agent:init (Claude-only), and tell the user that multi-agent targets need @guren/cli ≥ 2.5.0 (bunx guren upgrade).

Install

bunx guren agent:init --target <list>

<list> is comma-separated from: claude, codex, cursor, copilot, opencode, or all. Ask which agents the team uses; the default is claude only. The command writes the entry document (CLAUDE.md for Claude Code, AGENTS.md for the others), glob-scoped rule files, skills, subagents and hooks for Claude, and an MCP client config per target. It never overwrites an existing entry document or MCP config without --force; if an MCP config already exists without the Guren endpoint, it prints the snippet to merge by hand.

Refresh

bunx guren agent:sync

Overwrites framework-managed files (rules, skills, subagents, hooks) with the installed CLI's version and leaves user-owned files alone. It reports files under the managed locations that the current harness no longer writes; --prune deletes those. Rules files of your own in .claude/rules/ / .agents/rules/, and skills you or another installer (including this plugin) added to .claude/skills/ or .agents/skills/, are never touched unless they sit under a name the harness itself ships — the claim is by name, so avoid the canonical skill names (dev-workflow, db-manage, scaffold, feature, guren-api, plugin-authoring, agent-interface) and the shipped rule filenames for your own.

The loop the harness expects

Until agent:init has run, this is the only harness you have, so follow it yourself:

1. Session start: bunx guren context. Its output ends with an API signature digest for the ORM, controller, and testing APIs — read it before writing code. bunx guren context <Entity> bundles everything about one model. With the MCP server connected, guren_get_context is the same map.
2. After editing routes, controllers, models, db/schema.ts, or pages: bunx guren check, and bunx guren check --changed to scope it to your diff. Fix what it reports before moving on.
3. When the change is complete: bunx guren gate, and fix what it reports until it exits 0. It runs the stages CI runs — codegen, typecheck, lint, check, audit (validation and auth gaps on mutating routes, raw SQL, secrets), and the test suite — and a change is not done while any of them fails.

Once installed, the entry document describes the same loop for the app; the Claude harness automates all three steps with hooks (the gate runs when a turn ends with uncommitted changes), Cursor and Codex get the same stop hook, and the others are told in AGENTS.md to run the gate themselves. Read the installed rules in .claude/rules/ or .agents/rules/ — each file's globs frontmatter says which paths it covers — before editing those paths.