Skip to content

Commit a46b482

Browse files
leocavalcanteleocavalcante
committed
feat: initial release of opencoder autonomous runner
- Add opencoder script (v1.0.0) - Add comprehensive README with installation and usage docs - Support for provider presets (github, anthropic, openai, opencode) - Two-model architecture for planning and execution - State persistence and graceful shutdown - Exponential backoff retry logic Signed-off-by: leocavalcante <[email protected]>
1 parent 4933111 commit a46b482

File tree

2 files changed

+1200
-0
lines changed

2 files changed

+1200
-0
lines changed

‎README.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# opencoder
2+
3+
**Autonomous OpenCode Runner** - A POSIX-compliant Bash script that runs [OpenCode](https://opencode.ai) CLI in a fully autonomous way, creating development plans and executing them continuously without manual intervention.
4+
5+
## Features
6+
7+
- **Autonomous Development Loop** - Continuously plans, executes, and evaluates without stopping
8+
- **Two-Model Architecture** - Uses a high-capability model for planning and a faster model for execution
9+
- **Provider Presets** - Quick setup with GitHub Copilot, Anthropic, OpenAI, or OpenCode backends
10+
- **State Persistence** - Resumes from where it left off after interruptions
11+
- **Exponential Backoff** - Graceful retry logic for transient failures
12+
- **Plan History** - Archives completed plans for reference
13+
- **Signal Handling** - Clean shutdown with state preservation
14+
15+
## Installation
16+
17+
### Quick Install
18+
19+
```bash
20+
curl -fsSL https://raw.githubusercontent.com/opencodeco/opencoder/main/opencoder -o opencoder
21+
chmod +x opencoder
22+
sudo mv opencoder /usr/local/bin/
23+
```
24+
25+
### Manual Install
26+
27+
1. Download the script:
28+
```bash
29+
git clone https://github.com/opencodeco/opencoder.git
30+
cd opencoder
31+
```
32+
33+
2. Make it executable and move to PATH:
34+
```bash
35+
chmod +x opencoder
36+
sudo cp opencoder /usr/local/bin/
37+
```
38+
39+
## Requirements
40+
41+
- [OpenCode CLI](https://opencode.ai) installed and configured
42+
- Bash 4.0+ (macOS may need `brew install bash`)
43+
- Standard POSIX utilities (sed, grep, date)
44+
45+
## Usage
46+
47+
### Using Provider Presets (Recommended)
48+
49+
```bash
50+
# GitHub Copilot backend
51+
opencoder --provider github
52+
53+
# Anthropic Claude
54+
opencoder --provider anthropic
55+
56+
# OpenAI GPT
57+
opencoder --provider openai
58+
59+
# OpenCode free models
60+
opencoder --provider opencode
61+
```
62+
63+
### With a Hint/Instruction
64+
65+
Tell opencoder what to build:
66+
67+
```bash
68+
opencoder --provider github "build a REST API for user management"
69+
opencoder --provider anthropic "create a todo app with React"
70+
opencoder --provider opencode "implement authentication with JWT"
71+
```
72+
73+
### Using Explicit Models
74+
75+
```bash
76+
opencoder -P anthropic/claude-sonnet-4 -E anthropic/claude-haiku
77+
opencoder -P openai/gpt-4 -E openai/gpt-4o-mini "build a CLI tool"
78+
```
79+
80+
### Options
81+
82+
| Flag | Description |
83+
|------|-------------|
84+
| `--provider PROVIDER` | Use a provider preset (github, anthropic, openai, opencode) |
85+
| `-P, --planning-model MODEL` | Model for planning/evaluation phases |
86+
| `-E, --execution-model MODEL` | Model for task execution |
87+
| `-p, --project DIR` | Project directory (default: current directory) |
88+
| `-v, --verbose` | Enable verbose logging |
89+
| `-h, --help` | Show help message |
90+
91+
## Provider Presets
92+
93+
| Provider | Planning Model | Execution Model |
94+
|----------|----------------|-----------------|
95+
| `github` | claude-opus-4.5 | claude-sonnet-4.5 |
96+
| `anthropic` | claude-sonnet-4 | claude-haiku |
97+
| `openai` | gpt-4 | gpt-4o-mini |
98+
| `opencode` | glm-4.7-free | minimax-m2.1-free |
99+
100+
## How It Works
101+
102+
Opencoder implements an **agentic development loop** with three phases:
103+
104+
```
105+
+-------------+ +-------------+ +-------------+
106+
| Planning |---->| Execution |---->| Evaluation |
107+
| Phase | | Phase | | Phase |
108+
+-------------+ +-------------+ +-------------+
109+
^ |
110+
| |
111+
+---------------------------------------+
112+
(start new cycle)
113+
```
114+
115+
1. **Planning Phase** - Analyzes the project and creates a markdown checklist with 5-10 actionable tasks
116+
2. **Execution Phase** - Works through each task sequentially, making code changes and commits
117+
3. **Evaluation Phase** - Reviews completed work and decides whether to start a new cycle
118+
119+
The loop continues indefinitely until manually stopped (Ctrl+C).
120+
121+
## Directory Structure
122+
123+
Opencoder creates a `.opencoder/` directory in your project:
124+
125+
```
126+
.opencoder/
127+
├── state # Current execution state
128+
├── current_plan.md # Active task plan
129+
├── alerts.log # Critical error alerts
130+
├── config.env # Optional configuration overrides
131+
├── history/ # Archived completed plans
132+
│ └── plan_YYYYMMDD_HHMMSS_cycleN.md
133+
└── logs/
134+
├── main.log # Main rotating log
135+
└── cycles/ # Per-cycle detailed logs
136+
└── cycle_001.log
137+
```
138+
139+
## Environment Variables
140+
141+
| Variable | Default | Description |
142+
|----------|---------|-------------|
143+
| `OPENCODER_PROJECT_DIR` | `$PWD` | Default project directory |
144+
| `OPENCODER_MAX_RETRIES` | `3` | Max retries per operation |
145+
| `OPENCODER_BACKOFF_BASE` | `10` | Base seconds for exponential backoff |
146+
| `OPENCODER_LOG_RETENTION` | `30` | Days to keep old logs |
147+
148+
## Plan Format
149+
150+
Plans are saved as markdown checklists:
151+
152+
```markdown
153+
# Plan: Implement User Authentication
154+
155+
Created: 2026-01-16T10:30:00Z
156+
Cycle: 1
157+
158+
## Context
159+
Building a secure authentication system for the web application.
160+
161+
## Tasks
162+
- [ ] Task 1: Create user model with password hashing
163+
- [ ] Task 2: Implement JWT token generation
164+
- [ ] Task 3: Add login/logout endpoints
165+
- [ ] Task 4: Create authentication middleware
166+
- [ ] Task 5: Write unit tests for auth flow
167+
168+
## Notes
169+
Using bcrypt for password hashing, JWT for tokens.
170+
```
171+
172+
## Tips
173+
174+
- **Start with a clear hint** - The more specific your instruction, the better the initial plan
175+
- **Let it run** - Opencoder is designed to run continuously; trust the loop
176+
- **Check the logs** - Detailed logs are in `.opencoder/logs/` if something goes wrong
177+
- **Review history** - Completed plans are archived in `.opencoder/history/`
178+
179+
## License
180+
181+
MIT License - See [LICENSE](LICENSE) file.
182+
183+
## Author
184+
185+
[Leo Cavalcante](https://github.com/leocavalcante)
186+
187+
## Links
188+
189+
- [OpenCode CLI](https://opencode.ai)
190+
- [Report Issues](https://github.com/opencodeco/opencoder/issues)

0 commit comments

Comments
 (0)