Round and round we go

OCLoop is a loop harness that orchestrates OpenCode to execute tasks from a PLAN.md file iteratively. Each iteration runs in an isolated session, with full visibility into what OpenCode is doing.

• Automated task execution — Execute a plan one task at a time, each in a fresh context window
• Live dashboard — Visual status with iteration timing, averages, ETA, and progress bar
• Activity log — Real-time view of tool usage, file edits, token counts, and git diffs
• Terminal integration — Launch OpenCode in an external terminal to interact mid-iteration
• Command palette — Quick access to actions via Ctrl+P
• Knowledge persistence — Learnings documented in AGENTS.md and docs/ across iterations
• Theme sync — Automatically inherits your OpenCode theme (32 themes bundled)
• Debug mode — Sandbox for manual session creation without a plan file

• Bun runtime (v1.0 or later)
• OpenCode installed and configured

# Install globally
bun add -g ocloop

# Or run directly without installing
bunx ocloop

# Clone the repository
git clone https://github.com/d3vr/ocloop.git
cd ocloop

# Install dependencies
bun install

# Build the project
bun run build

# Link globally
bun link

1. Create a plan file (PLAN.md) and loop prompt file (.loop-prompt.md):

cp examples/PLAN.md ./PLAN.md
cp examples/loop-prompt.md ./.loop-prompt.md  # Note the leading dot

See examples/CREATE_PLAN.md for a prompt to help generate plans for your project.

1. Run OCLoop:

ocloop

1. Press S to start executing tasks (or use -r to start immediately)

Usage: ocloop [options]

Options:
  -p, --port <number>      Server port (default: 4096, falls back to random)
  -m, --model <string>     Model to use (passed to opencode)
  -a, --agent <string>     Agent to use (default: build)
  -r, --run                Start iterations immediately (skip the ready screen)
  -d, --debug              Debug/sandbox mode (no plan file required)
  --verbose                Enable verbose logging to .loop.log
  --prompt <path>          Path to loop prompt file (default: .loop-prompt.md)
  --plan <path>            Path to plan file (default: PLAN.md)
  -v, --version            Show version number
  -h, --help               Show help

Examples:
  ocloop                           # Start with defaults
  ocloop -r                        # Start immediately without waiting
  ocloop -m claude-sonnet-4        # Use specific model
  ocloop -a plan                   # Use the plan agent
  ocloop --plan my-plan.md         # Use custom plan file
  ocloop -d                        # Debug mode for experimentation

OCLoop parses your PLAN.md to track progress. Supported task formats:

- [ ] Pending task (will be executed)
- [x] Completed task
- [MANUAL] Task requiring human intervention (skipped)
- [BLOCKED: reason] Task that cannot proceed (skipped)

Using bold task IDs helps with organization:

- [ ] **1.1** First task in phase 1
- [ ] **1.2** Second task in phase 1
- [ ] **2.1** First task in phase 2

1. OCLoop starts the OpenCode server
2. Creates a new session for each iteration
3. Sends your loop prompt to the session
4. Waits for the session to become idle (task complete)
5. Checks for <plan-complete> tag in plan file
6. If not complete, starts the next iteration

The loop ends when:

• Model appends <plan-complete>summary</plan-complete> to the plan file (all automatable tasks done)
• You quit manually with Q
• An unrecoverable error occurs

OCLoop respects OpenCode's environment variables for API keys and configuration. See OpenCode documentation for details.

OCLoop automatically detects your OpenCode theme from ~/.local/state/opencode/kv.json and applies it to the dashboard. Includes all 32 bundled OpenCode themes.

On first use of T (terminal launcher), OCLoop detects installed terminals and saves your preference to ~/.config/ocloop/ocloop.json. Supports: Alacritty, Kitty, WezTerm, GNOME Terminal, Konsole, and more.

The examples/ directory contains starter templates:

• PLAN.md — Example task plan demonstrating all supported markers
• loop-prompt.md — Example loop prompt with best practices
• CREATE_PLAN.md — Prompt to help generate a plan for your project

To use them:

cp examples/PLAN.md ./PLAN.md
cp examples/loop-prompt.md ./.loop-prompt.md  # Note the leading dot

# Run in development mode
bun run dev

# Run tests
bun test

# Build for production
bun run build

Create a .loop-prompt.md file with instructions for executing plan tasks. See Quick Start above.

Create a PLAN.md file with tasks. At minimum:

## Backlog
- [ ] Your first task

• Ensure OpenCode is properly installed and available in your PATH
• Check OpenCode logs for errors (usually in .opencode/ directory)
• Verify your API keys are configured correctly

• Press T to launch OpenCode in an external terminal and see what's happening
• Check if OpenCode is waiting for input or confirmation
• Look at the activity log for recent events

MIT