# Claudy

**Universal Claude agent manager - FastMCP-based MCP server for managing persistent Claude agent sessions**

Claudy lets you spawn and manage multiple Claude agent sessions from within Claude Code, with automatic session management, TTL-based cleanup, and fork support.

## Features

- 🤖 **MCP Native** - Built with FastMCP for seamless Claude Code integration
- 🔄 **Context Preservation** - Agents remember conversation history across calls
- 🌳 **Session Forking** - Branch conversations to explore alternative paths
- ⏱️ **Auto Cleanup** - 2-hour idle timeout prevents resource leaks
- 🔐 **Permission Inheritance** - Auto-created sessions bypass permissions by default
- 🚀 **Zero Configuration** - Works out of the box with uvx

## Quick Start

### Installation (Claude Code)

Add to your `.mcp.json` or `claude_desktop_config.json`:

```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"
      ]
    }
  }
}
```

That's it! uvx will automatically handle dependencies.

## Usage (from Claude Code)

### 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"

# List all sessions
Use claudy_list

# Cleanup
Use claudy_cleanup with name="researcher"
```

### Context Preservation Example

```
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")
```

## 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): Parent to inherit from (auto-detected)

**Returns:** JSON with `success`, `name`, `response`, `session_id`

### `claudy_list`

List all active agent sessions.

**Returns:** JSON with `success`, `sessions` (array of session metadata)

### `claudy_status`

Get detailed status of a specific session.

**Parameters:**
- `name` (str): Session name

**Returns:** JSON with 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:** JSON with `success`, `message`

## Architecture

```
Claude Code
    ↓ MCP (stdio)
FastMCP Server
    ↓ Direct
ClaudeSDKClient Sessions (in-memory)
    └─ Auto cleanup (2hr idle timeout)
```

**Key features:**
- Single process (no HTTP server needed)
- Global session storage (shared across all MCP connections)
- Background TTL cleanup task
- Auto-detection of current Claude session ID for permission inheritance

## Configuration

Edit `claudy/mcp_server.py` to customize:

```python
SESSION_IDLE_TIMEOUT = 7200  # 2 hours
SESSION_CLEANUP_INTERVAL = 300  # 5 minutes
```

## Development

### Local Development

```bash
# Clone repo
git clone https://github.com/kangjihyeok/claude-agentic-skills.git
cd claude-agentic-skills/claudy

# Install with uv
uv pip install -e .

# Run MCP server
fastmcp dev claudy/mcp_server.py:mcp
```

### Local Testing in Claude Code

Use local path in `.mcp.json`:

```json
{
  "mcpServers": {
    "claudy": {
      "type": "stdio",
      "command": "/path/to/fastmcp",
      "args": ["run", "/path/to/claudy/mcp_server.py:mcp"]
    }
  }
}
```

## How It Works

### Auto-Creation

Sessions are automatically created on first `claudy_call`:
- Inherits current Claude session ID (auto-detected from `~/.claude/projects/`)
- Sets `bypassPermissions` mode by default
- Can use all tools (WebSearch, Read, Write, etc.)

### TTL Cleanup

Background task runs every 5 minutes:
- Checks `last_used` timestamp of each session
- Disconnects and removes sessions idle > 2 hours
- Prevents memory leaks from forgotten sessions

### Forking

When `fork=True`:
- Creates new session with `resume` + `fork_session` options
- Inherits full conversation history from parent
- Parent and fork are independent after creation

## 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

## Author

Kang Jihyeok

---

**Built with ❤️ using [FastMCP](https://github.com/jlowin/fastmcp) and [claude-agent-sdk](https://github.com/anthropics/claude-agent-sdk-python)**
