Initial commit

2025-11-30 08:26:00 +08:00
commit f05501db4b
5 changed files with 472 additions and 0 deletions
--- a/.claude-plugin/plugin.json
+++ 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"
+  ]
+}
--- a/README.md
+++ 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.
--- a/plugin.lock.json
+++ 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": []
+  }
+}
--- a/skills/claudy-orchestration/SKILL.md
+++ 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 <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)**
--- a/skills/claudy-orchestration/references/cli_reference.md
+++ 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 <command>
+```
+
+## Commands
+
+### call - Send message to agent
+
+```bash
+uvx claudy call <name> <message> [options]
+```
+
+**Arguments:**
+- `name`: Session name (creates new session if doesn't exist)
+- `message`: Message to send to the agent
+
+**Options:**
+- `--verbosity <level>`: Output verbosity (quiet/normal/verbose, default: normal)
+- `--fork`: Fork session before sending message
+- `--fork-name <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 <name>
+```
+
+**Arguments:**
+- `name`: Session name to check
+
+Shows detailed session information including idle time.
+
+### cleanup - Remove sessions
+
+```bash
+uvx claudy cleanup <name>
+# 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 <host>`: Server host (default: 127.0.0.1)
+- `--port <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"
+}
+```