gh-jhvictor4-claudy-claudy-multi-agent/skills/claudy-orchestration/SKILL.md

name, description

name	description
claudy-orchestration	Use this skill when delegating to sub-agents that require more flexibility than the Task tool provides - when launching multiple agents in parallel, managing persistent sessions across calls, or coordinating complex multi-agent workflows with custom orchestration patterns.

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_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!

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'])

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

Feature	CLI Mode	MCP Mode
Setup	None (always works)	Requires .mcp.json configuration
Server	HTTP (manual start)	stdio (auto-managed by Claude Code)
Usage	uvx claudy call ...	Use claudy_call tool
Functionality	✅ Full	✅ Full

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