🌾 Key Features

• 🚀 One run Command: paperfarm run . bootstraps a scout analysis, then enters the research loop — plan, review, experiment, repeat.

• 🤖 Multi-Agent Support: Works with Claude Code, Codex CLI, Aider, and Gemini CLI — pick your favorite.

• 🔬 Skill-Based Loop: Scout → Manager → Critic → Experiment — each phase is a markdown "skill" that an agent executes faithfully.

• 🖥️ Research TUI: Live dashboard with frontier status, metric charts, and structured log viewer. Keyboard controls for pause/resume/skip.

• 🛡️ Safety First: Every experiment is a git commit. Failed experiments auto-rollback via rollback.sh. Results logged to results.tsv with FileLock concurrency safety.

• 📡 Headless Mode: --headless for CI, scripts, or remote servers — no TUI needed.

• ⚡ Parallel Workers: Run experiments across multiple GPUs in isolated git worktrees — workers can't interfere with each other.

🌱 Quick Start

pip install PaperFarm

cd your-project
paperfarm run .

This launches a research session:

1. 🌱 Scout — survey the field: analyze your codebase, search related work, design evaluation metrics
2. 🚜 Manager — plan the crop: propose hypotheses, design experiments, maintain the frontier backlog
3. 🔍 Critic — inspect the plan: review experiment specs before execution, review evidence after
4. 🌾 Experiment — plant, test, harvest: implement one change, evaluate, record to results.tsv
5. 🔄 Repeat — until all frontier items are done or max_rounds is reached

Headless Mode

paperfarm run . --headless \
  --goal "Reduce val_loss below 0.3" \
  --agent-name codex

Parallel Workers

paperfarm run . --headless --workers 4 --agent-name codex

🚜 How It Works

PaperFarm creates a .research/ directory in your repo with everything needed for autonomous research.

Bootstrap
  └─ Scout — analyze codebase, define strategy and evaluation

Research Loop (repeats until done)
  ├─ Manager  — propose hypotheses, design experiments, maintain frontier
  ├─ Critic   — preflight review: approve or reject experiment specs
  ├─ Experiment — claim frontier item, implement change, evaluate, record
  └─ Critic   — post-run review: assess evidence, update claims

🛡️ Field Safety

🤖 Supported Agents

Default is claude-code. All agents receive the same skill prompt and work against the same .research/ state files.

📊 Interactive TUI Dashboard

Launch with TUI (default, no --headless):

paperfarm run . --agent-name claude-code

┌──────────────────────── PaperFarm ────────────────────────┐
│ Phase: experiment | Round: 3 | Hyps: 5 | Exps: 4/7 | Best: 1.92 │
│ scout  ‣  manager  ‣  critic  ‣  EXPERIMENT               │
├──[Execution]──[Metrics]──[Logs]────────────────────────────┤
│                                                             │
│  Frontier Panel              │  Worker Panel                │
│  frontier-001  keep   2.62   │  (idle)                      │
│  frontier-002  keep   2.40   │                              │
│  frontier-003  keep   2.31   │                              │
│  frontier-006  keep   1.92   │                              │
│                              │                              │
├─────────────────────────────────────────────────────────────┤
│ p Pause   r Resume   s Skip   q Quit             ^p palette│
└─────────────────────────────────────────────────────────────┘

🚜 Installation

Python 3.10+ required. Supports Linux, macOS, and Windows.

pip install (recommended)

pip install PaperFarm

cd your-project
paperfarm run .

From source (for development)

git clone https://github.com/shatianming5/PaperFarm.git
cd PaperFarm
pip install -e ".[dev]"
pytest

🖥️ CLI Reference

paperfarm run REPO [OPTIONS]    Launch or resume a research session
paperfarm status REPO           Show current research state
paperfarm results REPO          Display experiment results table

run Options

⚙️ Configuration

The scout agent fills .research/config.yaml during bootstrap. You can also edit it manually:

protocol: research-v1

metrics:
  primary:
    name: val_loss           # or test_accuracy, ops_per_sec, etc.
    direction: minimize      # minimize | maximize

limits:
  max_rounds: 20             # max research loop iterations
  timeout_minutes: 0         # 0 = no timeout

workers:
  max: 0                     # 0 = serial
  gpu_mem_per_worker_mb: 8192

agent:
  name: claude-code
  config: {}                 # passed to agent adapter

🏡 Project Structure

src/paperfarm/
├── cli.py              # Typer CLI (run / status / results)
├── agent.py            # Agent adapters (ClaudeCode, Codex, Aider, Gemini)
├── skill_runner.py     # Loads skills, substitutes [GOAL]/[TAG], drives the loop
├── state.py            # .research/ state file access layer
├── parallel.py         # WorkerPool for multi-GPU parallel experiments
├── skills/
│   ├── protocol.yaml   # Bootstrap + loop step order
│   ├── scout.md        # 🌱 Scout skill template
│   ├── manager.md      # 🚜 Manager skill template
│   ├── critic.md       # 🔍 Critic skill template
│   ├── experiment.md   # 🌾 Experiment skill template
│   └── scripts/
│       ├── record.py   # CLI tool for recording results (FileLock-safe)
│       └── rollback.sh # Revert failed experiments
└── tui/
    ├── app.py          # Textual TUI app (polling-based)
    ├── widgets.py      # StatsBar, PhaseStrip, FrontierPanel, etc.
    └── styles.css      # TUI styling

🌽 Examples

See examples/ for ready-to-run setups:

Running an Example

cd examples/cartpole
paperfarm run . --agent-name codex --headless \
  --goal "Maximize CartPole-v1 average reward to 500"

🧑‍🌾 Contributing

Contributions are welcome! Please:

1. Open an issue to discuss the proposed change
2. Fork the repository and create your feature branch
3. Submit a pull request with a clear description

📄 License

This project is licensed under the MIT License.

Star History