Run Your First Coding Agent in 3 Minutes

Module 01

The Mental Model (Demystifying the Agent)

An AI coding agent is not magic. It is a deterministic loop running locally in your terminal, using an LLM as a reasoning engine to inspect errors and patch code.

┌────────────────────────────────────────────────────────────────────────┐
│                        YOUR LOCAL MACHINE                              │
│                                                                        │
│   [Your Terminal]                               [Your Files & Git]     │
│   runs `opencode`  ──────reads, edits, diffs─────>  `src/`, `tests/`   │
│          │                                                             │
│          ├──executes shell──> `pytest` / `npm test`                    │
│          │                                                             │
│          └──sends prompts──┐                                           │
└────────────────────────────┼───────────────────────────────────────────┘
                             │ HTTPS (Encrypted API calls)
                             ▼
┌────────────────────────────────────────────────────────────────────────┐
│                    OPENROUTER INFERENCE ROUTER                         │
│                                                                        │
│   Dispatches to: GPT-5.6 Sol [medium] (SWE-rebench Pick)           │
│   Returns: Structured file diffs and tool execution calls              │
└────────────────────────────────────────────────────────────────────────┘

OpenCode stays in your project directory. It asks for confirmation before executing shell commands.

Zero lock-in: You bring your own OpenRouter API key. No monthly seat subscription.
Feedback loop: The agent reads compiler output and test failures, self-correcting until tests pass.
Frugal by default: Only the diffs and relevant context are sent to the model.

Module 02

Ignition in 2 Commands

Choose your model preset and operating system. The command updates automatically with the latest live model ID from SWE-rebench.

Terminal commands

npm install -g opencode-ai
export OPENROUTER_API_KEY="sk-or-v1-..."
opencode --model openrouter/openai/gpt-5.6-sol

Need an API key? Get one in 30 seconds at openrouter.ai/keys and set a $5 spending limit for safe testing.

Module 03

The Auto-Configured Kickoff Prompt (Rules for Frugality)

Without strict engineering guardrails, autonomous agents can wander in loops, rewrite working code, or burn unnecessary tokens. Inject these operational rules into OpenCode.

System & Turn 0 Prompt

You are an autonomous Software Engineering Agent running via OpenCode.
You operate under strict production and cost constraints:

1. WORKFLOW DISCIPLINE (TDD FIRST)
   - Never modify business logic without a reproducible failing test first.
   - Run the project test suite to confirm RED status before writing any fix.
   - Implement the minimal surgical patch to reach GREEN.
   - Refactor only after tests pass.

2. TOKEN & COST FRUGALITY
   - Never read entire large files if not necessary. Use grep and search tools.
   - Keep diffs surgical and atomic.
   - Do not summarize what you are about to do; just execute the tools.

3. CIRCUIT BREAKER
   - If a test or command fails 3 times with the same error, STOP immediately.
   - Report the blockage clearly with the exact error output and ask for human input.

4. BENCHMARK BASELINE
   - Current cost baseline: ~$1.36 per resolved task (SWE-rebench standard).

Alternative (1-line setup): create an AGENTS.md file in your repository with these exact rules so OpenCode loads them automatically:

Shell command

cat << 'EOF' > AGENTS.md
# AGENTS.md — Engineering Rules
- TDD first: reproduce failure in a test before modifying code.
- Frugality: use search/grep before reading whole files.
- Circuit breaker: stop after 3 identical errors.
EOF

Module 04

The 60-Second "Hello Bug" Test

Run this safe, contained test in a temporary folder to watch OpenCode analyze a failing test, patch the code, and confirm GREEN autonomously.

Step 1: Create a dummy sandbox with an intentional bug:

Terminal setup

mkdir agent-test && cd agent-test
echo 'def add(a, b): return a - b  # Intentional bug' > math_utils.py
echo 'from math_utils import add
def test_add():
    assert add(2, 3) == 5' > test_math.py

Step 2: Launch OpenCode and give it the mission:

OpenCode prompt

/task Run pytest, diagnose the failure, fix math_utils.py, and verify tests pass.

Step 1: Create a dummy sandbox with an intentional bug (zero external packages required):

Terminal setup

mkdir agent-test && cd agent-test
echo 'export function add(a, b) { return a - b; } // Intentional bug' > math.js
echo 'import test from "node:test";
import assert from "node:assert";
import { add } from "./math.js";

test("add numbers", () => {
  assert.strictEqual(add(2, 3), 5);
});' > test.js

Step 2: Launch OpenCode and give it the mission:

OpenCode prompt

/task Run node --test, diagnose the failure, fix math.js, and verify tests pass.

What you will observe: OpenCode runs the test command, observes the assertion error, opens the math file, fixes the return operator from - to +, re-runs the test, confirms GREEN, and commits. Total cost: ~$0.01 – $0.03.