multishot

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# 🏹 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*

🏹 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 - Product requirements, user stories, acceptance criteria
docs/DESIGN.md - System architecture, data flow, database schema
docs/TECH_STACK.md - All dependencies, versions, installation guide
docs/TASKS.md - Implementation checklist with phases
docs/PROJECT.md - Project overview, commands, timeline
CHANGELOG.md - Track of all changes made to the codebase
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:

User enters task prompt
App generates 4 prompt variations (via Claude API)
Spins up 4 Daytona sandboxes in parallel
Installs Claude Code CLI in each sandbox
Executes variations, streams output to UI terminals
User clicks "Select" on best agent
App extracts winner's files, destroys all sandboxes
User enters next prompt → files injected into 4 new sandboxes
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 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

User runs claude setup-token locally on their machine
Copy the OAuth token from output
App injects CLAUDE_CODE_OAUTH_TOKEN env var into each sandbox
Claude CLI uses token for authentication (no browser needed)

# 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):

User provides ANTHROPIC_API_KEY instead
App injects API key into sandboxes
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 for detailed checklist.

Development Setup

Prerequisites

# 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

# 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

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

Run Development Server

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

Start Here: README.md (this file)
Understand Requirements: docs/PRD.md
Understand Architecture: docs/DESIGN.md
Set Up Environment: docs/TECH_STACK.md
Follow Implementation: docs/TASKS.md
Quick Reference: docs/PROJECT.md
Track Changes: CHANGELOG.md
Error Reference: ERRORS.md

Contact & Resources

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

External Resources:

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

Generated with Claude Sonnet 4.5 on 2026-01-22