Debugging & Research Agents
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Debugging and Research Agents within the Continuous Claude system are specialized sub-agent configurations designed to handle complex investigative tasks that exceed simple tool calls. These agents leverage a combination of native Claude Code skills and external Model Context Protocol (MCP) scripts to explore codebases, analyze documentation, and investigate issues with high token efficiency. Their primary purpose is to provide autonomous or semi-autonomous reasoning and discovery capabilities, reducing the manual burden on the primary user session.
The agents operate by orchestrating multiple tools—such as morph-search for 20x faster codebase exploration than standard grep and nia-docs for comprehensive library documentation lookup. By utilizing the "Scripts-Based Execution" pattern, these agents achieve up to a 99.6% reduction in token consumption compared to writing custom logic from scratch for every task.
Sources: CLAUDE_ONBOARDING.md:46-59, CLAUDE.md:27-38, scripts/SCRIPTS.md:12-25
Research Capabilities and Data Flow
The Research Agent ecosystem is built around "Operational Intelligence," which allows agents to discover, read, and execute reusable capabilities. This workflow is particularly optimized for Claude Code's filesystem discovery and CLI-based execution.
Exploration Workflow
Research agents typically follow a three-step process to maximize efficiency and accuracy:
- Discovery: Listing available scripts to identify relevant tools for the research topic.
- Documentation Review: Reading script docstrings to understand CLI arguments.
- Execution: Running the chosen script via a specialized runtime harness (e.g.,
uv run python -m runtime.harness).
Sources: CLAUDE.md:44-55, scripts/SCRIPTS.md:33-40
Multi-Source Research Architecture
The system integrates various local and remote data sources to provide a unified research interface.
The Research Agent utilizes these tools to synthesize information from codebase structures, documentation, and web sources.
Sources: CLAUDE_ONBOARDING.md:65-80, CLAUDE.md:214-225, scripts/nia_docs.py:1-25
Debugging and Session Analysis
Debugging agents focus on investigating issues, detecting loops in logic, and extracting learnings from past sessions to prevent repetitive errors.
Braintrust Analysis System
A critical component of the debugging infrastructure is the braintrust_analyze.py script, which provides deep visibility into agent behavior. It allows for "Replay" of specific sessions to show the exact sequence of tool calls and LLM inputs/outputs.
| Command Option | Purpose | Use Case |
|---|---|---|
--detect-loops | Identifies repeated tool calls | Debugging infinite agent recursion |
--replay <id> | Shows full session content | Investigating specific failures |
--learn | Extracts markdown learnings | Building future context |
--review | Compares plan vs. code diff | Verifying implementation accuracy |
| Sources: scripts/braintrust_analyze.py:5-40, scripts/braintrust_analyze.py:270-300 |
Qualitative Debugging (LLM-as-Judge)
The system employs an "LLM-as-Judge" pattern for qualitative debugging. Instead of relying solely on quantitative metrics (like token counts), it uses critique-focused prompts to identify gaps in plans or implementations.
This process ensures that implementation follows the intended architectural logic and identifies "Scope Creep" or missing requirements.
Sources: scripts/braintrust_analyze.py:530-575, scripts/braintrust_analyze.py:720-750
Key Agent Tools and Skills
Agents interact with the project via defined skills and MCP scripts.
Codebase Exploration Tools
/codebase-explorer: Usesrepomixto pack codebase context into token-efficient structures, often achieving a 50% reduction in token count via XML compression.warpgrep_codebase_search: A specialized subagent (referred to as 'WarpGrep') that runs parallel grep and readfile calls to locate relevant line ranges across the codebase.
Sources: CLAUDE.md:14-20, servers/morph/README.md:33-40
Research and Documentation Tools
nia_docs.py: A comprehensive client for the Nia API, covering Oracle Research (autonomous AI research), repository indexing, and research paper (arXiv) search.firecrawl_scrape: The primary tool for single-page content extraction, featuring advanced options likemaxAgefor 500% faster cached scrapes.
Sources: scripts/nia_docs.py:45-60, servers/firecrawl/README.md:6-25
Summary
Debugging and Research Agents in Continuous Claude provide a structured, token-efficient approach to information gathering and problem-solving. By utilizing specialized MCP tools like morph for fast edits and braintrust_analyze for session post-mortems, these agents maintain high accuracy and prevent context pollution. This modular architecture allows developers to extend agent capabilities by simply adding new Python scripts or native skill definitions.