Autonomous OpenCode Runner - A TypeScript-powered CLI that uses the OpenCode SDK to run fully autonomous development loops, creating plans and building them continuously without manual intervention.
- Autonomous Development Loop - Continuously plans, builds, and evaluates without stopping
- OpenCode SDK Integration - Direct SDK integration with real-time event streaming
- Ideas Queue - Drop markdown files in
.opencode/opencoder/ideas/to prioritize specific tasks before autonomous plan - Two-Model Architecture - Uses a high-capability model for plan and a faster model for building
- Live Output Streaming - Real-time display of AI thinking, tool calls, and results
- State Persistence - Resumes from where it left off after interruptions (JSON format)
- Exponential Backoff - Graceful retry logic for transient failures
- Plan History - Archives completed plans for reference
- Signal Handling - Clean shutdown with state preservation
- Single Executable - Compiles to a standalone binary with Bun
OpenCode is an incredible AI coding agent with a powerful interactive TUI. You can have rich conversations, ask follow-up questions, and collaborate on complex problems. It's excellent when you want to work with the AI.
But what if you want the AI to work for you while you're away?
This concept is inspired by Dax Raad from OpenCode, who shares in this video that while AI is incredibly powerful, it doesn't replace the human creativity needed for high-level product decisions. Identifying a product's "aha moment" requires empathy and ruthless simplification that machines cannot replicate. The core elements of entrepreneurship - crafting unique ideas, designing intuitive experiences, and the difficult day-to-day strategic thinking - remain as demanding and human-centric as ever.
OpenCoder's insight is simple but powerful:
What if the AI never stopped improving your project?
Instead of interactive sessions where you guide the AI, OpenCoder creates an autonomous development loop that runs continuously:
| OpenCode (Interactive) | OpenCoder (Autonomous) |
|---|---|
| You drive the conversation | AI drives the development |
| Responds when you prompt | Runs continuously without prompts |
| Requires your presence | Works while you're away |
| You decide what's next | AI decides what's next |
| Great for collaboration | Great for delegation |
- Greenfield projects: "Build me a REST API" and walk away
- Overnight development: Start before bed, wake up to progress
- Continuous improvement: Let AI find and fix issues you haven't thought of
- Background tasks: Run while you focus on other work
- Interactive pair programming where you want to guide the AI
- Quick one-off tasks where you'll review immediately
- Complex decisions requiring human judgment at each step
- Learning by watching the AI's reasoning in real-time
OpenCoder treats software development as an infinite game. There's always another test to write, another edge case to handle, another optimization to make. OpenCoder embraces this by never declaring "done"—it continuously cycles through plan, build, and evaluation until you tell it to stop.
Download the latest release for your platform from GitHub Releases:
# Linux (x64)
curl -fsSL https://github.com/opencodeco/opencoder/releases/latest/download/opencoder-linux-x64 -o opencoder
# Linux (arm64)
curl -fsSL https://github.com/opencodeco/opencoder/releases/latest/download/opencoder-linux-arm64 -o opencoder
# macOS (Intel)
curl -fsSL https://github.com/opencodeco/opencoder/releases/latest/download/opencoder-darwin-x64 -o opencoder
# macOS (Apple Silicon)
curl -fsSL https://github.com/opencodeco/opencoder/releases/latest/download/opencoder-darwin-arm64 -o opencoder
# Make executable and move to PATH
chmod +x opencoder
sudo mv opencoder /usr/local/bin/Requires Bun 1.0+:
git clone https://github.com/opencodeco/opencoder.git
cd opencoder
bun install
bun run build
sudo cp opencoder /usr/local/bin/- OpenCode - OpenCoder uses the OpenCode SDK which starts the server automatically
# Run with a specific model
opencoder --model anthropic/claude-sonnet-4
# With a project directory and hint
opencoder -m anthropic/claude-sonnet-4 -p ./myproject "build a REST API"# Use a more capable model for plan, faster model for building
opencoder -P anthropic/claude-opus-4 -B anthropic/claude-sonnet-4| Flag | Description |
|---|---|
-m, --model MODEL |
Model for both plan and build (provider/model format) |
-P, --plan-model MODEL |
Model for plan/evaluation phases |
-B, --build-model MODEL |
Model for build phase |
-p, --project DIR |
Project directory (default: current directory) |
-v, --verbose |
Enable verbose logging |
-h, --help |
Show help message |
-V, --version |
Show version |
Models are specified as provider/model:
opencoder -m anthropic/claude-sonnet-4
opencoder -m openai/gpt-4o
opencoder -m google/gemini-2.0-flashOpenCoder implements an agentic development loop with three phases:
+-------------+ +-------------+ +-------------+
| Planning |---->| Build |---->| Evaluation |
| Phase | | Phase | | Phase |
+-------------+ +-------------+ +-------------+
^ |
| |
+---------------------------------------+
(start new cycle)
- Plan Phase - Analyzes the project and creates a markdown checklist with 3-7 actionable tasks
- Build Phase - Works through each task sequentially, making code changes
- Evaluation Phase - Reviews completed work and decides whether to start a new cycle (COMPLETE/NEEDS_WORK)
The loop continues indefinitely until manually stopped (Ctrl+C).
Create a .opencode/opencoder/config.json in your project:
{
"planModel": "anthropic/claude-sonnet-4",
"buildModel": "anthropic/claude-sonnet-4",
"verbose": false,
"maxRetries": 3,
"taskPauseSeconds": 2
}| Variable | Default | Description |
|---|---|---|
OPENCODER_PROJECT_DIR |
$PWD |
Default project directory |
OPENCODER_PLAN_MODEL |
- | Model for plan phase |
OPENCODER_BUILD_MODEL |
- | Model for build phase |
OPENCODER_VERBOSE |
false |
Enable verbose logging |
OPENCODER_MAX_RETRIES |
3 |
Max retries per operation |
OPENCODER_BACKOFF_BASE |
10 |
Base seconds for exponential backoff |
OPENCODER_LOG_RETENTION |
30 |
Days to keep old logs |
OPENCODER_TASK_PAUSE_SECONDS |
2 |
Pause between tasks |
Configuration is merged in this order (later overrides earlier):
- Defaults (hardcoded)
.opencode/opencoder/config.jsonin project directory- Environment variables (
OPENCODER_*) - CLI arguments
OpenCoder creates a .opencode/opencoder/ directory in your project:
.opencode/
└── opencoder/
├── config.json # Configuration file
├── state.json # Current state (JSON)
├── current_plan.md # Active task plan
├── ideas/ # Drop .md files here to queue tasks
│ ├── feature-x.md
│ └── bugfix-y.md
├── history/ # Archived completed plans
│ └── plan_YYYYMMDD_HHMMSS_cycleN.md
└── logs/
├── main.log # Main rotating log
└── cycles/ # Per-cycle detailed logs
└── cycle_001.log
Plans are saved as markdown checklists:
# Plan: Implement User Authentication
Created: 2026-01-17T10:30:00Z
Cycle: 1
## Context
Building a secure authentication system for the web application.
## Tasks
- [ ] Task 1: Create user model with password hashing
- [ ] Task 2: Implement JWT token generation
- [ ] Task 3: Add login/logout endpoints
- [ ] Task 4: Create authentication middleware
- [ ] Task 5: Write unit tests for auth flow
## Notes
Using bcrypt for password hashing, JWT for tokens.Want to direct OpenCoder toward specific tasks? Drop markdown files in .opencode/opencoder/ideas/ and OpenCoder will prioritize them before generating its own plans.
# Create an idea
cat > .opencode/opencoder/ideas/add-dark-mode.md << 'EOF'
# Add Dark Mode
Add dark mode toggle with system preference detection.
Steps:
1. Create theme context
2. Add toggle component
3. Persist preference to localStorage
EOF
# Run opencoder
opencoder -m anthropic/claude-sonnet-4- Before Planning - OpenCoder checks
.opencode/opencoder/ideas/for.mdfiles - Smart Selection:
- 1 idea: Uses it directly (no extra API call)
- 2+ ideas: AI evaluates all and picks the simplest/quick-win, considering dependencies
- Build - Selected idea is deleted, plan is created specifically for it
- Fallback - When ideas are exhausted, returns to autonomous plan
The AI prioritizes based on:
- Simplicity - Quick wins first
- Dependencies - If idea B requires idea A, A is selected first
- Priority order - Bug fixes > Small features > Docs > Refactoring > Large features
[Cycle 5] Found 3 idea(s) in queue
[Cycle 5] AI selected idea: fix-login-timeout.md
[Cycle 5] Planning for: fix-login-timeout.md
[Cycle 5] Plan created with 3 tasks
- Be specific - The more detailed the idea, the better the plan
- One idea per file - Keep ideas focused and atomic
- Mention dependencies - Explicitly state if an idea depends on another
- No naming convention - Any
.mdfilename works - Auto-cleanup - Empty/invalid ideas are automatically deleted
- Start with a clear hint - The more specific your instruction, the better the initial plan
- Use ideas for focus - Drop task files in
.opencode/opencoder/ideas/to direct development - Let it run - OpenCoder is designed to run continuously; trust the loop
- Check the logs - Detailed logs are in
.opencode/opencoder/logs/if something goes wrong - Review history - Completed plans are archived in
.opencode/opencoder/history/
Using Make (recommended):
make # Build release version
make test # Run tests
make lint # Format and check code with Biome
make clean # Remove build artifacts
make install # Install to /usr/local/bin
make install PREFIX=~/.local # Install to custom locationOr using Bun directly:
bun install # Install dependencies
bun run build # Build release executable
bun run dev # Run in development
bun test # Run tests
bunx biome check src/ # Check formatting/lintingMIT License - See LICENSE file.