claudy 0.1.0

Universal Claude agent manager with CLI, HTTP API, and MCP integration

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:

{
  "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:

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

Development

Local Development

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

{
  "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 and claude-agent-sdk