Single-user desktop recursive multi-agent IDE — orchestrate complex coding runs on your local machine.

OneShot is a single-user desktop recursive multi-agent IDE with a full orchestration layer. Instead of a single-agent flow, OneShot decomposes your prompt into a Directed Acyclic Graph of tasks, spawns parallel agents for each node, isolates them in shadow git worktrees, validates output with quality/deploy gates, and ingests branch results back into your main branch.

Fork attribution: OneShot is a fork of sst/opencode. This project builds on that foundation and adds a single-user desktop orchestration runtime.

Screenshot tour

OneShot has local auto-setup launch helpers:

• ./scripts/launch.sh (macOS/Linux)
• ./scripts/launch.ps1 (Windows PowerShell)
• ./scripts/launch.bat (Windows batch)
• ./scripts/launch.command (macOS double-click)

---

How It Works

User Prompt
    │
    ▼
┌─────────────────────────────┐
│   Temporal Workflow         │  Durable execution for each run
│   (runtime/workflow.ts)     │  with start/kill/resume semantics
└────────────┬────────────────┘
             │
             ▼
┌─────────────────────────────┐
│   LangGraph Engine          │  research → planning → execution
│   (runtime/langgraph-engine)│  with dependency-aware task flow
└────────────┬────────────────┘
             │
             ▼
┌─────────────────────────────┐
│   Worker Execution          │  Task workers execute in project context
│   (worker + agent runtime)  │  and stream task/run events
└────────────┬────────────────┘
             │
             ▼
┌─────────────────────────────┐
│   Snapshot History          │  Persisted run + graph snapshots
│   (orchestrator/history.ts) │  in .oneshot/orchestrator-history
└─────────────────────────────┘

---

State Persistence

OneShot persists orchestration snapshots in .oneshot/orchestrator-history. If the process crashes, resume with:

oneshot orchestrate --resume

Each snapshot includes:

• Full task DAG with statuses and results
• Token usage for the run
• Structured task metadata and dependencies
• Summary/index metadata for fast historical listing

---

 OneShot Mission Control  RUN: 3A7F2B1E  ACTIVE  62%  elapsed: 12m 4s
────────────────────────────────────────────────────────────────────────

 AGENT TREE

  [DONE]    Setup PostgreSQL schema & migrations
  [DONE]    Implement JWT authentication middleware
  └── [WORKING]  Build user registration & login API      (8m 12s)
      └── [WORKING]  OAuth GitHub integration             (3m 45s)
  [WORKING] Create boards/lists/cards REST endpoints      (11m 33s)
  [WORKING] Setup WebSocket real-time event system        (6m 02s)
  [IDLE]    Build React drag-and-drop frontend
  [IDLE]    Write integration test suite
  [FAILED]  Setup Redis session store                     [Retry #1]

  Total: 10  Done: 2  Running: 4  Pending: 3  Failed: 1

────────────────────────────────────────────────────────────────────────

## Requirements

- Git ≥ 2.5 (for `git worktree`)
- LLM Provider

If you use the launch scripts below, OneShot will auto-check/install most local requirements for you (Bun/Rust/Tauri deps/Temporal where possible).

Manual setup requirements (source/dev builds):
- [Bun](https://bun.sh) ≥ 1.0
- Rust + Cargo (for desktop/Tauri)
- [Temporal Server](https://github.com/temporalio/temporal) reachable at `127.0.0.1:7233` (or set `TEMPORAL_ADDRESS`)
- [Temporal CLI](https://github.com/temporalio/cli) (`temporal`) installed on your PATH

> OneShot orchestration uses Temporal for durable workflow execution. The runtime starts a worker in-process and uses the `temporal` CLI to start/signal/query workflows.
>
> Desktop release bundles include both `oneshot-cli` and `temporal` sidecars and will auto-start local Temporal by default, so end users do not need a separate Temporal install.

Download a built release

If you don’t want to build from source, download a signed, prebuilt desktop app from the GitHub Releases page:

• https://github.com/braedonsaunders/oneshot/releases/latest

Pick the installer for your OS:

• macOS: .dmg / .app
• Windows: .exe (NSIS)
• Linux: .deb and .rpm

After downloading:

1. Install and launch OneShot.
2. Add your provider key in .env or directly in your shell:
   • export ANTHROPIC_API_KEY=...
3. Run an orchestration command to start immediately.

---

Orchestrator Usage

Interactive prompt

oneshot orchestrate
# Prompts you interactively for the task description

With flags

oneshot orchestrate "Build X" \
  --provider anthropic \           # anthropic | openai | deepseek
  --model claude-3-5-sonnet-20241022 \
  --budget 2000000 \               # token budget for entire run
  --parallel 20 \                  # max concurrent agents
  --depth 3                        # max recursion depth

Headless (server-only, no TUI)

oneshot orchestrate "Build X" --no-tui

Resume after crash

oneshot orchestrate --resume
# Loads the latest resumable snapshot from .oneshot/orchestrator-history

Watch an existing run

oneshot orchestrate --watch <run-id>
# Attaches Mission Control TUI to an already-running orchestration

Orchestration control actions

# List runs
oneshot orchestrate list

# Show one run (summary) or JSON state
oneshot orchestrate get <run-id>
oneshot orchestrate get <run-id> --format json

# Pause / kill / delete
oneshot orchestrate pause <run-id>
oneshot orchestrate kill <run-id>
oneshot orchestrate delete <run-id>

# Resume latest or specific run snapshot
oneshot orchestrate resume
oneshot orchestrate resume <run-id>

# Deploy a run result
oneshot orchestrate deploy <run-id>
oneshot orchestrate deploy <run-id> --wait --reason "manual approval"

# Message the master orchestrator
oneshot orchestrate message <run-id> "Prioritize mobile-first UX and fix failing auth tests"

# Escalations
oneshot orchestrate escalations <run-id>
oneshot orchestrate escalations <run-id> --pending
oneshot orchestrate resolve <run-id> <escalation-id> "Use Redis for shared session cache"

# Scratchpad
oneshot orchestrate scratchpad <run-id>
oneshot orchestrate scratchpad-write <run-id> deployment_target staging

# Persistent queue (cross-run memory)
oneshot orchestrate tasks
oneshot orchestrate ready
oneshot orchestrate claim <task-id> --actor user
oneshot orchestrate close <task-id> "done"
oneshot orchestrate link <from-task-id> <to-task-id> --link-type duplicates
oneshot orchestrate compact --days 30 --limit 100

If your prompt starts with a control-like word (pause, list, resume, etc.), prefix with start to force prompt mode:

oneshot orchestrate start "pause background video autoplay on mobile Safari"

---

Environment Variables

Copy .env.example to .env and fill in your keys:

cp .env.example .env

Variable	Default	Description
ANTHROPIC_API_KEY	—	Anthropic Claude API key
OPENAI_API_KEY	—	OpenAI API key
DEEPSEEK_API_KEY	—	DeepSeek API key
ONESHOT_DEFAULT_PROVIDER	anthropic	Default AI provider
ONESHOT_SERVER_HOST	127.0.0.1	HTTP server host
ONESHOT_SERVER_PORT	3141	HTTP server port
ONESHOT_MAX_AGENTS	100	Max parallel agents
ONESHOT_MAX_RECURSION_DEPTH	5	Max agent recursion depth
ONESHOT_MAX_REPLAN_CYCLES	250	Max supervisor replan cycles per run
ONESHOT_MAX_TOKENS_BUDGET	5000000	Default token budget
ONESHOT_TOKEN_KILL_THRESHOLD	4000000	Hard kill threshold
ONESHOT_CHECKPOINT_INTERVAL_MS	60000	Checkpoint frequency
ONESHOT_MODEL_CALL_TIMEOUT_MS	600000	Per-model call timeout for worker tasks
ONESHOT_STALE_TASK_THRESHOLD_MS	360000	Supervisor stale-task threshold before intervention
ONESHOT_INSTANCE_BOOTSTRAP_TIMEOUT_MS	0 (disabled)	Optional hard timeout for worker bootstrap; <=0 disables
ONESHOT_VERIFICATION_ISOLATE_WORKTREE	1 (true)	Run deterministic verification in an isolated git worktree to avoid mutating main checkout
TEMPORAL_ADDRESS	127.0.0.1:7233	Temporal frontend address
TEMPORAL_NAMESPACE	default	Temporal namespace for workflows
TEMPORAL_TASK_QUEUE	oneshot-orchestrator-v2	Task queue used by orchestrator workflows

---

Architecture

packages/
├── oneshot/              # Core CLI + orchestration engine
│   └── src/
│       ├── orchestrator/ # ← OneShot additions
│       │   ├── types.ts           Zod schemas
│       │   ├── history.ts         Snapshot persistence
│       │   ├── mission-control.ts TUI display
│       │   ├── index.ts           Public API
│       │   └── runtime/           LangGraph + Temporal runtime
│       ├── server/routes/
│       │   └── orchestrator.ts    REST + SSE endpoints
│       ├── cli/cmd/
│       │   └── orchestrate.ts     CLI command
│       ├── agent/        # Core agent runtime (extended)
│       ├── session/      # Internal worker/session state management
│       ├── provider/     # Provider-agnostic AI layer
│       └── server/       # Hono HTTP server
├── app/                  # Desktop app (Tauri)
├── ui/                   # Shared UI components (SolidJS)
└── sdk/                  # TypeScript SDK

---

Credits

• Upstream project: sst/opencode
• OneShot is a fork with additional orchestration, runtime, and desktop workflow changes.
• Thank you to the opencode maintainers and contributors for the original project.

---

License

MIT. See LICENSE and NOTICE.