{"id":31273610,"url":"https://github.com/schickling/dilagent","last_synced_at":"2026-01-18T04:15:07.951Z","repository":{"id":313341861,"uuid":"1050989628","full_name":"schickling/dilagent","owner":"schickling","description":"\"Deep research for bugs\" – Agentic root cause analysis through hypothesis-driven debugging","archived":false,"fork":false,"pushed_at":"2025-09-10T08:20:57.000Z","size":690,"stargazers_count":91,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-10T13:14:23.476Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/schickling.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-05T09:09:38.000Z","updated_at":"2025-10-02T08:04:38.000Z","dependencies_parsed_at":"2025-09-07T11:33:52.280Z","dependency_job_id":null,"html_url":"https://github.com/schickling/dilagent","commit_stats":null,"previous_names":["schickling/deebug","schickling/dilagent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/schickling/dilagent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schickling%2Fdilagent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schickling%2Fdilagent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schickling%2Fdilagent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schickling%2Fdilagent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/schickling","download_url":"https://codeload.github.com/schickling/dilagent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schickling%2Fdilagent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28529467,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-23T22:01:55.366Z","updated_at":"2026-01-18T04:15:07.934Z","avatar_url":"https://github.com/schickling.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","App"],"sub_categories":[],"readme":"\u003cimg src=\"https://gitbucket.schickling.dev/api/get/32330263261d8466bc8146badc9dabbcdbf3425a046486097f62f47c10b9cf96\" alt=\"\" height=\"200\"/\u003e\n\n# dilagent 🔍\n\n**Agentic root cause analysis through hypothesis-driven debugging**\n\ndilagent automates the tedious process of reproducing, diagnosing, and fixing bugs through systematic hypothesis testing and experimentation. It combines LLM agents with structured scientific methodology to identify root causes and validate fixes.\n\n## When to Use dilagent\n\n**Ideal for:**\n- Complex, hard-to-reproduce bugs (race conditions, timing issues)\n- Performance regressions without obvious cause\n- Issues that occur only in specific environments\n- Bugs with multiple potential root causes\n- Intermittent or flaky test failures\n\n**Not suitable for:**\n- Simple syntax errors or compilation issues\n- Obvious logic errors that are easily spotted\n- Issues with clear error messages pointing to the problem\n\n## How It Works\n\ndilagent follows a structured, multi-stage approach to debugging:\n\n### 1. 🔬 Reproduction Stage\nFirst, dilagent attempts to reproduce the issue:\n- Creates minimal reproducible test cases (`repro.ts`)\n- Measures timing characteristics (performance, timeouts, race conditions)\n- Documents setup requirements\n- Asks clarifying questions when needed\n\n### 2. 🧠 Hypothesis Generation  \nBased on successful reproduction, dilagent generates targeted hypotheses:\n- Analyzes reproduction data and codebase context\n- Creates multiple hypotheses (H001, H002, H003...)\n- Tailors hypotheses to the type of issue (performance, concurrency, logic)\n- Outputs structured `hypotheses.json` for tracking\n\n### 3. 🧪 Hypothesis Testing\nEach hypothesis is tested in parallel:\n- Independent testing in isolated worktrees\n- Each hypothesis can result in:\n  - ✅ **Proven**: Root cause identified\n  - ❌ **Disproven**: Not the issue, move on\n  - ❓ **Inconclusive**: Requires additional data\n- Counter-experiments validate findings\n\n### 4. 💬 Interactive Exploration (Optional)\nFor complex issues requiring human insight:\n- REPL-based interactive debugging session\n- Agent-assisted exploration with full context\n- Direct manipulation and testing\n\nThe process continues iteratively until the root cause is found and validated.\n\n## System Architecture\n\n### Overall Manager Flow\n![System Overview](./diagrams/manager-flow.svg)\n\n### Hypothesis Testing Loop\n![Hypothesis Loop](./diagrams/hypothesis-loop.svg)\n\n## Key Features\n\n- **Automated Reproduction**: Generates minimal test cases from bug reports\n- **Parallel Hypothesis Testing**: Tests multiple theories simultaneously in isolated environments\n- **Counter-Experiment Validation**: Prevents false positives through negative testing\n- **Interactive Fallback**: REPL mode for complex cases requiring human expertise\n- **Evidence-Based**: Every conclusion backed by reproducible experiments\n- **MCP Integration**: Leverages Model Context Protocol for tool orchestration\n\n## Workflow Stages \u0026 Key Files\n\n### Stage 0: Setup\n```bash\ndilagent manager setup --working-directory ./debug-session --context-directory ./my-project\n```\n- Creates `.dilagent/` directory structure\n- Generates `context.md` with codebase information and issue description\n\n### Stage 1: Reproduce\n```bash\ndilagent manager repro --working-directory ./debug-session --llm claude\n```\n- Creates `reproduction.md` with steps to reproduce the issue\n- Generates diagnostic information and error details\n\n### Stage 2: Generate Hypotheses\n```bash\ndilagent manager generate-hypotheses --working-directory ./debug-session --hypothesis-count 3 --llm claude\n```\n- Creates numbered hypothesis directories: `H001-config-issue/`, `H002-race-condition/`, etc.\n- Each contains:\n  - `hypothesis.md` - The specific theory about the bug\n  - `instructions.md` - Steps to test the hypothesis\n\n### Stage 3: Test Hypotheses\n```bash\ndilagent manager run-hypotheses --working-directory ./debug-session --llm claude\n```\n- Creates git worktrees for parallel testing (e.g., `worktree-H001-config-issue/`)\n- AI agents test each hypothesis independently\n- Updates `report.md` in each hypothesis directory with findings\n- Logs stored in `.dilagent/H{NNN}-{slug}/hypothesis.log`\n\n![](https://share.cleanshot.com/Khr4vWlL+)\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eExample report.md output\u003c/strong\u003e (click to expand)\u003c/summary\u003e\n\n```markdown\n# Hypothesis H003: Race Condition in Connection Pool\n\n## Status: ✅ PROVEN\n\n## Initial Analysis\nThe intermittent timeout errors in production suggested a potential race condition\nin the database connection pool management. The error pattern showed:\n- Errors occur only under high concurrent load (\u003e100 req/s)  \n- Error rate increases exponentially with load\n- Database logs show connection pool exhaustion messages\n- Issue started appearing after the connection pooling refactor in commit abc123\n\n## Investigation Steps\n\n### Step 1: Reproduce the Issue\nCreated load test script that successfully reproduced the issue:\n```bash\n# Load test that triggers the race condition\nab -n 10000 -c 50 http://localhost:3000/api/users/search\n# Result: 3.2% failure rate with \"connection pool timeout\" errors\n```\n\n### Step 2: Code Analysis\nIdentified suspicious code in `src/db/pool.ts:42-58`:\n```typescript\n// PROBLEMATIC: Race condition between check and increment\nif (this.activeConnections \u003c this.maxConnections) {\n  // Gap here - another request could increment activeConnections\n  this.activeConnections++;\n  return this.createConnection();\n}\n```\n\n### Step 3: Root Cause Identification\nThe race condition occurs when multiple requests simultaneously:\n1. Check `activeConnections \u003c maxConnections` (both see same value)\n2. Both increment `activeConnections` \n3. Both attempt to create connections\n4. Total connections exceed `maxConnections`\n5. Database rejects excess connections\n6. Pool state becomes inconsistent\n\n## Fix Applied\nImplemented atomic operation using mutex lock:\n```typescript\n// FIXED: Atomic check-and-increment\nasync acquireConnection(): Promise\u003cConnection\u003e {\n  return this.mutex.acquire(async () =\u003e {\n    if (this.activeConnections \u003e= this.maxConnections) {\n      throw new PoolExhaustedError();\n    }\n    this.activeConnections++;\n    return this.createConnection();\n  });\n}\n```\n\n## Validation Results\n\n### Load Testing\n- ✅ 10,000 requests at 50 concurrent: 0% failure rate\n- ✅ 50,000 requests at 200 concurrent: 0% failure rate  \n- ✅ Connection count never exceeds maxConnections under load\n\n### Code Review\n- ✅ All database operations now use atomic operations\n- ✅ Added connection pool metrics and monitoring\n- ✅ Updated connection pool tests to include concurrency scenarios\n\n### Counter-Experiments\n- ✅ Reverting to old code: Issue reproduces immediately\n- ✅ Artificially increasing load beyond capacity: Proper error handling\n- ✅ Simulating connection failures: Pool recovers correctly\n\n## Performance Impact\n- No measurable latency increase (\u003c1ms)\n- Memory usage unchanged  \n- CPU overhead negligible\n\n## Additional Observations\n- This pattern exists in 3 other services using the same pooling library\n- Similar race conditions found in Redis connection pool\n- Recommended: Audit all resource pooling implementations company-wide\n\n## Files Modified\n- `src/db/pool.ts` - Fixed race condition\n- `tests/db/pool.test.ts` - Added concurrency tests\n- `package.json` - Added async-mutex dependency\n```\n\u003c/details\u003e\n\n### Stage 4: Summary\n```bash\ndilagent manager summary --working-directory ./debug-session\n```\n- Aggregates all hypothesis reports\n- Generates final summary with likely root causes and fixes\n\n## Quick Start\n\n```bash\n# Install\nnpm install -g dilagent\n\n# Run the complete workflow in one command\ndilagent manager all \\\n  --context-directory ./my-project \\\n  --working-directory ./debug-session \\\n  --hypothesis-count 3 \\\n  --llm claude\n\n# Key options:\n# --llm claude|codex - Choose AI model (Claude recommended)\n# --working-directory - Where dilagent stores its files\n# --context-directory - The codebase to debug\n# --hypothesis-count - Number of hypotheses to generate (default: 3)\n# --flaky - Use this flag for intermittent/flaky issues\n# --repl - Start interactive mode for complex debugging\n```\n\n## Troubleshooting\n\n**Issue: Reproduction fails**\n- Ensure the bug description is clear and specific\n- Check that all required dependencies are installed\n- Verify the issue occurs in the provided codebase\n\n**Issue: All hypotheses are inconclusive**\n- Try increasing `--hypothesis-count` to generate more hypotheses\n- Add more context to `context.md` about recent changes\n- Use `--repl` mode for manual exploration\n\n**Issue: Worktree creation fails**\n- Ensure you're in a git repository\n- Check that git worktree is supported (Git 2.5+)\n- Verify sufficient disk space for multiple worktrees\n\n## Configuration\n\n**Environment Variables:**\n- `DILAGENT_CLI_PATH` - Automatically set to CLI location for MCP proxy\n\n**LLM Tools:**\n- Requires either `claude` or `codex` command in your PATH\n- Claude recommended for best results\n- Configure your API keys according to your LLM tool's documentation\n\n**Working Directory Best Practices:**\n- Use a dedicated directory (e.g., `./debug-sessions/issue-123/`)\n- Keep separate from your main codebase\n- Clean up old sessions periodically to save disk space\n\n## Requirements\n\n- Bun 1.2+\n- Git (for worktree isolation)\n- Local LLM tool (`claude` or `codex` command available in PATH)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschickling%2Fdilagent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fschickling%2Fdilagent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschickling%2Fdilagent/lists"}