Autonomous AI-powered research with rigorous methodology, evidence tracking, and built-in quality controls.
Smithers runs Claude Code in an autonomous loop to conduct deep, evidence-based research on any topic. It enforces a 5-phase methodology, tracks every source and claim, scores credibility, requires counter-evidence, and halts automatically when it detects shallow patterns or fabrication.
Install once, use everywhere — Smithers becomes a global command available in any directory.
my-research/
├── .smithers/evidence/
│ ├── sources.json ← 15 credible sources, scored 0.0-1.0
│ ├── claims.json ← 23 claims with direct quotes
│ └── validations.json ← counter-evidence for every major claim
└── .smithers/evidence/SYNTHESIS.md ← final report with citations
# 1. Install (one time)
git clone https://github.com/dapdevsoftware/smithers.git
cd smithers && ./install.sh
# 2. Create a folder and tell Smithers what to research
mkdir ~/ai-coding-research && cd ~/ai-coding-research
smithers-enableThe wizard asks one thing — describe your research:
Describe what you want to research.
e.g., I want to understand the competitive landscape of AI coding
assistants — who the key players are, how they're priced, what
developers actually think of them, and whether there's a gap in
the CLI-native segment that no one is filling yet.
> I want to understand the competitive landscape of AI coding
> assistants and whether there's room for a new CLI-native tool.
Ready. Your research brief is at .smithers/RESEARCH_BRIEF.md
Your description becomes .smithers/RESEARCH_BRIEF.md. Smithers reads it, defines research questions during the SCOPE phase, then executes. Edit the file anytime to adjust scope.
# 3. Launch the research
smithers --monitorSmithers searches the web, reads sources, extracts claims with direct quotes, hunts for counter-evidence, and writes a final cited report to .smithers/evidence/SYNTHESIS.md. Watch it work in the tmux dashboard, or detach with Ctrl+B D and come back later.
Smithers enforces a strict 5-phase methodology. Each phase has completion requirements that must be met before advancing:
SCOPE → DISCOVER → DEEP_READ → VALIDATE → SYNTHESIZE
│ │ │ │ │
│ │ │ │ └─ Generate cited report
│ │ │ └─ Search for counter-evidence
│ │ └─ Extract claims with quotes from each source
│ └─ Find 5+ credible, diverse sources via WebSearch
└─ Define research questions, boundaries, success criteria
| Feature | What It Does |
|---|---|
| Evidence Tracking | Every claim links to a source with a direct quote |
| Credibility Scoring | Sources scored 0.0-1.0 based on type, publication tier, recency, author |
| Contrarian Enforcement | Must search for counter-evidence before completing research |
| Circuit Breaker | Halts on repeated searches, shallow reads, or fabrication (threshold=1) |
| Phase Gates | Can't advance without meeting evidence thresholds |
Sources are automatically scored based on:
- Type weights: Primary (0.95), data (0.90), secondary (0.75), news (0.60), opinion (0.45)
- Publication tier: Top-tier, mainstream, niche
- Recency: Half-life decay (2 years for academic, 6 months for news)
- Author credentials: Verified expert, known author, unknown
The loop checks completion in this priority order:
- Evidence-based completion — SYNTHESIS.md with RESEARCH_COMPLETE marker (ground truth)
- Permission denials — blocked tools requiring config updates
- Minimum loops — must reach MIN_RESEARCH_LOOPS (default: 3)
- Exit signal — Claude explicitly set EXIT_SIGNAL: true
- Safety limits — test-only loop stagnation
Graceful exit is checked before the circuit breaker, so completed research is always detected cleanly.
- Bash 4.0+
- Claude Code CLI —
npm install -g @anthropic-ai/claude-code - jq — JSON processing
- tmux — terminal multiplexer (recommended)
- Git
- GNU coreutils — for
timeout(macOS:brew install coreutils)
git clone https://github.com/dapdevsoftware/smithers.git
cd smithers
./install.shInstalls to ~/.local/bin/: smithers, smithers-monitor, smithers-setup, smithers-import, smithers-enable, smithers-enable-ci, smithers-migrate.
./uninstall.sh# Option A: Interactive wizard (recommended)
cd my-project
smithers-enable # Asks your topic and key questions
# Option B: Import an existing research brief
smithers-import brief.md my-research
# Option C: Blank project (you write the brief yourself)
smithers-setup market-research
# Then edit .smithers/RESEARCH_BRIEF.md with your research questionsAll three options create a .smithers/RESEARCH_BRIEF.md — this is the file that tells Smithers what to research. Edit it anytime to refine the scope.
smithers --monitor # tmux dashboard (recommended)
smithers # headless
smithers --status # check progress
smithers --verbose # detailed output
smithers --calls 50 # limit API calls/hoursmithers --status # JSON status
smithers --circuit-status # circuit breaker state
smithers --reset-circuit # reset after stagnation
smithers --reset-session # clear session context
tail -f .smithers/logs/smithers.log # live logsCtrl+BthenD— detach (keeps Smithers running)Ctrl+Bthen←/→— switch panestmux attach -t <session>— reattach
my-research/
├── .smithers/
│ ├── RESEARCH_BRIEF.md # Your research questions (edit this)
│ ├── status.json # Progress tracking (auto)
│ ├── evidence/
│ │ ├── sources.json # Discovered sources with scores
│ │ ├── claims.json # Extracted claims with quotes
│ │ ├── validations.json # Counter-evidence records
│ │ └── SYNTHESIS.md # Final report (auto)
│ ├── phases/ # Phase completion notes
│ ├── prompts/ # Phase-specific prompts (templates)
│ ├── logs/ # Execution logs
│ ├── scratchpad/ # Working notes
│ └── contrarian_checks.json # Counter-evidence tracking
├── .smithersrc # Project config
└── README.md
PROJECT_NAME="my-research"
# Loop settings
MAX_CALLS_PER_HOUR=100
CLAUDE_TIMEOUT_MINUTES=15
CLAUDE_OUTPUT_FORMAT="json"
# Tool permissions
ALLOWED_TOOLS="WebSearch,WebFetch,Read,Write,Edit,Bash(git *)"
# Session
CLAUDE_USE_CONTINUE=true
SESSION_EXPIRY_HOURS=24
# Research thresholds
MIN_SOURCES=5
MIN_CLAIMS_PER_SOURCE=2
REQUIRE_COUNTER_EVIDENCE=true
# Circuit breaker
CB_NO_PROGRESS_THRESHOLD=3
CB_FABRICATION_THRESHOLD=1 # immediate halt on fabricationClaude reports status at the end of each loop:
SMITHERS_STATUS:
PHASE: DISCOVER
STATUS: IN_PROGRESS
EXIT_SIGNAL: false
SOURCES_FOUND: 8
SOURCES_READ: 3
CLAIMS_EXTRACTED: 12
VALIDATIONS_COMPLETED: 0
# Installation (run once)
./install.sh # Install globally
./uninstall.sh # Remove from system
smithers-migrate # Migrate existing project
# Project setup
smithers-setup <name> # New blank project
smithers-enable # Enable in current dir (interactive)
smithers-enable-ci [--force] # Enable (non-interactive)
smithers-import <brief> <name> # Import research brief
# Research loop
smithers [OPTIONS]
-m, --monitor tmux dashboard
-s, --status Show status
-v, --verbose Detailed output
-c, --calls NUM Max calls/hour (default: 100)
-t, --timeout NUM Claude timeout in minutes
--reset-session Clear session state
--reset-circuit Reset circuit breaker
--circuit-status Show CB state
--output-format FORMAT json or text
--allowed-tools TOOLS Override tool permissions
--no-continue Disable session continuity
--session-expiry HOURS Session expiry (default: 24)| Problem | Solution |
|---|---|
| Rate limited | Smithers auto-waits with countdown |
| 5-hour API limit | Smithers prompts: wait 60min or exit |
| Stuck in phase | Check .smithers/status.json for unmet requirements |
| Circuit breaker open | Review logs, then smithers --reset-circuit |
| Shallow research halt | Claims need direct quotes from sources |
| No counter-evidence | Contrarian checks required — can't skip |
| Session expired | smithers --reset-session |
timeout: not found (macOS) |
brew install coreutils |
See CONTRIBUTING.md.
Priority areas:
- Testing — expand coverage for research components
- Quality controls — new circuit breaker patterns
- Real-world testing — use it, report issues, share feedback
MIT — see LICENSE.
- Inspired by the Ralph technique by Geoffrey Huntley
- Powered by Claude Code by Anthropic