Initial commit
This commit is contained in:
Zhongwei Li
293
skills/claudy-orchestration/SKILL.md
Normal file
293
skills/claudy-orchestration/SKILL.md
Normal file
@@ -0,0 +1,293 @@
|
||||
---
|
||||
name: claudy-orchestration
|
||||
description: 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)
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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`:
|
||||
```python
|
||||
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:
|
||||
|
||||
```bash
|
||||
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](https://github.com/jlowin/fastmcp) and [claude-agent-sdk](https://github.com/anthropics/claude-agent-sdk-python)**
|
||||
Reference in New Issue
Block a user