shadok-ai

shadok-ai is an open-source, AGPL-3.0-licensed tool that wraps the Claude Code CLI into a browser-based cockpit, letting you run many Claude Code sessions side by side on your existing Claude subscription — no API key required. It is installed with a single npx shadok-ai command (Node 20+) and opens a web UI that manages agents, schedules, secrets, and multi-user access from one place. The project is notable for being largely built by agents running inside itself, each working in its own git worktree and landing changes as reviewed pull requests.

What It Is

shadok-ai is a self-hosted agent orchestration cockpit for Claude Code. It drives the interactive claude CLI through a real terminal (via tmux or node-pty), reads responses from Claude Code's own .jsonl transcript, and exposes a browser UI plus a Telegram bridge for remote control. The core design goal is letting multiple Claude Code agents work in parallel without duplicating effort, wasting quota on silent runs, or requiring you to be at your desk to answer their questions.

How the Multi-Agent Architecture Works

Each agent runs in its own git worktree and branch, so parallel agents never collide on the filesystem. Agents can spawn child agents, and a parent is notified the moment a child finishes, blocks on a question, or dies — nothing polls. A shared ledger (opt-in) keeps one table of settled decisions across all agents: a bug closed or a job already run is written once, and every other agent receives the delta before its next message, so the same problem is never fixed twice. The cockpit also exposes a WebSocket protocol (ws://…/ws) so any client — another front-end, a bot, or a script — can attach to the same session and receive the same events.

Scheduling and the Zero-Token Guard

Agents can be given recurring prompts on a schedule (every N minutes, or daily at a specific time in a named timezone). Each schedule can carry a deterministic guard command that runs without invoking the model: if the guard prints nothing, the agent is never woken and the run costs zero tokens. This is the design the name references — Les Shadoks, French cartoon birds from 1968 who pumped relentlessly for no result, are the anti-pattern the guard is built to prevent.

Remote Control and Multi-Pilot Access

Connecting a Telegram group (with Topics enabled) gives every agent its own topic. Questions arrive as tappable buttons; photos and files sent from the phone land in the agent's working directory. The Telegram session and the browser session are the same process — an answer tapped on a phone appears instantly on the open browser tab. Multiple people can drive the same agent simultaneously from different browsers or from Telegram; with a password set, each pilot gets a named login via an invitation link, and every prompt arrives with the sender's name attached.

Deployment Model

shadok-ai runs entirely on your own machine or in a Docker container. The repo ships an official Dockerfile that bundles Claude Code, shadok-ai, a headless Playwright Chromium browser, git, gh, tmux, and a C toolchain. Three Docker volumes persist state across restarts and container recreation: ~/.shadok-ai (vault, profiles, channels, crons, SSH identity), ~/.claude (credentials, transcripts), and /workspace (agents' files). For network exposure, the server binds 127.0.0.1 by default; setting SHADOK_HOST=0.0.0.0 requires a password and enables a multi-user login system with admin and member roles.

Update: v0.7.0 — Scheduled Agents and the Zero-Token Guard

The latest release, v0.7.0 (published 2026-08-24), is named "scheduled agents, and a guard that costs nothing." It formalizes the cron scheduling system and the deterministic guard command as first-class features. The project follows two release channels: beta (the default, promoted deliberately by bumping the minor version) and alpha (every merge to main). Version numbers encode the channel: an alpha carries the commit count (e.g., 0.3.78), while a promotion is a round number (e.g., 0.4.0). The cockpit polls npm and can update and reload itself in place.