<p align="center">
<img src="https://raw.githubusercontent.com/rachpradhan/agent-lab/main/agent-lab.png" alt="AgentLab" width="480" />
</p>
<h3 align="center">Multi-agent scientific reasoning, from intuition to testable hypothesis.</h3>
<p align="center">
<a href="https://github.com/justrach/agentlab/releases/latest"><img src="https://img.shields.io/github/v/release/justrach/agentlab?style=flat-square&label=version" alt="Latest Release" /></a>
<a href="https://github.com/justrach/agentlab/blob/main/LICENSE"><img src="https://img.shields.io/github/license/justrach/agentlab?style=flat-square" alt="License" /></a>
<img src="https://img.shields.io/badge/built_with-Zig-f7a41d?style=flat-square" alt="Built with Zig" />
<img src="https://img.shields.io/badge/MCP-compatible-6c63ff?style=flat-square" alt="MCP Compatible" />
</p>
<p align="center">
One MCP server. <strong>38 tools.</strong> Drop it into Claude Code, Codex, or Amp — get parallel agents,<br/>
hypothesis trajectories, and sandboxed compute without leaving your editor.
</p>
<p align="center">
<a href="#-quick-start">Quick Start</a> ·
<a href="#-hypothesis-engine">Hypothesis Engine</a> ·
<a href="#-real-output-dissipative-baryogenesis">Real Output</a> ·
<a href="#-all-38-tools">All Tools</a> ·
<a href="#-architecture">Architecture</a>
</p>
---
> **Fork notice:** Forked from [DevSwarm](https://github.com/justrach/devswarm) at [`ca6f0d6`](https://github.com/justrach/devswarm/commit/ca6f0d6384e0f0ad0b74201d728ce1f2dd3ed18f). Shares the agent runtime, MCP protocol, and code intelligence engine. Adds the hypothesis trajectory engine, sandboxed compute, and science-oriented agent roles.
---
## ⚡ Quick Start
**Install**
```bash
# Option 1: grab a binary
# → https://github.com/justrach/agentlab/releases/latest
# Option 2: build from source (requires Zig 0.15.x)
git clone https://github.com/justrach/agentlab.git && cd agentlab
zig build
```
**Connect** — add to `~/.claude.json` (or Codex/Amp equivalent):
```json
{
"mcpServers": {
"agentlab": {
"command": "/path/to/agentlab",
"args": ["--mcp"],
"env": { "REPO_PATH": "/path/to/your/repo" }
}
}
}
```
Run `/mcp` to verify — 38 tools light up.
---
## 🔬 Hypothesis Engine
The core of AgentLab. Give it a rough idea, get back a structured investigation.
```
run_hypothesis("Gravitational particle creation can explain the baryon asymmetry of the universe")
```
Six phases run in sequence (phases 1–3 in parallel), each a specialized agent:
| Phase | Role | Job |
|:-----:|------|-----|
| 0 | **Formalizer** | Map informal terms → formal math. Symbol tables, SDEs, assumptions. |
| 1 | **Existence Prover** | Can this work at all? Prior evidence, theoretical bounds. |
| 2 | **Constraint Closer** | Necessary conditions, boundary cases, parameter limits. |
| 3 | **Gap Finder** | What's missing? Critical blockers vs minor uncertainties. |
| 4 | **Mechanism Designer** | Design the concrete mechanism. Components, invariants, failure modes. |
| 5 | **Deeper Connector** | Connect to broader landscape — analogies, implications, open directions. |
Each phase writes `findings.md` + `compute_*.py` scripts to its directory. Each run is timestamped and isolated — previous runs are never touched. A `trajectory.json` records timing, model, backend, and I/O sizes for every phase.
```
hypothesis_workspace/
├── run_20260307_054700/
│ ├── findings.md # final synthesis
│ ├── trajectory.json # per-phase traces
│ ├── phase0_formalizer/
│ │ ├── findings.md # symbol table, SDEs
│ │ └── compute_0.py # verification script
│ ├── phase1_existence_prover/
│ │ └── compute_0.py
│ ├── phase2_constraint_closer/
│ │ ├── compute_0.py
│ │ └── compute_1.py
│ ├── phase3_gap_finder/
│ │ ├── compute_0.py
│ │ └── compute_1.py
│ ├── phase4_mechanism_designer/
│ │ ├── compute_0.py
│ │ └── compute_1.py
│ └── phase5_deeper_connector/
│ └── compute_0.py
├── run_20260307_061508/ # next run, untouched
│ └── ...
```
When a phase produces Python scripts, AgentLab executes them in a sandbox and feeds results forward. The synthesizer gets both the math **and** the numerics.
---
## 🧪 Real Output: Dissipative Baryogenesis
This isn't a toy example. AgentLab produced a [complete investigation](hypothesis_workspace/run_20260307_054700/) of whether gravitational particle creation can explain the baryon asymmetry (η ≈ 6.1 × 10⁻¹⁰):
| Phase | What it found | Scripts |
|:-----:|--------------|---------|
| 0 | Formalized the DAF (Dissipative Axion-like Field) coupled to trace anomaly. Symbol table, risk-neutral SDEs. | [`compute_0.py`](hypothesis_workspace/run_20260307_054700/phase0_formalizer/compute_0.py) |
| 1 | Prigogine formalism gives η ~ 10⁻⁴ (overproduction) — mechanism exists but needs tuning | [`compute_0.py`](hypothesis_workspace/run_20260307_054700/phase1_existence_prover/compute_0.py) |
| 2 | QCD instanton f_B decomposition → η ~ 10⁻⁶⁹ at QCD epoch (Hubble friction kills it) | [`compute_0.py`](hypothesis_workspace/run_20260307_054700/phase2_constraint_closer/compute_0.py) [`compute_1.py`](hypothesis_workspace/run_20260307_054700/phase2_constraint_closer/compute_1.py) |
| 3 | Traced every power of H — found the Γ_EW/H gap. Goldstone sector investigated. | [`compute_0.py`](hypothesis_workspace/run_20260307_054700/phase3_gap_finder/compute_0.py) [`compute_1.py`](hypothesis_workspace/run_20260307_054700/phase3_gap_finder/compute_1.py) |
| 4 | **Electroweak epoch works.** Exact β ≈ 6 via bisection, first-principles ζ/s. 4 UV completion models verified. | [`compute_0.py`](hypothesis_workspace/run_20260307_054700/phase4_mechanism_designer/compute_0.py) [`compute_1.py`](hypothesis_workspace/run_20260307_054700/phase4_mechanism_designer/compute_1.py) |
| 5 | Proved η is y_φ-independent in adiabatic regime → universal prediction | [`compute_0.py`](hypothesis_workspace/run_20260307_054700/phase5_deeper_connector/compute_0.py) |
**Result:** η = 6.1 × 10⁻¹⁰ with natural parameters (β ≈ 6, M = 10 MeV, f_φ = 100 GeV). [Read the full paper →](hypothesis_workspace/run_20260307_054700/findings.md)
<p align="center">
<img src="hypothesis_workspace/run_20260307_054700/phase4_mechanism_designer/baryogenesis_v4_final.png" width="600" />
</p>
---
## 🔧 All 38 Tools
| Category | Tools |
|----------|-------|
| **Science** | `run_hypothesis` |
| **Agents** | `run_agent` · `run_swarm` · `run_task` · `review_fix_loop` · `run_reviewer` · `run_explorer` · `run_zig_infra` |
| **Planning** | `decompose_feature` · `get_project_state` · `get_next_task` · `prioritize_issues` |
| **Issues** | `create_issue` · `update_issue` · `close_issue` · `get_issue` · `create_issues_batch` · `close_issues_batch` · `link_issues` |
| **Git** | `create_branch` · `get_current_branch` · `commit_with_context` · `push_branch` · `recently_changed` · `git_history_for` |
| **PRs** | `create_pr` · `get_pr_status` · `list_open_prs` · `merge_pr` · `get_pr_diff` · `review_pr_impact` |
| **Code Intel** | `blast_radius` · `relevant_context` · `symbol_at` · `find_callers` · `find_callees` · `find_dependents` |
| **Config** | `set_repo` |
---
## ⚙️ Architecture
```
┌──────────────────────────────────────────────┐
│ Your AI Assistant (Claude / Codex / Amp) │
└──────────────────┬───────────────────────────┘
│ MCP (JSON-RPC 2.0, stdio)
▼
┌──────────────────────────────────────────────┐
│ AgentLab Runtime │
│ │
│ ┌──────────┐ ┌──────────┐ ┌─────────────┐ │
│ │Hypothesis│ │ Swarm │ │ Code Graph │ │
│ │ Engine │ │ Engine │ │ (PPR) │ │
│ │ 6-phase │ │ parallel │ │ blast_radius│ │
│ └────┬─────┘ └────┬─────┘ └──────┬──────┘ │
│ └─────────────┼──────────────┘ │
│ ┌──────┴──────┐ │
│ │ Agent SDK │ │
│ │ Claude/Codex│ │
│ └─────────────┘ │
│ ┌──────────────────────────────────────┐ │
│ │ GitHub · Git · File I/O · Sandbox │ │
│ └──────────────────────────────────────┘ │
└──────────────────────────────────────────────┘
```
- **Hypothesis Engine** — 6-phase trajectory. Each phase gets a specialized prompt, reads prior findings, writes `compute_*.py` scripts. Full run traced in `trajectory.json`.
- **Swarm Engine** — Parallel agent orchestration. Up to 100 workers via Zig threads.
- **Code Graph** — Personalized PageRank over your call graph. Powers blast radius, caller/callee analysis, dependency-aware prioritization.
---
## Contributing
Contributions welcome. Open an issue before large PRs.
```bash
git clone https://github.com/justrach/agentlab.git && cd agentlab
zig build test
```
## License
MIT — see [LICENSE](LICENSE)
<p align="center"><sub><a href="README-changelog.md">Changelog</a></sub></p>