Absorb the jitter in your requirements. Spec first, code second, verify always.
jibuff is a spec-driven workflow harness for AI coding agents. Like a jitter buffer in real-time communications — which absorbs timing inconsistencies before they reach the decoder — jibuff absorbs requirement ambiguity before it reaches the AI coding agent.
AI coding agents are powerful but expensive to course-correct. Feeding an ambiguous or contradictory spec into an agent wastes compute, produces misaligned code, and shifts the debugging cost onto the developer. jibuff front-loads the hard thinking: clarify the spec, score the risk, then let the agent execute against a locked, unambiguous target.
Request → [Interview] → [Spec Lock] → [Agent Loop] → [Validation] → Artifact
↑ ↓ ↓
ambiguity score pass: mark done fail: requeue
risk gate (rtc) fail: requeue write failure report
- Interview — Multi-round clarification with hybrid ambiguity scoring (keyword coverage + contradiction detection + dimensional clarity)
- Spec Lock —
tasks.mdis generated and frozen; no scope changes mid-loop - Agent Loop —
LoopControllerfeeds tasks one at a time to a freshclaudesubprocess; no session carryover - Validation — Configurable validator stack runs after each task: lint, types, tests, security, and (in
rtcmode) device, network, fallback, firewall - Artifact — Pass/fail artifacts written to
storage/; context hygiene enforced — each task sees only its own history
quick |
rtc |
|
|---|---|---|
| Ambiguity threshold | ≤ 0.25 | ≤ 0.15 |
| Risk gate | none | < 0.4 |
| Max interview rounds | 5 | 8 |
| Validator stack | lint, types, tests, security | + device, network, fallback, firewall |
| Target use case | General features, scripts, APIs | WebRTC, media, real-time protocols |
One-liner:
curl -fsSL https://raw.githubusercontent.com/RohSungKyun/jibuff/main/scripts/install.sh | bashWith extras:
# RTC validators + MCP server
curl -fsSL https://raw.githubusercontent.com/RohSungKyun/jibuff/main/scripts/install.sh | bash -s -- --extras rtc,mcp
# Everything
curl -fsSL https://raw.githubusercontent.com/RohSungKyun/jibuff/main/scripts/install.sh | bash -s -- --extras allpip:
pip install jibuff # core
pip install "jibuff[mcp]" # + MCP server
pip install "jibuff[rtc]" # + RTC validators (Playwright)
pip install "jibuff[all]" # everythingRequires Python ≥ 3.12 and a coding-agent CLI on PATH — claude (npm install -g @anthropic-ai/claude-code) or codex. jibuff auto-detects in that order.
Both jibuff and the short alias jb are available after installation.
# Step 1: clarify requirements → generates spec/tasks.md
jb interview "Add WebRTC screen sharing to the dashboard"
jb interview "Add WebRTC screen sharing" --mode rtc # RTC mode
# Step 2: run the agent loop against spec/tasks.md
jb run
jb run --mode rtc
jb run --no-commit # skip auto git commit per task
jb run --agent "codex exec" # override agent CLI for this run
JIBUFF_AGENT_CMD="codex exec" jb run # or set globally via env var
# Check current loop state
jb status
# Diagnose and inspect runtime state
jb doctor
jb inspect
jb recover
jb recover --stale-after-minutes 10
jb recover --force
jb cleanup
# Install a thin Codex skill wrapper for in-session discovery
jb setup-skill
# (jibuff is also available as a full-name alias)
jibuff --helpRegister jibuff as an MCP server inside Claude Code:
{
"mcpServers": {
"jibuff": {
"command": "jibuff",
"args": ["mcp", "serve"]
}
}
}Or with uvx:
{
"mcpServers": {
"jibuff": {
"command": "uvx",
"args": ["--from", "jibuff", "jibuff", "mcp", "serve"]
}
}
}This exposes four tools to Claude Code:
| Tool | Description |
|---|---|
jibuff_interview |
Start or continue an interview session |
jibuff_run |
Execute the loop for a spec |
jibuff_status |
Query current loop state |
jibuff_cancel |
Halt a running loop |
your-project/
├── spec/
│ └── tasks.md # Generated by interview; locked before loop starts
└── storage/
├── state.json # Loop state (status, iteration, current task)
├── task_status.json # Per-task done/todo/blocked/in_progress
├── issues/ # Open issues by task ID
└── last_failure.md # Last agent failure report
Task status entries also carry revision, claimed_by, claimed_at, and
claim_token metadata as a compatibility mirror. Runtime source-of-truth lives
under .jibuff/runs/<run_id>/, with task and worker state split into separate
JSON files so future parallel workers do not contend on a single status file.
These files are runtime artifacts. They are useful while a local run is active, but they usually should not be committed to your application repository:
.jibuff/
storage/state.json
storage/task_status.json
storage/last_failure.md
storage/progress.md
storage/open_issues.json
storage/decision_log.md
storage/traces/
storage/issues/your-project/
└── .jibuff/
└── runs/
├── active.json
└── <run_id>/
├── manifest.json
├── tasks/
│ └── P0-01.json
├── workers/
│ └── worker-1.json
├── events.jsonl
└── locks/
Each in-progress task carries claimed_at and heartbeat_at. jb recover
requeues only stale tasks by default; recent heartbeats are skipped unless
--force is passed.
MCP interview sessions are stored under:
your-project/
└── .jibuff/
└── mcp/
└── interviews/
├── <session_id>.md
└── <session_id>.lock
jb inspect shows these sessions. jb cleanup removes expired sessions and
orphan locks. jb recover requeues stale in-progress tasks after an interrupted
run.
tasks.md uses a simple marker syntax:
- [ ] P0-01: Scaffold the project structure
- [x] P0-02: Add pyproject.toml
- [~] P1-01: Implement interview engine # in progress
- [!] P1-02: Wire CLI to interview engine # blockedjibuff uses a three-stage hybrid scorer that balances cost and accuracy:
| Stage | Method | Cost |
|---|---|---|
| 1. Keyword coverage | Regex scan for mandatory dimension keywords | Free |
| 2. Contradiction detection | LLM (Haiku) — only if Stage 1 passes | Low |
| 3. Dimensional clarity | LLM (Haiku) — only when Stage 1+2 pass | Low |
Mandatory dimensions (all modes): target users, success criteria, scope boundary, tech stack, data model
RTC extra dimensions: latency budget, browser targets, signaling protocol, fallback behavior
┌─────────────────────────────────────────────────┐
│ CLI / MCP │
│ jibuff run | jibuff interview │
└──────────────────┬──────────────────────────────┘
│
┌──────────────────▼──────────────────────────────┐
│ Orchestrator │
│ LoopController · TaskQueue · AgentRunner │
└──────────────────┬──────────────────────────────┘
│
┌────────────┴─────────────┐
│ │
┌─────▼──────┐ ┌────────▼───────┐
│ Interview │ │ Validators │
│ Engine │ │ lint·type·test │
│ Ambiguity │ │ security·rtc │
│ Risk Index │ └────────┬───────┘
└─────────────┘ │
┌────────▼───────┐
│ Storage │
│ ArtifactStore │
└────────────────┘
git clone https://github.com/RohSungKyun/jibuff
cd jibuff
pip install -e ".[all]"
# Run tests
pytest
# Lint + format
ruff check .
black .
# Type check
mypy .
# Security audit
bandit -r orchestrator interview validators storage mcp
pip-auditTest coverage is enforced at 80% minimum (currently ~90%).
MIT