Claudy Orchestration

Claudy Orchestration

Multi-agent session manager for Claude Code. Spawn and manage persistent Claude agent sessions with automatic cleanup.

Quick Start

⚠️ IMPORTANT: Claudy works in two modes:

1. CLI Mode (Always available, no setup needed) - Use uvx claudy commands
2. MCP Mode (Optional, for Claude Code integration) - Add to .mcp.json

If you don't have MCP configured, use CLI mode! It provides the same functionality.

Option 1: CLI Usage (No Setup Required)

# Start the server (required first step)
uvx claudy server start

# Call an agent session
uvx claudy call <name> "<message>" [--verbosity quiet|normal|verbose]

# List all sessions
uvx claudy list

# Get session status
uvx claudy status <name>

# Cleanup sessions
uvx claudy cleanup <name>
uvx claudy cleanup --all

# Stop the server
uvx claudy server stop

Option 2: MCP Integration (Optional)

Add to your .mcp.json for Claude Code integration:

{
  "mcpServers": {
    "claudy": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/kangjihyeok/claude-agentic-skills.git@main#subdirectory=claudy",
        "fastmcp",
        "run",
        "claudy.mcp_server:mcp"
      ]
    }
  }
}

MCP Tools

claudy_call

Send a message to an agent session (auto-creates if doesn't exist).

Parameters:

• name (str): Session name
• message (str): Message to send
• verbosity (str): "quiet", "normal", or "verbose" (default: "normal")
• fork (bool): Fork before sending (default: false)
• fork_name (str, optional): Name for forked session
• parent_session_id (str, optional): Explicit parent session to inherit context from

Returns: {"success": true, "name": "...", "response": "...", "session_id": "..."}

claudy_call_async

Start agent task in background, returns immediately for parallel execution.

Parameters:

• name (str): Session name
• message (str): Message to send
• verbosity (str): "quiet", "normal", or "verbose" (default: "normal")
• parent_session_id (str, optional): Explicit parent session to inherit context from

Returns: {"success": true, "name": "...", "status": "running"}

claudy_get_results

Wait for and aggregate results from multiple background agents (blocking until complete).

Parameters:

• names (list[str]): List of session names to wait for
• timeout (int, optional): Timeout in seconds

Returns: {"success": true, "results": {"name1": {...}, "name2": {...}}}

claudy_check_status

Check if background tasks are still running.

Parameters:

• names (list[str], optional): Session names to check (if None, checks all)

Returns: {"success": true, "tasks": {"name1": "running", "name2": "completed"}}

claudy_list

List all active agent sessions.

Returns: {"success": true, "sessions": [...]}

claudy_status

Get detailed status of a specific session.

Parameters:

• name (str): Session name

Returns: Session metadata (created_at, last_used, message_count, etc.)

claudy_share_context (NEW!)

Share context from one session that other sessions can access.

Parameters:

• session_name (str): Name of the session sharing the context
• context_key (str): Unique identifier for this context (e.g., "verification_findings", "test_results")
• context_data (dict): Dictionary containing the context to share

Returns: {"success": true, "context_key": "...", "session_name": "...", "message": "..."}

Use Cases:

• Verifier shares findings → Analyst validates them
• Generator shares solution → Tester shares results → Fixer accesses both
• Multiple specialists share analysis → Lead agent synthesizes

claudy_get_shared_context (NEW!)

Retrieve shared context from other sessions.

Parameters:

• context_key (str): The context identifier to retrieve
• source_session (str, optional): Optional filter by source session name

Returns: {"success": true, "context_key": "...", "count": N, "contexts": [...]}

Each context contains:

• session_name: Source session
• session_id: Source session ID
• data: The shared data
• timestamp: When it was shared

claudy_cleanup

Cleanup one or all sessions.

Parameters:

• name (str, optional): Session name to cleanup
• all (bool): Cleanup all sessions (default: false)

Returns: {"success": true, "message": "..."}

Usage Patterns

Basic Session Management

# Auto-create and call a session
Use claudy_call with name="researcher" and message="Search for latest AI papers"

# Check status
Use claudy_status with name="researcher"

# Cleanup
Use claudy_cleanup with name="researcher"

Context Preservation

1. claudy_call(name="memory_test", message="Remember this number: 42")
2. claudy_call(name="memory_test", message="What number did I ask you to remember?")
   → "42" ✓ Context preserved!

Inter-Session Context Sharing (NEW!)

# Verifier agent shares findings
claudy_call(name="verifier", message="Review code for bugs")
claudy_share_context(
    session_name="verifier",
    context_key="bug_findings",
    context_data={"critical_bugs": [...], "warnings": [...]}
)

# Analyst agent validates findings
claudy_call(name="analyst", message=f"""
Review these bug findings and mark each as 'confirmed' or 'false_positive':
{claudy_get_shared_context("bug_findings", "verifier")}
""")

# Fixer accesses validated findings
claudy_call(name="fixer", message=f"""
Fix only the confirmed bugs:
{claudy_get_shared_context("validated_bugs", "analyst")}
""")

Session Forking

# Create base session
claudy_call(name="analysis", message="Analyze this codebase")

# Fork to explore alternatives
claudy_call(
    name="analysis",
    message="Try refactoring approach B",
    fork=True,
    fork_name="analysis_fork_b"
)

# Original session unchanged
claudy_call(name="analysis", message="Continue with approach A")

Parallel Execution

# Launch multiple agents in parallel
claudy_call_async('security', 'Audit code for vulnerabilities')
claudy_call_async('performance', 'Find performance bottlenecks')
claudy_call_async('docs', 'Generate API documentation')

# Collect all results
claudy_get_results(['security', 'performance', 'docs'])

IOI/Competitive Programming Pattern (NEW!)

Multi-stage workflow with specialized agents and context sharing. Based on solving Korean Olympiad in Informatics problems using iterative refinement.

## Agent Role Templates

# Code Generator Agent - Focuses on initial correctness
GENERATOR_PROMPT = """
You are an IOI algorithm expert specializing in generating optimal solutions.
PRIORITY: Correctness > Optimization
OUTPUT: Working code + complexity analysis + edge cases
Allowed Tools: Read, Grep, Glob, WebSearch
"""

# Strict Verifier Agent - Finds ALL issues (false positives OK)
VERIFIER_PROMPT = """
You are a strict IOI coach and automated judge combined.
PRIORITY: Find ALL potential issues, even if uncertain
OUTPUT: Categorized issues (Critical Logic Error, TLE/MLE, Implementation Bug, Edge Case)
Style: Adversarial, detailed, quote specific code sections
"""

# Analyst Agent - Validates verifier findings (prevents over-fixing!)
ANALYST_PROMPT = """
You are a senior IOI coach judging verification reports.
PRIORITY: Distinguish real issues from false positives
OUTPUT: Each finding marked as 'confirmed' or 'false_positive' with justification
Style: Evidence-based, conservative
"""

# Conservative Fixer Agent - Minimal changes, test after each
FIXER_PROMPT = """
You are a careful code improver for IOI solutions.
PRIORITY: Preserve working functionality, change ONE thing at a time
OUTPUT: Incremental fix + test + next fix (not bulk changes!)
Style: Conservative, test-driven
"""

# Lead Synthesizer Agent - Final integration and decision making
LEAD_PROMPT = """
You are the meta-coordinator for IOI problem solving.
PRIORITY: Synthesize all agent insights, make final decisions
ACCESS: All shared contexts from specialized agents
OUTPUT: Final solution that integrates verified improvements only
Style: Holistic, evidence-based
"""

## Complete IOI Workflow

# Step 1: Generate initial solution
Use claudy_call with name="code_generator" and GENERATOR_PROMPT + problem description
Use claudy_share_context to share the solution under key="solution_v1"

# Step 2: Self-critique
Use claudy_call with name="critic" and message including solution_v1
Use claudy_share_context to share critique under key="critique"

# Step 3: Strict verification
Use claudy_call with name="verifier" and message including solution + critique
Use claudy_share_context to share findings under key="verification_findings"

# Step 4: Analyst validation (CRITICAL - prevents over-fixing!)
Use claudy_call with name="analyst" and message:
  "Review these findings and mark each as 'confirmed' or 'false_positive':
  {claudy_get_shared_context('verification_findings', 'verifier')}"
Use claudy_share_context to share validated issues under key="confirmed_issues"

# Step 5: Incremental fixing with testing
baseline_score = test_solution(solution_v1)
For each confirmed issue (one at a time):
    Use claudy_call with name="fixer" and message:
      "Fix ONLY this issue: {issue}
       Previous score: {current_score}
       {claudy_get_shared_context('solution_v1')}
       Provide updated code."
    Test the fix
    If score >= current_score:
        Accept fix, update current_score
        Use claudy_share_context with key="solution_v{iteration}"
    Else:
        Reject fix, continue to next issue

# Step 6: Lead agent final synthesis (if not 100% score)
If score < 100:
    Use claudy_call with name="lead" and message:
      "Synthesize all contexts and achieve 100 points:
       {claudy_get_shared_context('solution_v1')}
       {claudy_get_shared_context('critique')}
       {claudy_get_shared_context('verification_findings')}
       {claudy_get_shared_context('confirmed_issues')}
       Test results: {all_test_results}
       Make final improvement."

Key Lesson from Real Usage: The 44→23 point regression happened because we skipped Step 4 (Analyst validation) and applied all verifier findings at once in Step 5. The improved workflow fixes this by:

1. Adding validation layer (Step 4)
2. Applying changes incrementally with testing (Step 5)
3. Lead agent synthesis with full context (Step 6)

Key Features

• Dual Mode: CLI (no setup) or MCP (Claude Code integration)
• Context Preservation: Agents remember full conversation history
• Session Forking: Branch conversations to explore alternative paths
• Auto Cleanup: 20-minute idle timeout prevents resource leaks
• Independent Sessions: Clean context, no automatic inheritance
• Parallel Execution: Run multiple agents concurrently with claudy_call_async
• Zero Configuration: CLI works out of the box with uvx

Configuration

Sessions auto-cleanup after 20 minutes of inactivity. To customize:

Edit claudy/config.py:

SESSION_IDLE_TIMEOUT = 1200  # 20 minutes in seconds
SESSION_CLEANUP_INTERVAL = 300  # 5 minutes

Architecture

[CLI Mode]                      [MCP Mode]
claudy CLI → HTTP Server        Claude Code → stdio
         ↓                               ↓
         └──────── FastMCP Server ───────┘
                        ↓
            ClaudeSDKClient Sessions (in-memory)
                        ↓
                Auto cleanup (20min idle timeout)

Design:

• CLI Mode: HTTP server (starts with claudy server start)
• MCP Mode: Direct stdio communication (no HTTP server)
• Global session storage (shared across all connections)
• Background TTL cleanup task (20-minute idle timeout)
• Independent sessions (no automatic context inheritance)

Important Notes

Use CLI Mode if MCP is Not Configured

You don't need MCP to use claudy! If you see MCP tool errors:

1. Start the HTTP server: uvx claudy server start
2. Use CLI commands: uvx claudy call <name> "<message>"

CLI mode provides identical functionality to MCP mode.

Server Start Required (CLI Mode)

For CLI usage, you must start the server first:

uvx claudy server start

Then you can use call, list, status, cleanup commands. The server will NOT auto-start.

Session Persistence

Sessions are in-memory only. They are lost when:

• Server stops
• Session idle for 20+ minutes
• Manual cleanup via claudy_cleanup

MCP vs CLI Mode

Both modes share the same session storage and features.

Troubleshooting

"Server is not running"

Run uvx claudy server start before using CLI commands.

Sessions disappearing

Sessions cleanup after 20 minutes of inactivity. Use them regularly or reduce SESSION_IDLE_TIMEOUT.

Fork fails

Ensure parent session has sent at least one message (session_id must exist).

Requirements

• Python 3.10+
• Claude Code 2.0+ (for claude-agent-sdk)
• fastmcp >= 2.12.0
• claude-agent-sdk >= 0.1.4

License

MIT License

Built with ❤️ using FastMCP and claude-agent-sdk