Repository navigation
Agent Code Detective
Josemalyson Oliveira edited this page Jun 27, 2026
·
1 revision
The systematic methodology for reverse-engineering any AI agent open-source project.
Turns your agent into a "code detective" that can map architectures of projects like OpenHands, Aider, Cline, LangGraph, CrewAI, and more.
- Understanding a new codebase
- Documenting existing architecture
- Onboarding new team members
- Learning from open-source projects
- "Me ajuda a entender o projeto X"
- "Investigate this codebase"
- "Map the architecture of X"
- "How does this agent work?"
| Phase | Time | Description |
|---|---|---|
| 1. Territory Reconnaissance | 15 min | Read README, analyze dependencies, map folder structure |
| 2. Entry Point | 30 min | Locate execution start, classify as CLI/HTTP/SDK/Worker |
| 3. Follow the Trail | 1h | Find 6 universal components using grep patterns |
| 4. Live Surveillance | 1-2h | Debug with 5 universal breakpoints |
| 5. X-Ray Tracing | 30 min | Capture HTTP calls to LLM providers |
| 6. Validate by Modifying | 1h | Make 3+ experiments to confirm understanding |
- Understand what the project does
- Identify the tech stack
- Map the folder structure
- Read README.md and ARCHITECTURE.md (if exists)
- Analyze dependency manifests (pyproject.toml, package.json, etc.)
- Map folder structure
- Identify frameworks (langgraph, pydantic-ai, etc.)
- Find where execution starts
- Classify the application type
-
Search for entry points:
- Python:
if __name__,app.command,cli() - TypeScript:
createServer,app.listen,main() - Go:
func main() - Rust:
fn main()
- Python:
-
Classify as:
- CLI — Command-line interface
- HTTP — Web server
- SDK — Library/package
- Worker — Background process
Every AI agent has these components:
- Entry Point — Where execution starts
- Agent Loop — The main execution cycle
- LLM Client — Interface to language models
- Tool Registry — Available tools/functions
- Memory/State — Context management
- Prompt Manager — Template management
# Agent loop
grep -r "while True" --include="*.py"
grep -r "for.*in.*range" --include="*.py"
# LLM client
grep -r "openai\|anthropic\|langchain" --include="*.py"
# Tool registry
grep -r "@tool\|def.*tool\|register.*tool" --include="*.py"| BP | Location | Variables to Inspect |
|---|---|---|
| BP1 | Input entry | User message, context |
| BP2 | LLM outbound call | Prompt, model, params |
| BP3 | LLM response | Completion, tokens |
| BP4 | Tool execution | Tool name, args, result |
| BP5 | Loop stop decision | Exit condition, state |
- No tool — Send a simple question
- Single tool — Request one specific action
- Multi-tool — Request complex workflow
- Forced error — Send invalid input
- mitmproxy — HTTP proxy for capturing requests
- Langfuse — LLM observability platform
- OpenTelemetry — Distributed tracing
# mitmproxy
mitmproxy --mode reverse:http://localhost:8080
# Environment variables
export ANTHROPIC_PROXY=http://localhost:8080
export OPENAI_BASE_URL=http://localhost:8080- Add print statements — Trace execution flow
- Change a prompt — Observe behavior changes
- Add a new tool — Test extensibility
- Modify state — Test memory management
A structured docs/investigation.md dossier with:
- Identity and entry point analysis
- 6 core components
- End-to-end flow visualization
- Observed patterns
- Metrics (lines of code, dependencies, etc.)
- Fragilities and risks
- Architectural decisions
- Open questions
- Transferable learnings
- Agent-Code-Detective-Breakpoints — Detailed breakpoint guide
- Agent-Code-Detective-Debug-Configs — VSCode configurations
- Agent-Code-Detective-Dossier-Template — Report template
- Agent-Code-Detective-Tracing — Tracing setup guides
Last updated: June 2026