Claud-IA

AI agent orchestrator with system tray integration for macOS. Manages Claude Code CLI sessions in Docker containers (or locally) with a web terminal interface.

Features

• Docker-based agents - Each Claude session runs in an isolated container
• Local agent support - Run agents directly on the host without Docker
• System tray - macOS menu bar integration for quick access
• Web terminal - Browser-based terminal with full PTY support
• Wake lock - Prevents Mac from sleeping while agents are active
• Resource bounded - Memory/CPU limits prevent host starvation
• Auto-cleanup - Testcontainers Ryuk handles orphaned containers

Installation

Global Installation (Recommended)

npm install -g @zicenter/claud-ia

Using npx

npx @zicenter/claud-ia

From Source

git clone https://github.com/zicenter/claud-ia.git
cd claud-ia
npm install
npm run build
npm link

Requirements

• macOS (Apple Silicon or Intel)
• Node.js >= 20.0.0
• Docker Desktop (for container backend)
• Optional: fzf (brew install fzf) for project picker

Quick Start

# Start the orchestrator (opens system tray)
claud-ia

# Or run with npx
npx @zicenter/claud-ia

Once running, access the web interface at http://localhost:3000 or use the system tray menu to manage agents.

CLI Commands

claud-ia launch [path]     # Launch agent (fzf picker if no path)
claud-ia list              # List running agents
claud-ia attach [id]       # Attach to agent tmux session
claud-ia stop [id]         # Stop an agent
claud-ia stop --all        # Stop all agents
claud-ia status            # Show system status

Configuration

Create ~/.claud-ia.json:

{
  "projectDirs": ["~/Projects", "~/Code"],
  "agent": {
    "backend": "container",
    "resourceLimits": {
      "memory": "8g",
      "cpus": 4
    }
  }
}

Set agent.backend to "local" to run agents directly on the host without Docker.

Remote Access

# SSH into your Mac (e.g., via Tailscale)
ssh [email protected]

# Launch or attach to agents
claud-ia launch
claud-ia attach <id>

# Detach with Ctrl+B D (agent keeps running)

Architecture

macOS Host
├── Claud-IA Orchestrator (Node.js)
│   ├── System Tray (node-systray-v2)
│   ├── Web Server (Fastify + WebSocket)
│   └── Agent Manager (Testcontainers / node-pty)
└── Agents
    ├── Docker Containers (tmux → claude-code)
    └── Local Processes (PTY → claude-code)

Development

npm install          # Install dependencies
npm run dev          # Run server + client with hot reload
npm run build        # Build for production
npm run typecheck    # Type check

License

MIT