| name | IDA Swarm Technical Reference |
| description | Technical reference for using IDA Swarm MCP tools. Covers system constraints, architecture, TRUE CONTEXT principle, result interpretation, and debugging. Use when analyzing binaries via IDA Swarm or troubleshooting sessions. |
IDA Swarm Technical Reference
Critical Constraints
ONE pending message per session
- Cannot send second message while first is processing
- Error: "session is still processing previous message"
- Use
get_session_messages() to poll or wait_for_response() to block
Sessions are deterministic
- session_id = "session_" + SHA256(binary_path)[:16]
- Same binary always gets same session_id
- Prevents duplicate sessions
- Must close existing session before creating new one for same binary
Results are in response text
start_analysis_session() and send_message() return synthesized findings- Orchestrator collects all agent work and returns coherent response
extract_results.sh is DEBUG ONLY
- Creates HUGE raw dump of all agent data
- Only use when debugging "why did orchestrator conclude X?"
- Not part of normal workflow
- Normal results come from response text
TRUE CONTEXT Principle
Why This Matters
Orchestrator spawns specialized agents based on task description. Task quality determines:
- What types of agents spawn (network analysis? crypto? vulnerability research?)
- How agents prioritize work
- Analysis depth
- Whether findings meet actual needs
Deriving Effective Task Descriptions
Reason through what orchestrator needs to understand:
1. What is the actual objective?
- Not "analyze network code" → WHY: Extracting C2? Understanding protocol? Finding vulnerabilities?
- Objective determines agent specialization
2. What form should results take?
- Not "provide analysis" → Addresses with annotations? IOC list? Pseudocode? Detection signatures?
- Output format affects what agents extract
3. What would make results unusable?
- Missing function addresses? No proof? Incomplete spec?
- Understanding failure modes clarifies success criteria
Cognitive Process
Before sending task:
- If agents only knew what I've written, could they derive what's actually needed?
- What decisions will agents make based on this description?
- Am I describing surface task ("find X") or underlying goal ("because I need Y")?
Example reasoning:
"Find network functions" → Agents don't know:
- WHY needed (IOC extraction vs protocol RE require different approaches)
- Platform specifics (WinSock vs POSIX)
- What constitutes completeness
Derive:
- WHY: C2 infrastructure for threat intel → Agents prioritize: IOCs, destinations, protocol patterns, evasion
- CONTEXT: Windows PE, APT, encrypted custom protocol → Agents look for: WinINet/WinSock, crypto on network data, DGA
- OUTPUT: IOC table, protocol structure, signatures → Agents extract: IPs/domains/ports, message format, detection patterns
Result: Agents spawn with APT C2 specialization, focus on actionable IOCs, extract detection-relevant patterns.
Framework as Scaffold
WHAT - Technical task
WHY - Actual objective determining approach
CONTEXT - Information constraining/focusing analysis
OUTPUT - Form making results usable
Not rules. Questions to reason through what enables effective agent spawning.
Orchestrator can't read your mind. It derives agent strategy from task description.
Architecture Essentials
Communication flow:
Claude Code → MCP Server → Orchestrator (IDA) → Agents (IDA instances)
Two workspace locations:
/tmp/ida_swarm_sessions/{session_id}/
- IPC files: request.json, response.json, sequence files
- ida.err - check this for IDA errors
- ida.out - IDA stdout
/tmp/ida_swarm_workspace/{binary_name}/
- agents/agent_N/ - agent databases, logs, memories
- orchestrator.log - check for orchestrator errors
- profiling/ - performance metrics (if enabled)
- extract_results.sh - debug tool (raw agent dump)
File-based IPC
- Orchestrator polls sequence files for changes
- Atomic writes via tmp+rename
- Response text contains orchestrator's synthesis
Agent coordination
- Agents work on isolated database copies
- IRC for conflict resolution when agents disagree
- Orchestrator merges findings after agents complete
- Response text contains merged result
Tool Usage Patterns
start_analysis_session
- Spawns IDA
- Returns session_id and initial findings in response text
run_in_background=true returns immediately (use for parallel analysis)
send_message
- Orchestrator maintains full context from previous messages
- Can reference previous findings naturally
- Returns synthesized response text
run_in_background=true requires retrieving response later
close_session
- 60-second graceful shutdown (IDA database save)
- Cleans workspace directory
- Orphaned files (created by orchestrator) remain where they were written
get_session_messages
- Non-blocking poll for background mode
- Returns empty if still processing
- Clears message queue when retrieved
wait_for_response
- Blocking wait for background mode
- Returns when response available
- Use for parallel analysis coordination
Background Mode (Parallel Analysis)
When to use run_in_background=true:
- Analyzing multiple binaries simultaneously
- Long analysis + other work needed
Pattern:
s1 = start_analysis_session(bin1, task1, run_in_background=true)
s2 = start_analysis_session(bin2, task2, run_in_background=true)
s3 = start_analysis_session(bin3, task3, run_in_background=true)
r1 = wait_for_response(s1)
r2 = wait_for_response(s2)
r3 = wait_for_response(s3)
Orchestrator Capabilities
File writing
- Can create files (scripts, reports, configs)
- Default location: next to binary
- Can specify custom paths in request
Binary patching
- Agents can modify binaries via Keystone assembler
- Patches applied to both IDA database and actual binary file
Multi-agent decomposition
- Orchestrator spawns specialized agents based on task
- Quality of task description determines agent specialization
- Agents work in parallel, findings merged
Common Issues
"Session started but no response"
- Check
/tmp/ida_swarm_sessions/{session_id}/ida.err
- Verify IDA process:
ps aux | grep ida64
- Check orchestrator log:
tail /tmp/ida_swarm_workspace/{binary}/orchestrator.log
"Cannot send message: still processing"
- ONE pending message constraint
- Use
get_session_messages() to check status
- Wait for response before next message
Optimization
Reuse sessions
- Multiple follow-up questions in same session
- Much faster than closing and reopening
Debugging Checklist
Configuration
MCP Server: ~/.ida_swarm_mcp/server_config.json
{
"max_sessions": 25,
"ida_path": "/Applications/IDA Professional 9.0.app/Contents/MacOS/ida64"
}
Orchestrator: ~/.idapro/llm_re_config.json
{
"api": {"auth_method": "api_key", "api_key": "sk-ant-..."},
"profiling": {"enabled": true}
}
Key Takeaways
- Sessions are deterministic (same binary = same session_id)
- Results in response text, not extract_results.sh (debug only)
- ONE pending message per session at a time
- TRUE CONTEXT determines agent spawning quality
- 10+ minutes is normal, not hung
- Two workspace directories for debugging
- extract_results.sh = debug tool for raw agent data
- 60-second shutdown is graceful IDA database save
