Setu (setu-opencode)

Pre-emptive guardrails for AI coding agents in OpenCode. From fast-but-fragile to reliable, boringly-correct, senior-level engineering. Other tools fix mistakes after they happen. Setu prevents them before they start. Independent open-source plugin for OpenCode AI coding agents.

Setu bridges the gap between "AI that codes fast" and "AI that codes correctly."

Setu is not prompt engineering.

• At the model layer: Setu improves reasoning quality through structured research/plan contracts.
• At the runtime layer: Setu enforces safety and workflow at OpenCode tool hooks before actions execute.

Setu (Translation: "bridge") focuses on Developer Experience by creating guardrails, so agents understand before they modify, confirm before risky actions, and prove completion with verification evidence.

Why I Built This

I was building a product. Three times, my AI agent — one of the best available — cost me hours of work. Not maliciously. It just forgot.

Incident 1: The 12-Hour Deletion

It forgot I told it not to touch certain files. It forgot the architecture we discussed. It forgot why we made specific decisions 3-4 prompts ago. Gone. Twelve hours of careful work - hard overwrite, all gone. Wasted additional 3+ hours to recover everything.

Incident 2: The Git Reset From Hell

I had uncommitted changes — experimental work I wasn't ready to commit yet. The agent decided to "clean up" and ran git reset --hard. My entire afternoon of exploration: vanished. No warning, no "are you sure?" Just gone.

Incident 3: The Build That Wasn't

I asked it to check if my dev server was running before building. It nodded along, said "absolutely," then immediately ran bun run build anyway — overwriting my bundles, killing my server, and breaking my local environment. It said it understood. It didn't.

The Daily Grind

Every new session: "Let me explain the codebase again..."
Every compaction: "No, we already tried that approach..."
Every build command: "Please check if the dev server is running first..."

I was spending more time re-explaining than coding. Burning tokens on ghost loops — the same broken approach, 15 retries, zero progress.

So I built the DX + guardrails I needed.

Four Pillars

Setu is built on four foundations that work together:

Guardrails — Blocks unsafe or out-of-order tool calls at the hook level (not "please be careful")

Gear Workflow — Scout → Architect → Builder progression enforced by native gears and artifacts, not vibes

Hydration & Continuity — Persistent artifacts + compaction survival means no re-explaining the codebase every session

Evidence — Verification logs prove "done" means "works," not "I'm confident"

Why Other "Solutions" Don't Work

Prompt engineering? "Please think step by step" — ignored when the model is in flow state.

AGENTS.md? Great until the agent "forgets" your rules mid-session.

Better models? They will still hallucinate, still forget context, still rush to implementation.

The truth: You can't solve this with better prompts. You need structure + enforcement.

Installation (30 Seconds)

setu-opencode is published on npm, so npm/pnpm/bun can install the same package.

Option A: Global install (recommended)

npm install -g setu-opencode && setu init
# or
pnpm add -g setu-opencode && setu init
# or
bun add -g setu-opencode && setu init

setu init ensures consistent setup across npm, pnpm, and bun — even when install scripts are skipped. It also normalizes plugin wiring and cleans legacy files that can shadow global agent updates.

Global setup updates:

• ~/.config/opencode/opencode.json (adds/normalizes Setu plugin to exact [email protected])
• Setu agent profile under OpenCode global config

Fallback: If setu is unavailable or postinstall bootstrap is skipped after install:

npx setu-opencode init

Manual Bootstrap (Fallback)

Add Setu manually to ~/.config/opencode/opencode.json:

{
  "plugin": ["setu-opencode"]
}

Then run setu init once to normalize this to the canonical exact plugin spec.

Restart OpenCode. Setu should appear as default agent/mode in your OpenCode.

If this is not the case, Setu is not configured correctly. Please open an issue, with details.

Uninstall (Clean Removal)

setu uninstall && npm uninstall -g setu-opencode
# or
setu uninstall && pnpm remove -g setu-opencode
# or
setu uninstall && bun remove -g setu-opencode

setu uninstall removes Setu wiring from global OpenCode config and cleans legacy managed Setu agent files from ~/.opencode when present.

Restart OpenCode. Setu should no longer appear as default agent/mode.

How It Works (No Willpower Required)

Setu hydrates each session — gathering context and understanding your codebase before any gears engage. Your agent then progresses through three phases with artifact-driven, hook-enforced transitions.

Scout: Understand First, Build Never

Agent can read. Can explore. Can analyze. Cannot write a single line of code.

• Reads your codebase thoroughly
• Analyzes patterns and architecture
• Documents findings in .setu/RESEARCH.md

Result: Solid foundation before any code is written.

Architect: Design the Approach

Agent creates PLAN.md with implementation steps. Still cannot touch your source code.

• Creates detailed implementation steps
• Designs the approach
• Documents in .setu/PLAN.md

You review and approve before execution; runtime safety gates still enforce risky actions independently.

Builder: Execute With Confidence

Now (and only now) does it implement. Verification runs at the end, and you can run setu_verify after major steps.

• Implements the approved approach
• Runs verification before completion
• Ships only when everything passes

Build fails? Won't claim "done." Tests fail? Won't claim "done."

The gears shift automatically. Your agent can't accidentally skip ahead. The workflow ensures every phase gets the attention it deserves.

Contract-Driven Quality

Setu doesn't just block bad actions—it guides the model to produce better artifacts.

Before Generation: Setu injects detailed contracts into the system prompt, telling the model exactly what comprehensive research and atomic planning look like.

Research Contract: Intent/PRD, technical analysis, alternatives/tradeoffs, risks, verification, open decisions

Plan Contract: Atomic steps with why, files touched, change intent, verification method, edge cases

After Generation: Setu writes the model's output verbatim—no reformatting, no structure coercion, zero knowledge loss. The model produces comprehensive content with its own structure; Setu preserves it exactly.

This is soft guidance, not hard enforcement: the model knows what quality looks like, then creates accordingly.

The distinction: Hooks enforce workflow phases (hard) while contracts guide output quality (soft). Hooks block invalid actions and control phase transitions; contracts prescribe what good research and plans look like, but do not enforce control flow.

What Makes This Different

The "Eager Junior Dev" Problem

Without Setu:

You: Add auth
Agent: *immediately starts coding*
Agent: Done!
You: This is completely wrong
Agent: Sorry, let me fix it
Agent: *tries the same broken approach*

With Setu:

You: Add auth
Agent: I'm in Scout phase. Let me understand your auth patterns first...
[Reads your existing auth code]
[Analyzes your middleware structure]
[Documents findings in RESEARCH.md]

Agent: Moving to Architect phase. Here's my plan:
[PLAN.md with step-by-step approach]
[Specifically addresses your existing patterns]

You: Looks good, proceed
Agent: Executing plan with verification...
[Build passes]
[Tests pass]
Done.

The "Context Goldfish" Problem

Without Setu:
Every session starts with "Let me explore the codebase..." (even though you did this yesterday)

With Setu:
RESEARCH.md and PLAN.md persist across restarts. Your agent picks up exactly where you left off. No re-explaining. No déjà vu.

Safety Mechanisms

Three independent layers protect your codebase:

| Layer | Purpose | How It Helps | |-------|---------|--------------| | Hydration Gate | Prevents action before understanding | Agent explores safely first; write paths unlock only after understanding is established | | Confirmation Flow | Double-checks risky operations | Production-impacting commands require explicit approval; destructive commands are hard-blocked | | Read-Before-Write | Prevents accidental overwrites | Agent must read existing files before editing them |

These aren't roadblocks—they're guardrails that keep your agent on the right path.

Tools Included

| Tool | What It Does | |------|--------------| | setu_context | Explicit alignment checkpoint (fallback when clarification/tooling needs it) | | setu_research | Document findings (Scout phase) | | setu_plan | Create implementation plan (Architect phase) | | setu_verify | Run build/test/lint (Builder phase) | | setu_doctor | Check environment before executing | | setu_task | Manage task lifecycle (create, reframe, update_status, clear, get) | | setu_reset | Reset progress to restart current plan |

Important: In auto mode, setu_research and setu_plan append to existing artifacts. A new objective starts with setu_task(action="create"), which archives prior artifacts to HISTORY.md, replaces the previous task boundary, and resets the workflow to Scout. Refinements to the same objective go through setu_task(action="reframe"), which keeps existing artifacts intact. setu_task(action="update_status") tracks progress only and should not be followed by an automatic clear.

Skills Included

| Skill | Purpose | |-------|---------| | setu-bootstrap | Project setup following the discipline protocol | | setu-verification | Verification and release checks | | setu-rules-creation | Create effective AGENTS.md files |

Skills load on-demand, not at startup.

What's Next

See ROADMAP.md for upcoming features and development plans.

When NOT to Use Setu

• Rapid prototyping where you want maximum speed — use Build mode (Tab)
• Learning/exploration — use Plan mode (Tab)
• Already have a workflow that works — Setu enhances, doesn't replace

Setu is optional discipline, not mandatory bureaucracy.

Works Well With

Setu complements other agent productivity tools:

| Related Tool | Best At | How Setu Complements | |---|---|---| | GSD | Spec-driven meta-prompting and planning workflows | GSD structures thinking; Setu enforces safety at the tool boundary | | oh-my-opencode | Full orchestration harnesses and workflow automation | Setu stays narrow and auditable as the guardrail/evidence layer | | Beads | Persistent memory graph for long-horizon agent work | Beads remembers state; Setu prevents unsafe execution | | btca.dev / better-context | Codebase grounding and context retrieval | Better context improves retrieval; Setu enforces safe actions and verification |

Setu's role: Guardrails + continuity + verification inside OpenCode.

Technical Details

• Skills load on-demand rather than front-loading context
• Hook-level enforcement at tool.execute.before
• Compaction survival via experimental.session.compacting
• Version tracked by the npm badge at the top of this README

See: ROADMAP.md for upcoming features
See: docs/DIAGRAMS.md for architecture diagrams

License

Apache 2.0 — See LICENSE

Setu: Because "move fast and break things" is fun until you're debugging at 2 AM.