---
slug: "multishot"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/seanchiuai/multishot@main/README.md"
repo: "https://github.com/seanchiuai/multishot"
source_file: "README.md"
branch: "main"
---
# 🏹 Multishot

**Parallel Claude Code Agent Orchestration for Exploratory Development**

Electron desktop app that runs 4 Claude Code agents simultaneously in isolated Daytona sandboxes, each exploring different approaches to the same task. Pick the best solution, iterate in the next round with the winner's codebase as the starting point.

**Hackathon:** Daytona Hacksprint (Jan 26, 2026)
**Status:** ✅ Planning Complete → Ready for Implementation

---

## Quick Links

- **[docs/PRD.md](https://github.com/seanchiuai/multishot/blob/HEAD/docs/PRD.md)** - Product requirements, user stories, acceptance criteria
- **[docs/DESIGN.md](https://github.com/seanchiuai/multishot/blob/HEAD/docs/DESIGN.md)** - System architecture, data flow, database schema
- **[docs/TECH_STACK.md](https://github.com/seanchiuai/multishot/blob/HEAD/docs/TECH_STACK.md)** - All dependencies, versions, installation guide
- **[docs/TASKS.md](https://github.com/seanchiuai/multishot/blob/HEAD/docs/TASKS.md)** - Implementation checklist with phases
- **[docs/PROJECT.md](https://github.com/seanchiuai/multishot/blob/HEAD/docs/PROJECT.md)** - Project overview, commands, timeline
- **[CHANGELOG.md](https://github.com/seanchiuai/multishot/blob/HEAD/CHANGELOG.md)** - Track of all changes made to the codebase
- **[ERRORS.md](https://github.com/seanchiuai/multishot/blob/HEAD/ERRORS.md)** - Error log with root causes and solutions

---

## The Idea

**Problem:** When building software, you often don't know the best approach upfront. Should you use Library A or B? Pattern X or Y? Trial-and-error wastes time.

**Solution:** Run 4 agents in parallel, each trying a different approach. Observe them working simultaneously, pick the winner, and iterate on that solution in subsequent rounds.

**Example Flow:**

```
Round 1: "Build a snake game in Python"
├── Agent 1: Uses pygame (object-oriented)
├── Agent 2: Uses tkinter (functional)
├── Agent 3: Uses curses (terminal-based)
└── Agent 4: Uses web canvas (Flask + JS)

→ User selects Agent 1 (pygame) as winner

Round 2: "Add score counter and high score tracking"
├── All 4 agents start with Agent 1's pygame code
├── Each tries different score persistence methods
└── User picks best implementation

Round 3: "Add difficulty levels"
→ Continue iterating...
```

---

## Architecture at a Glance

```
┌─────────────────────────────────────────┐
│   Electron App (Your Computer)         │
│                                         │
│   ┌─────────────────────────────────┐   │
│   │   React UI (2x2 Grid)           │   │
│   │   ┌───────┬───────┐             │   │
│   │   │ Term1 │ Term2 │ xterm.js    │   │
│   │   ├───────┼───────┤             │   │
│   │   │ Term3 │ Term4 │             │   │
│   │   └───────┴───────┘             │   │
│   └─────────────────────────────────┘   │
│                ▲ IPC                    │
│   ┌────────────▼────────────────────┐   │
│   │   Node.js Main Process          │   │
│   │   - Sandbox Manager             │   │
│   │   - Auth Manager                │   │
│   │   - SQLite Database             │   │
│   └─────────────────────────────────┘   │
└─────────────────────────────────────────┘
           │ API Calls
           ▼
┌─────────────────────────────────────────┐
│   Daytona Cloud                         │
│   ┌──────┬──────┬──────┬──────┐        │
│   │ Sb 1 │ Sb 2 │ Sb 3 │ Sb 4 │        │
│   │[CLI] │[CLI] │[CLI] │[CLI] │        │
│   └──────┴──────┴──────┴──────┘        │
└─────────────────────────────────────────┘
```

**Key Flow:**
1. User enters task prompt
2. App generates 4 prompt variations (via Claude API)
3. Spins up 4 Daytona sandboxes in parallel
4. Installs Claude Code CLI in each sandbox
5. Executes variations, streams output to UI terminals
6. User clicks "Select" on best agent
7. App extracts winner's files, destroys all sandboxes
8. User enters next prompt → files injected into 4 new sandboxes
9. Repeat

---

## Tech Stack Summary

**Desktop:** Electron + React + TypeScript
**Terminal:** xterm.js
**Database:** SQLite (better-sqlite3)
**APIs:** Daytona SDK, Anthropic SDK
**Build:** Vite + electron-builder

See [TECH_STACK.md](https://github.com/seanchiuai/multishot/blob/HEAD/TECH_STACK.md) for full dependency list and versions.

---

## Critical Challenge: Claude Code OAuth in Sandboxes

**The Problem:**
Claude Code CLI requires browser-based OAuth, but Daytona sandboxes are headless (no browser).

**The Solution:**

### Primary Approach
1. User runs `claude setup-token` locally on their machine
2. Copy the OAuth token from output
3. App injects `CLAUDE_CODE_OAUTH_TOKEN` env var into each sandbox
4. Claude CLI uses token for authentication (no browser needed)

```bash
# On your local machine (one-time setup)
claude setup-token

# Output: CLAUDE_CODE_OAUTH_TOKEN=xxxxx
# Copy this token into app settings
```

### Fallback Approach
If token auth fails (see [known issue](https://github.com/anthropics/claude-code/issues/8938)):
1. User provides `ANTHROPIC_API_KEY` instead
2. App injects API key into sandboxes
3. Claude CLI uses direct API authentication

**Required Accounts:**
- Daytona account with API key
- Claude Pro/Max subscription (for `setup-token`) **OR** Anthropic API credits

---

## Implementation Timeline (Hackathon Day)

**Total:** ~12 hours

| Phase | Time | Tasks |
|-------|------|-------|
| Setup | 0.5h | Project init, dependencies, structure |
| Auth | 1h | Setup wizard, credential validation |
| Sandboxes | 2h | Create sandboxes, install CLI |
| Prompts | 0.75h | Generate variations via Claude API |
| UI & Streaming | 2h | Grid layout, xterm.js integration |
| Execution | 1.5h | Run agents, status tracking |
| Winner Selection | 1.5h | Extract files, destroy sandboxes |
| Next Round | 1.5h | File injection, iteration |
| Polish | 1.5h | Error handling, UI refinements |
| **Demo Prep** | **1h** | **Test 3-round flow, package app** |

See [TASKS.md](https://github.com/seanchiuai/multishot/blob/HEAD/TASKS.md) for detailed checklist.

---

## Development Setup

### Prerequisites

```bash
# Node.js 20+ (LTS)
node --version  # v20.11.0+

# Accounts & Keys
# 1. Daytona account → get API key from dashboard
# 2. Claude Pro/Max → run: claude setup-token
#    OR Anthropic API credits → get key from console.anthropic.com
```

### Installation

```bash
# Create project
mkdir multishot && cd multishot
npm init -y

# Install dependencies (see TECH_STACK.md for full list)
npm install @daytonaio/sdk @anthropic-ai/sdk better-sqlite3 \
  react react-dom xterm xterm-addon-fit electron

npm install --save-dev typescript vite electron-builder \
  @types/react @types/node tailwindcss

# Setup config files
npx tsc --init
npx tailwindcss init -p

# Create .env
cp .env.example .env
# Edit .env with your API keys
```

### Environment Variables

```bash
# .env
DAYTONA_API_KEY=dtn_xxxxx
CLAUDE_CODE_OAUTH_TOKEN=your_token_here
# OR
ANTHROPIC_API_KEY=sk-ant-xxxxx
```

### Run Development Server

```bash
npm run dev
```

---

## Demo Script

**Objective:** Show 3-round iterative development of a snake game.

### Round 1: Initial Build
**Prompt:** "Build a snake game in Python"

**Expected Outcomes:**
- Agent 1: pygame implementation
- Agent 2: tkinter implementation
- Agent 3: terminal-based (curses)
- Agent 4: web-based (Flask + canvas)

**Action:** Select pygame agent (best GUI + performance)

### Round 2: Feature Addition
**Prompt:** "Add score counter and high score tracking"

**Expected Outcomes:**
- All agents start with pygame code from Round 1
- Different approaches to score persistence (file, SQLite, JSON)

**Action:** Select best persistence implementation

### Round 3: Enhancement
**Prompt:** "Add difficulty levels (easy, medium, hard)"

**Expected Outcomes:**
- Speed variations, obstacle generation, etc.

**Action:** Select polished version → **Final playable game!**

**Demo Time:** <5 minutes
**Wow Factor:** Watch 4 terminals building simultaneously, pick best-of-breed

---

## Success Metrics

✅ **MVP Complete:**
- User can create run with task prompt
- 4 agents execute in parallel with live terminal streaming
- Winner selection extracts state correctly
- Next round injects winner files into new agents
- Multiple rounds iterate successfully

✅ **Demo Success:**
- Complete 3-round snake game in <5 min
- No crashes during presentation
- Clear visual impact (4 terminals, different approaches)
- Audience understands value proposition

---

## Known Risks & Mitigations

| Risk | Mitigation |
|------|------------|
| `CLAUDE_CODE_OAUTH_TOKEN` doesn't work | Implement `ANTHROPIC_API_KEY` fallback on Day 1 |
| Sandbox creation slow (20-30s) | Show clear loading indicator, set expectations |
| Terminal streaming lag | Buffer outputs (100ms), optimize IPC |
| All 4 agents fail | Allow run restart with modified prompt |
| Network issues during demo | Record backup demo GIF |

---

## Post-Hackathon Ideas

- **Auto-scoring:** Claude evaluates outputs, recommends winner
- **File preview:** Monaco editor for viewing code
- **Agent metrics:** Token usage, execution time, error count
- **Cloud sync:** Share runs across devices
- **Custom agents:** User-defined Docker images
- **Collaboration mode:** Agents communicate and combine solutions

---

## File Structure

```
multishot/
├── README.md           # This file
├── CLAUDE.md           # Claude Code agent guidance
├── CHANGELOG.md        # Track of all changes
├── ERRORS.md           # Error log with solutions
├── docs/               # Project documentation
│   ├── PRD.md          # Product requirements
│   ├── DESIGN.md       # System architecture
│   ├── TECH_STACK.md   # Dependencies & tools
│   ├── TASKS.md        # Implementation checklist
│   └── PROJECT.md      # Project overview
├── prompts/            # LLM prompt templates
├── .claude/skills/     # Claude Code agent skills
│   ├── daytona-integration/
│   ├── electron-ipc/
│   ├── database-schema/
│   ├── terminal-streaming/
│   └── auth-flow/
└── src/                # (when implemented)
    ├── main/           # Electron main process
    ├── renderer/       # React UI
    └── shared/         # Shared types
```

---

## Documentation Index

1. **Start Here:** README.md (this file)
2. **Understand Requirements:** [docs/PRD.md](https://github.com/seanchiuai/multishot/blob/HEAD/docs/PRD.md)
3. **Understand Architecture:** [docs/DESIGN.md](https://github.com/seanchiuai/multishot/blob/HEAD/docs/DESIGN.md)
4. **Set Up Environment:** [docs/TECH_STACK.md](https://github.com/seanchiuai/multishot/blob/HEAD/docs/TECH_STACK.md)
5. **Follow Implementation:** [docs/TASKS.md](https://github.com/seanchiuai/multishot/blob/HEAD/docs/TASKS.md)
6. **Quick Reference:** [docs/PROJECT.md](https://github.com/seanchiuai/multishot/blob/HEAD/docs/PROJECT.md)
7. **Track Changes:** [CHANGELOG.md](https://github.com/seanchiuai/multishot/blob/HEAD/CHANGELOG.md)
8. **Error Reference:** [ERRORS.md](https://github.com/seanchiuai/multishot/blob/HEAD/ERRORS.md)

---

## Contact & Resources

**Project Lead:** Sean Chiu
**Hackathon:** Daytona Hacksprint (Jan 26, 2026)
**Planning Completed:** Jan 22, 2026

**External Resources:**
- [Daytona Docs](https://www.daytona.io/docs/)
- [Daytona TypeScript SDK](https://www.daytona.io/docs/en/typescript-sdk/)
- [Anthropic API Docs](https://docs.anthropic.com/)
- [Claude Code Setup](https://code.claude.com/docs/en/setup)
- [xterm.js Guide](https://xtermjs.org/)
- [Electron IPC](https://www.electronjs.org/docs/latest/tutorial/ipc)

---

**Status:** 🚀 Ready to Build
**Next Step:** Initialize project structure (see TASKS.md Phase 1)

*Generated with Claude Sonnet 4.5 on 2026-01-22*