Klaudio

AI Agent Launcher

Launch Claude Code in Docker containers with prompt templates.
Select a template, start the task, and let Claude handle everything — with full visibility and control.

Quick Start · Roadmap · Contributing · Release Process · API · Releases

What is Klaudio?

Klaudio launches Claude Code inside Docker containers and gives it the right prompt for the job. Give it a task, and it:

1. Select a template — Choose from 10 built-in prompt templates (auto, parallel, fullstack, multi-module, dev-test, dev-review, tdd, bugfix, refactor, explore)
2. Start — A single Docker container launches with the templated prompt
3. Claude handles the rest — Claude Code uses its internal Agent tool to parallelize work as needed
4. Delivers — Results are collected and can be auto-committed to Git

All with real-time streaming, a modern web UI, and full stop/resume capability.

Highlights

Architecture

graph TD
    Browser["🌐 Browser<br/><i>SvelteKit + xterm.js</i>"]

    Browser -- "REST API" --> API
    Browser -. "WebSocket" .-> API

    subgraph Server["⚙️ Go API Server · :8080"]
        direction TB
        API["🔀 Chi Router · Stream Hub · Auth"]

        subgraph Core["🧠 Core Services"]
            direction LR
            TaskManager["📋 TaskManager"]
            TemplateEngine["📝 TemplateEngine"]
            RepoManager["📦 RepoManager"]
            FileManager["📁 FileManager"]
        end

        subgraph Infra["🔧 Infrastructure"]
            direction LR
            AgentPool["🏊 AgentPool"]
            DockerMgr["🐳 DockerMgr"]
            StreamHub["📡 StreamHub"]
            StateStore["💾 StateStore"]
        end

        API --> Core
        API --> Infra
        Core --> DB["🗄️ SQLite<br/><i>modernc.org/sqlite</i>"]
        Infra --> DB
    end

    DockerMgr --> Agent

    subgraph Agent["🐳 Docker Container (1 per task)"]
        direction TB
        Claude["🤖 Claude Code"]
        SubAgent1["🔧 Sub-agent 1"]
        SubAgent2["🔧 Sub-agent 2"]
        SubAgentN["🔧 Sub-agent N"]
        Claude --> SubAgent1
        Claude --> SubAgent2
        Claude --> SubAgentN
    end

    style Browser fill:#7c3aed,stroke:#6d28d9,color:#fff,stroke-width:2px
    style Server fill:#0f172a,stroke:#334155,color:#e2e8f0,stroke-width:2px
    style API fill:#2563eb,stroke:#1d4ed8,color:#fff,stroke-width:2px
    style Core fill:#064e3b,stroke:#065f46,color:#d1fae5,stroke-width:1px
    style Infra fill:#7c2d12,stroke:#9a3412,color:#fed7aa,stroke-width:1px
    style DB fill:#d97706,stroke:#b45309,color:#fff,stroke-width:2px
    style Agent fill:#022c22,stroke:#065f46,color:#d1fae5,stroke-width:2px
    style Claude fill:#059669,stroke:#047857,color:#fff,stroke-width:2px
    style SubAgent1 fill:#0d9488,stroke:#0f766e,color:#fff,stroke-width:1px
    style SubAgent2 fill:#0d9488,stroke:#0f766e,color:#fff,stroke-width:1px
    style SubAgentN fill:#0d9488,stroke:#0f766e,color:#fff,stroke-width:1px
    style TaskManager fill:#10b981,stroke:#059669,color:#fff
    style TemplateEngine fill:#10b981,stroke:#059669,color:#fff
    style RepoManager fill:#10b981,stroke:#059669,color:#fff
    style FileManager fill:#10b981,stroke:#059669,color:#fff
    style AgentPool fill:#f97316,stroke:#ea580c,color:#fff
    style DockerMgr fill:#f97316,stroke:#ea580c,color:#fff
    style StreamHub fill:#f97316,stroke:#ea580c,color:#fff
    style StateStore fill:#f97316,stroke:#ea580c,color:#fff

    linkStyle 0 stroke:#a78bfa,stroke-width:2px
    linkStyle 1 stroke:#a78bfa,stroke-width:2px,stroke-dasharray:5
    linkStyle 5 stroke:#059669,stroke-width:2px

Tech Stack

Quick Start

Option 1 — Download a release (recommended)

Download the latest binary from the Releases page:

# Linux (amd64)
curl -L https://github.com/davidebaraldo/Klaudio/releases/latest/download/klaudio-linux-amd64 -o klaudio
chmod +x klaudio
./klaudio

The binary includes the web UI and Docker build context — no build step needed.

Option 2 — Build from source

Prerequisites

• Go 1.22+
• Docker Engine running
• Node.js 20+ (for the web UI)
• Claude Code Max account with config in ~/.claude/

git clone https://github.com/davidebaraldo/Klaudio.git
cd Klaudio

# Build the agent Docker image
make docker-build

# Build everything (frontend + backend) and start
make run

The server starts at http://localhost:8080 with the web UI served from the same port.

Development mode

For faster iteration during development:

# Terminal 1: Build and run backend only
make dev

# Terminal 2: Start frontend dev server with HMR
cd web && npm install && npm run dev

The dev frontend runs at http://localhost:5173 and proxies API calls to the Go backend.

Task Lifecycle

stateDiagram-v2
    direction LR

    [*] --> created
    created --> running : start

    running --> completed : success
    running --> paused : stop
    running --> failed : error

    paused --> running : resume
    failed --> running : retry
    completed --> [*]

    classDef initial fill:#6366f1,color:#fff,stroke:#4f46e5,stroke-width:2px
    classDef active fill:#f59e0b,color:#fff,stroke:#d97706,stroke-width:2px
    classDef success fill:#10b981,color:#fff,stroke:#059669,stroke-width:2px
    classDef warn fill:#f97316,color:#fff,stroke:#ea580c,stroke-width:2px
    classDef error fill:#ef4444,color:#fff,stroke:#dc2626,stroke-width:2px

    class created initial
    class running active
    class completed success
    class paused warn
    class failed error

Execution Model

Klaudio runs one Docker container per task. Claude Code handles all parallelism internally using its built-in Agent tool — spawning sub-agents to work on different parts of the codebase simultaneously. The prompt template guides Claude's strategy (e.g., parallel work, TDD, fullstack split), but Claude decides how to break down and execute the work.

Configuration

Create a config.yaml file (or use environment variables):

server:
  port: 8080                    # KLAUDIO_PORT
  host: 0.0.0.0                 # KLAUDIO_HOST

docker:
  image_name: klaudio-agent
  max_agents: 5                 # Global concurrent container limit

claude:
  auth_mode: host               # "host" (mount ~/.claude/) or "env" (session key)
  # session_key: ""             # CLAUDE_SESSION_KEY

database:
  path: data/klaudio.db         # KLAUDIO_DB_PATH

storage:
  data_dir: data
  auto_save_enabled: true
  auto_save_interval: 5m
  max_checkpoints: 3

Claude Code Authentication

API Reference

Tasks

Communication & Files

Templates

# Create a task with auto-start
curl -s http://localhost:8080/api/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hello World",
    "prompt": "Create a simple Hello World API in Go with tests",
    "auto_start": true
  }' | jq .

# Watch the task in your browser
open http://localhost:8080/tasks/<task-id>

Project Structure

klaudio/
├── cmd/klaudio/              # Entry point, embed directives
├── internal/
│   ├── api/                  # HTTP handlers, Chi router, WebSocket
│   ├── agent/                # Agent pool management
│   ├── config/               # YAML + env configuration
│   ├── db/                   # SQLite layer (hand-written queries)
│   ├── docker/               # Docker container management
│   ├── embedded/             # Embedded frontend + Docker context
│   ├── files/                # File upload/download/transfer
│   ├── repo/                 # Git operations, repo analysis, platform APIs
│   ├── state/                # Checkpoint persistence, autosave
│   ├── stream/               # Real-time streaming hub
│   └── task/                 # Task engine
│       ├── manager.go            # Task lifecycle controller
│       ├── template.go           # Prompt template engine
│       └── ...
├── docker/                   # Agent Dockerfile and entrypoint
├── migrations/               # SQL migrations
├── web/                      # SvelteKit frontend
│   └── src/
│       ├── routes/               # Pages
│       └── lib/
│           ├── components/       # Terminal, SubAgentPanel, FileManager...
│           ├── stores/           # WebSocket, tasks
│           └── api.ts            # TypeScript API client
├── .github/workflows/        # CI + Release pipelines
├── config.yaml               # Default configuration
└── Makefile                  # Build targets

Development

make build            # Build binary (frontend + backend)
make build-backend    # Build backend only (faster)
make run              # Build and start server
make dev              # Backend-only build + start
make docker-build     # Build agent Docker image
make test             # Run all tests
make clean            # Remove artifacts and database
make tidy             # go mod tidy

Development Guidelines

• No CGO — Pure Go SQLite via modernc.org/sqlite
• Context everywhere — All I/O functions accept context.Context
• Wrapped errors — fmt.Errorf("doing X: %w", err)
• Hand-written SQL — No ORM, queries in internal/db/queries.go
• Structured logging — log/slog for all output
• No global state — Dependencies passed via structs

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Good first issues

• Add unit tests for existing packages
• Improve error messages and input validation
• UI improvements and bug fixes
• Create new prompt templates
• GitHub/GitLab Git integration (Phase 7)

License

Apache License 2.0 — use it freely in personal and commercial projects.