Skip to content
/
Tier B A3 MCP-anchored

Deebo

deebo · snagasuri/deebo-prototype · ★ 0 · last commit 2026-05-25

Primitive shape 6 total
Subagents 2 MCP tools 4
00

Summary

Deebo — Summary

An autonomous debugging MCP server that speeds up time-to-resolution by introducing multi-threaded debugging into AI coding workflows. When a main coding agent hits a tough bug, it delegates the investigation to Deebo, which spawns a "mother agent" and N "scenario agents" running in parallel git branches — each testing a different hypothesis about the bug's cause.

The architecture is explicitly inspired by OODA loops: mother agent Observes (sets up tools), Orients (generates hypotheses), Decides (spawns scenario agents), Acts (waits for reports). Each scenario agent runs in its own git branch, tests its hypothesis against the actual codebase, and reports back. The mother agent synthesizes reports and returns a validated solution.

Deebo is implemented as a TypeScript Node.js MCP server. It requires OpenRouter (or compatible API) and is configured with separate model assignments for the mother agent (e.g., claude-3.5-sonnet) and scenario agents (e.g., deepseek-chat). The original repository (snagasuri/deebo-prototype) is no longer accessible; the canonical accessible fork is MjrTom/deebo-prototype. The README notes: "Deebo is not maintained actively. Install at your own risk." Despite this, the concept spawned a successor product (bojack.ai).

Compared to seeds: closest to claude-flow (Archetype 3 — MCP server for multi-agent orchestration with parallel agents) but claude-flow does task decomposition while Deebo does hypothesis-driven debugging with competing scenario agents. Deebo is the only framework in this corpus explicitly designed for the "debugging delegation" use case with parallel hypothesis testing in isolated git branches.

01

Overview

Deebo — Overview

Origin

Created by Sashank Nagaraju (snagasuri on GitHub), published 2025. Original repo now deleted/private; the accessible fork maintained by MjrTom. Featured in PulseMCP, @cline on X, and the official MCP directory. The README notes the project is not actively maintained; a successor commercial product (bojack.ai) has been launched.

Philosophy

"Deebo is an agentic debugging copilot for your AI coding agent that speeds up time-to-resolution by 10x. If your main coding agent is like a single-threaded process, Deebo introduces multi-threadedness to your development workflow."

The framework explicitly frames debugging as a parallelizable multi-hypothesis problem:

  1. One bug → multiple competing hypotheses
  2. Each hypothesis → one scenario agent in an isolated git branch
  3. All scenario agents run simultaneously
  4. Mother agent synthesizes results and returns the validated solution

OODA Loop Architecture

Mother agent follows the OODA loop (Observe, Orient, Decide, Act):

  • Observe: Set up git and filesystem MCP tools
  • Orient: Generate diverse hypotheses about the bug
  • Decide: Spawn scenario agents for each hypothesis
  • Act: Wait for reports, synthesize solution

Multi-Model Strategy

Two distinct model roles:

  • MOTHER_HOST / MOTHER_MODEL: Orchestrates the investigation (typically a larger model)
  • SCENARIO_HOST / SCENARIO_MODEL: Tests individual hypotheses (can be a smaller/cheaper model)

Both support any OpenAI-compatible API, Anthropic, Gemini, and OpenRouter.

Status

Dormant (README: "Install at your own risk"). Successor: bojack.ai.

02

Architecture

Deebo — Architecture

Distribution

mcp-server — npm package (npx deebo-setup@latest for install). Installed to ~/.deebo/.

Install

# Quick install
npx deebo-setup@latest

# Manual config (example)
{
  "servers": {
    "deebo": {
      "command": "node",
      "args": ["--experimental-specifier-resolution=node", "--experimental-modules",
               "--max-old-space-size=4096", "/Users/<name>/.deebo/build/index.js"],
      "env": {
        "USE_MEMORY_BANK": "true",
        "MOTHER_HOST": "openrouter",
        "MOTHER_MODEL": "anthropic/claude-3.5-sonnet",
        "SCENARIO_HOST": "openrouter",
        "SCENARIO_MODEL": "deepseek/deepseek-chat",
        "OPENROUTER_API_KEY": "your-key"
      }
    }
  }
}

Source Directory Tree

deebo-prototype/
├── src/
│   ├── index.ts            # MCP server entry point (4 MCP tools)
│   ├── mother-agent.ts     # OODA loop orchestrator
│   ├── scenario-agent.ts   # Hypothesis tester (per-branch subprocess)
│   └── util/
│       ├── agent-utils.ts  # LLM call abstraction + system prompts
│       ├── branch-manager.ts  # git branch creation/cleanup
│       ├── logger.ts          # Structured logging
│       ├── membank.ts         # Memory bank read/write
│       ├── mcp.ts             # MCP client for tools
│       ├── observations.ts    # Inter-agent observation passing
│       ├── reports.ts         # Scenario report writing
│       └── sanitize.ts        # Project ID hashing
├── packages/
│   ├── deebo-setup/        # npx install helper
│   └── deebo-doctor/       # Diagnostic utility
├── memory-bank/            # Session logs per project
├── config/                 # LLM provider configs
└── build/                  # Compiled output

Runtime Dependencies

  • Node.js (--experimental-modules)
  • npx + uvx on PATH (for spawning git and filesystem MCP tools)
  • OpenRouter API key (or Anthropic/OpenAI/Gemini equivalents)
  • Git (for branch management)

Data Paths

~/.deebo/
├── build/index.js          # Compiled server
├── memory-bank/
│   └── <project-hash>/
│       └── sessions/
│           └── <session-id>/
│               └── logs/   # Agent activity logs
03

Components

Deebo — Components

MCP Tools (4)

Tool Description
start Begin an autonomous debugging session. Launches mother agent which generates hypotheses and spawns scenario agents in parallel git branches.
check Retrieve the current status of a debugging session — in-progress pulse or completed solution with code changes.
cancel Terminate all processes related to a debugging session (mother + all scenario agents).
add_observation Add an external observation to an agent in the session (default: mother). Allows human/tool insights to be incorporated mid-investigation.

Internal Agents (code classes)

Agent Definition Role
Mother Agent src/mother-agent.ts OODA loop orchestrator; generates hypotheses; spawns scenario agents; synthesizes reports
Scenario Agent src/scenario-agent.ts Per-hypothesis tester; runs in isolated git branch; calls git and filesystem MCP tools; writes report

Guide Server (optional)

A separate deebo-guide MCP server that provides help documentation even if the main Deebo installation fails. Listed in the manual config example.

Memory Bank

Session logs at ~/.deebo/memory-bank/<project-hash>/sessions/<session-id>/logs/ — structured log files per agent, readable by Claude Code to track session progress.

Util Layer

8 utility modules: LLM call abstraction, git branch management, logging, memory bank I/O, MCP tool connection, inter-agent observation passing, report writing, and project ID hashing.

Skills (0)

None.

Hooks (0)

None.

CLI (0)

No user-facing CLI beyond npx deebo-setup.

05

Prompts

Deebo — Prompts

MCP Tool Description: start (verbatim from index.ts)

server.tool(
  "start",
  "Begins an autonomous debugging session that investigates software bugs through
   multiple competing hypotheses. This tool launches a mother agent that analyzes
   errors, generates diverse hypotheses about potential causes, and spawns isolated
   scenario agents to test each hypothesis in separate git branches. The mother agent
   coordinates the investigation, evaluates scenario reports, and synthesizes a
   validated solution when sufficient evidence is found.",
  { ... }
)

MCP Tool Description: check (verbatim)

server.tool(
  "check",
  "Retrieves the current status of a debugging session, providing a detailed pulse
   report. For in-progress sessions, the pulse includes the mother agent's current
   stage in the OODA loop, running scenario agents with their hypotheses, and any
   preliminary findings. For completed sessions, the pulse contains the final solution
   with a comprehensive explanation, relevant code changes, and outcome summaries from
   all scenario agents that contributed to the solution. Use this tool to monitor
   ongoing progress or retrieve the final validated fix. In a short paragraph, Include
   the Mother agents status only if it's crashed or failing otherwise just skip over
   it and use the last activity and the last log message to summarize in one sentence
   what the mother agent did. Then describe scenario agents activity and hypotheses
   briefly",
  { ... }
)

Note: The check tool description includes formatting instructions embedded in the description field — telling Claude how to format the response. This is an unusual technique of embedding response formatting requirements in the tool description itself.

System Prompts (from agent-utils.ts)

Internal getMotherAgentPrompt() and getScenarioAgentPrompt() functions generate system prompts for each agent role. These embed the OODA loop instructions and hypothesis-testing protocol.

Prompting Technique Classification

  • Embedded response formatting: check tool description tells Claude how to format the output (novel technique)
  • Role separation via env vars: MOTHER_MODEL vs SCENARIO_MODEL configures different LLMs per role
  • Observation injection: add_observation allows humans to inject mid-session guidance into the agent's context
09

Uniqueness

Deebo — Uniqueness

differs_from_seeds

Closest seed is claude-flow (Archetype 3 — MCP server with parallel multi-agent coordination). But claude-flow's parallel agents do task decomposition (each agent handles a different task slice) while Deebo's parallel agents do hypothesis testing (each agent tests a different explanation for the same bug). This is a fundamentally different coordination model: claude-flow is additive (agents build different parts), Deebo is competitive (agents test competing theories). The closest methodology is Adversarial Subagent Review from superpowers, but superpowers uses adversarial review for code quality, not for debugging hypothesis testing.

Positioning

Deebo is the only framework in the corpus explicitly designed for the "debugging delegation" use case. It treats debugging as a scientific investigation with competing hypotheses rather than a linear troubleshooting sequence.

Distinctive Opinion

"If your main coding agent is like a single-threaded process, Deebo introduces multi-threadedness to your development workflow."

The framework posits that debugging is inherently parallelizable via hypothesis generation — and that the overhead of spinning up multiple agents is worth it for "10x speedup."

Observable Failure Modes

  1. Repository not maintained: Original snagasuri/deebo-prototype is 404; canonical fork is MjrTom. README says "install at your own risk."
  2. API cost accumulation: Mother + N scenario agents × 60/15 minute timeouts = significant API costs
  3. Git branch proliferation: Each scenario creates a git branch; failed scenarios may leave orphaned branches
  4. No real-time streaming: check returns a snapshot; no live log streaming
  5. npx path resolution bugs: winRoamingBin() and platform-specific path finding has documented edge cases for nvm users
  6. Memory bank feature requires env var: USE_MEMORY_BANK=true is opt-in; without it, no cross-session learning

What Makes It Novel vs. the 11 Seeds

  • Only framework using git-branch isolation per agent (not worktree, not container, but branch)
  • Only framework with hypothesis-driven parallel agent spawning (competitive rather than additive)
  • Only framework with explicit multi-model role assignment via env vars (MOTHER_MODEL ≠ SCENARIO_MODEL)
  • Only framework whose session logs are designed to be read by an AI agent for status checking
  • Only framework where the AI spawns child processes that are themselves LLM agents
04

Workflow

Deebo — Workflow

Debugging Delegation Flow

User's main coding agent hits a bug
  ↓
User: "Delegate this to Deebo: error [msg] in repo [path]"
  ↓
Agent calls: start(error="...", context="...", filePath="...", repoPath="...")
  ↓
Deebo returns: session_id="session-1745..."
  ↓
~30 seconds later...
  ↓
Agent calls: check(session_id="session-1745...")
  ↓
Deebo returns: session pulse (in-progress) or final solution (completed)

Mother Agent OODA Loop (from mother-agent.ts comments)

OBSERVE: Setup git and filesystem MCP tools, read LLM config
ORIENT: Generate diverse hypotheses about the bug cause
DECIDE: Spawn scenario agents (one per hypothesis) in separate git branches
ACT: Wait for scenario reports, synthesize validated solution

Scenario Agent Lifecycle

Mother spawns scenario-{n} with: session, error, hypothesis, repoPath, branch
  ↓
scenario-{n}:
  1. Connect to git + filesystem MCP tools
  2. Investigate hypothesis in dedicated git branch
  3. Make code changes to test hypothesis
  4. Run tests/commands to validate
  5. Write report (finding/conclusion)
  6. Report back to mother agent

Phase/Artifact Table

Phase Artifact
start session-id, mother agent process
hypothesis generation hypotheses list (internal to mother)
scenario spawn N git branches (scenario-{n}-{id})
investigation code changes in branches, agent logs
synthesis final solution report
cancel cleaned up processes and branches

Approval Gates

One: user can add_observation mid-session to redirect the investigation (e.g., "that warning is a red herring").

Timeouts

  • Mother agent: 60 minutes maximum runtime
  • Scenario agents: 15 minutes maximum runtime
06

Memory Context

Deebo — Memory & Context

Session Logs (Memory Bank)

Each debugging session produces structured logs:

~/.deebo/memory-bank/<project-hash>/sessions/<session-id>/logs/

Log files per agent (mother + each scenario). Readable by the calling agent to track progress without calling the check tool.

Memory Bank (USE_MEMORY_BANK=true)

When USE_MEMORY_BANK=true is set, the mother agent can read/write to the memory bank. The updateMemoryBank() function in util/membank.ts writes summaries of completed sessions. This enables the mother agent to learn from past debugging sessions on the same project.

Cross-Session Handoff

Yes. The memory bank persists between sessions. A future session can reference past debugging logs for the same project (by project hash).

Inter-Agent Communication

Observations: the add_observation tool and observations.ts utility allow the calling agent or human to inject mid-session context. Observations are stored as files and read by agents in their next context cycle.

Reports: scenario agents write completion reports via util/reports.ts. Mother agent reads these to synthesize the final solution.

Context Window Management

Each agent (mother + scenarios) runs independently with its own context window. The scenario agent has a 15-minute timeout; the mother agent has 60 minutes. When a scenario agent's context fills up, it writes a report and exits gracefully.

State Files

  • ~/.deebo/memory-bank/<project-hash>/ — session logs, memory bank summaries
  • Temporary git branches for each scenario (cleaned up on session end)
07

Orchestration

Deebo — Orchestration

Multi-Agent Pattern

Parallel fan-out — mother agent generates N hypotheses and spawns N scenario agents, all running simultaneously. Mother waits for reports and synthesizes.

Isolation Mechanism

git-branch — each scenario agent runs in its own git branch created from HEAD. Branch naming: scenario-{n}-{session-id}. Branches are cleaned up when the session ends.

Execution Mode

one-shot per debugging session. The session runs to completion (or timeout), not continuously.

Multi-Model Configuration

Yes — the primary multi-model framework in this batch:

Role Config Var Example Model
Mother agent (orchestrator) MOTHER_HOST + MOTHER_MODEL openrouter/anthropic/claude-3.5-sonnet
Scenario agent (investigator) SCENARIO_HOST + SCENARIO_MODEL openrouter/deepseek/deepseek-chat

Supported providers: OpenRouter, Anthropic, OpenAI, Gemini, any OpenAI-compatible API.

Agent Spawning

Scenario agents are spawned as child processes: spawn(process.execPath, ['--experimental-modules', ...scenario-agent.js..., '--session', id, '--hypothesis', h, '--branch', b, ...])

Each spawned process is independent (separate process, separate LLM client, separate git branch).

Consensus Mechanism

None — the mother agent makes the final decision by evaluating scenario reports. It's a synthesis model, not consensus.

Max Concurrent Scenario Agents

Determined by the number of hypotheses generated. No hard cap in the code; constrained by available API rate limits and system resources.

Prompt Chaining

Yes — mother agent reads scenario reports; scenario conclusions become part of mother's synthesis prompt. Explicit multi-step chaining.

Crash Recovery

Partial — process tracking allows cancel to kill stray processes. Scenario agent timeouts (15 min) prevent indefinite hanging. The deebo-doctor package provides diagnostics.

08

Ui Cli Surface

Deebo — UI & CLI Surface

Dedicated CLI Binary

No user-facing binary. The MCP server is invoked via Node.js by the MCP client.

Install helper: npx deebo-setup@latest — sets up the ~/.deebo directory and generates config instructions.

deebo-doctor Package

Diagnostic utility for troubleshooting Deebo installation. Available in the packages/deebo-doctor/ directory.

deebo-guide Server

A separate lightweight MCP server that provides help documentation even if the main Deebo installation fails. Useful for troubleshooting.

Local Web Dashboard

None.

Observability

  • Structured logs per session at ~/.deebo/memory-bank/<project-hash>/sessions/<session-id>/logs/
  • Log files are in a format readable by Claude Code: "When asked to check debug session progress, look in: ~/.deebo/memory-bank/[project-hash]/sessions/[session-id]/logs/"
  • This is a unique pattern: the session logs are designed to be consumed by an AI agent, not just human developers

Cross-Tool Portability

Medium — designed primarily for Claude Code but documented to work with Cline (mentioned in social media coverage). Any MCP client that supports the 4 Deebo tools can use it.

Related frameworks

same archetype · same primary tool · same memory type

Taskmaster AI ★ 27k
A3 MCP-anchored

Converts a PRD into a dependency-ordered JSON task graph that AI coding agents execute one task at a time, eliminating context…

ccmemory ★ 1
A3 MCP-anchored

Accumulates decisions, corrections, and failed approaches from Claude Code sessions into a queryable Neo4j graph so each new…

Pimzino spec-workflow-mcp ★ 4.2k
A3 MCP-anchored

MCP server providing spec-driven development workflow with dashboard-backed approval gates, implementation logging, and VSCode…

MCP Shrimp Task Manager ★ 2.1k
A3 MCP-anchored

Convert natural language requests into structured AI development tasks with chain-of-thought enforcement, reflection gates, and…

Bernstein ★ 460
A3 MCP-anchored

Govern parallel CLI coding agents with a deterministic Python scheduler, HMAC-chained audit trail, and compliance-ready signed…

LeanSpec ★ 252
A3 MCP-anchored

Provides a unified spec CLI and MCP server over any existing spec backend (markdown, GitHub Issues, ADO), making spec-driven…