From f05501db4bd1ce83ea80c087fc58534000576ef8 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:26:00 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 + README.md | 3 + plugin.lock.json | 48 +++ skills/claudy-orchestration/SKILL.md | 293 ++++++++++++++++++ .../references/cli_reference.md | 116 +++++++ 5 files changed, 472 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 plugin.lock.json create mode 100644 skills/claudy-orchestration/SKILL.md create mode 100644 skills/claudy-orchestration/references/cli_reference.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..91a7b07 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "claudy-multi-agent", + "description": "Multi-agent orchestration plugin providing both CLI skill and MCP tools. Enables launching multiple agents in parallel, managing persistent sessions, and coordinating complex workflows beyond Task tool capabilities.", + "version": "0.0.0-2025.11.28", + "author": { + "name": "Jihyeok Kang", + "email": "[email protected]" + }, + "skills": [ + "./skills/claudy-orchestration" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..5afd010 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# claudy-multi-agent + +Multi-agent orchestration plugin providing both CLI skill and MCP tools. Enables launching multiple agents in parallel, managing persistent sessions, and coordinating complex workflows beyond Task tool capabilities. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..1dabaea --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,48 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:Jhvictor4/claudy:claudy-multi-agent", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "00a1bfc3ffcbafcc7376cfdcb33d36672ce93d65", + "treeHash": "01045635f1d5eb892c83c04a441ce606e97d47befb063d8eaa366b8e428d8b0f", + "generatedAt": "2025-11-28T10:11:48.089576Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "claudy-multi-agent", + "description": "Multi-agent orchestration plugin providing both CLI skill and MCP tools. Enables launching multiple agents in parallel, managing persistent sessions, and coordinating complex workflows beyond Task tool capabilities." + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "5d148f49d9971fca1dd8fb90b41b90d5d0f1f49fe6df365a3adff6757d0ae5c8" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "6240441df615ae36545c7ad918b8759e6f38dd8f387b1f38937e43db33bdeb7d" + }, + { + "path": "skills/claudy-orchestration/SKILL.md", + "sha256": "a57436ae69787e229dc58b74fcd9fd994c064f9770118689ee8e8970aafa5232" + }, + { + "path": "skills/claudy-orchestration/references/cli_reference.md", + "sha256": "85f4040744346fcc275114d3b44bfc93dd82a0f547aa1a70f81d8434d5e0ffff" + } + ], + "dirSha256": "01045635f1d5eb892c83c04a441ce606e97d47befb063d8eaa366b8e428d8b0f" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/claudy-orchestration/SKILL.md b/skills/claudy-orchestration/SKILL.md new file mode 100644 index 0000000..4b1de99 --- /dev/null +++ b/skills/claudy-orchestration/SKILL.md @@ -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 "" [--verbosity quiet|normal|verbose] + +# List all sessions +uvx claudy list + +# Get session status +uvx claudy status + +# Cleanup sessions +uvx claudy cleanup +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 ""` + +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)** diff --git a/skills/claudy-orchestration/references/cli_reference.md b/skills/claudy-orchestration/references/cli_reference.md new file mode 100644 index 0000000..c3fb3bf --- /dev/null +++ b/skills/claudy-orchestration/references/cli_reference.md @@ -0,0 +1,116 @@ +# Claudy CLI Reference + +Complete reference for claudy command-line interface. + +## Installation + +Claudy can be used via `uvx` without installation: + +```bash +uvx claudy +``` + +## Commands + +### call - Send message to agent + +```bash +uvx claudy call [options] +``` + +**Arguments:** +- `name`: Session name (creates new session if doesn't exist) +- `message`: Message to send to the agent + +**Options:** +- `--verbosity `: Output verbosity (quiet/normal/verbose, default: normal) +- `--fork`: Fork session before sending message +- `--fork-name `: Name for forked session + +**Examples:** +```bash +# Create and call agent +uvx claudy call researcher "Search for latest AI papers" + +# Call with quiet output +uvx claudy call researcher "Continue analysis" --verbosity quiet + +# Fork session +uvx claudy call analysis "Try approach B" --fork --fork-name analysis_b +``` + +### list - List all sessions + +```bash +uvx claudy list +``` + +Shows all active agent sessions with metadata (created_at, last_used, message_count). + +### status - Get session details + +```bash +uvx claudy status +``` + +**Arguments:** +- `name`: Session name to check + +Shows detailed session information including idle time. + +### cleanup - Remove sessions + +```bash +uvx claudy cleanup +# or +uvx claudy cleanup --all +``` + +**Arguments:** +- `name`: Session name to cleanup (optional if using --all) + +**Options:** +- `--all`: Remove all sessions + +### server - Start HTTP server + +```bash +uvx claudy server [options] +``` + +**Options:** +- `--host `: Server host (default: 127.0.0.1) +- `--port `: Server port (default: 8000) + +Starts HTTP server for programmatic access to claudy. + +## Session Behavior + +- **Auto-creation**: Sessions are created automatically on first `call` +- **TTL cleanup**: Sessions auto-cleanup after 20 minutes of inactivity +- **In-memory**: Sessions reset when server restarts +- **Context preservation**: Each session remembers full conversation history + +## JSON Output Format + +All commands return JSON for easy parsing: + +```json +{ + "success": true, + "name": "researcher", + "session_id": "uuid", + "response": { + "content": [...], + "stop_reason": "end_turn" + } +} +``` + +Error responses: +```json +{ + "success": false, + "error": "Session not found" +} +```