Claudio macht Claude Code als Dienst nutzbar
Claude Code läuft bislang nur im Terminal, was unpraktisch wird, wenn man Chats vom Handy starten oder mehrere Agenten parallel im Blick behalten will. Das selbstgebaute Tool Claudio schließt diese Lücke, indem es Claude Code als Service laufen lässt.
Veröffentlicht am 24. Oktober • Ursprünglich erschienen auf josegarrido.dev
Claude Code lebt in einem Terminal. Das ist in Ordnung, solange du keinen Chat vom Handy aus starten, einen Agenten überprüfen möchtest, der weiterarbeitet, während du nicht am Schreibtisch bist, oder fünf davon parallel betreiben willst, ohne den Überblick zu verlieren, welcher davon eine Antwort braucht. Ich habe Claudio gebaut, um diese Lücke zu schließen: Es betreibt Claude Code als Dienst.
Dieser Beitrag behandelt, was Claudio ist, wie es mit Claude Code kommuniziert und wie man es installiert.
Claudio stellt die Claude Code CLI hinter eine REST API und eine Web UI. Derselbe Server unterstützt auch eine Linux Desktop App und eine installierbare Web App für dein Handy. Alles läuft auf deinem Rechner oder deinem Server, mit deinem eigenen Claude Login.
Claudio liest das Terminal nicht aus, ruft keine undokumentierten Endpunkte auf und meldet sich nicht selbst ein zweites Mal an. Es erreicht Claude Code über die Flags der CLI, ihr Stream Protokoll und die Dateien, die sie schreibt. docs/cli-surfaces.md listet jede genutzte Schnittstelle auf, eine Zeile pro Anwendungsfall. Zum Beispiel:
Gespräch starten / fortsetzen claude -p --input-format stream-json --output-format stream-json, Auth Status claude auth status --json, Sitzungsverlauf $CLAUDE_CONFIG_DIR/projects/*/*.jsonl. Die praktische Konsequenz ist eine Obergrenze: Was die CLI nicht kann, kann auch Claudio nicht. Web Artefakte und der claude.ai Chat Speicher haben keine CLI Schnittstelle, daher greift Claudio nicht auf sie zu.
Ein Chat ist ein langlebiger claude Prozess, der über stdin gespeist wird, mit --resume, wenn der Prozess nicht mehr existiert. Du kannst einen über die UI oder über die API starten:
curl -X POST http://localhost:8797/api/chats mit dem Header Content-Type: application/json und dem Body mit prompt und cwd, etwa dem Prompt "Add a unit test for parseDuration" und dem Arbeitsverzeichnis /workspace/my-app. Die Anfrage akzeptiert außerdem worktree (Ausführung in einem neuen git worktree mit diesem Namen) und jsonSchema (strukturierte Ausgabe). Von dort stehen dir POST /api/chats/:id/messages, /stop, /interrupt, /resume und /fork sowie GET /api/chats/:id/stream zur Verfügung, um dem Verlauf zu folgen. Wenn der Agent nach einer Berechtigung, einer Frage oder einer Planfreigabe fragt, antwortest du über die UI (oder per POST /api/chats/:id/permissions/:requestId).
Die interaktive Referenz wird unter /docs bereitgestellt, das OpenAPI 3.1 Dokument unter /openapi.json. Wenn du die Authentifizierung aktiviert hast, sende Authorization: Bearer <token>.
Die UI fragt nicht zyklisch ab. Ein einziger Server Sent Events Feed, GET /api/events, überträgt Chats, auf dich wartende Prompts, Aufgaben, Orchestrierungen und Konto Rotation und setzt nach einem Abbruch mit Last-Event-ID wieder an.
Eine Orchestrierung ist ein Graph von Aufgaben. Worker laufen parallel, jeder in seinem eigenen git worktree, und ihre Branches werden in einen Integrationsbranch zusammengeführt. Danach läuft in einer Verifizierungsphase deine Prüfung (Build, Tests) auf dem Integrationsbranch mit einem Timeout, und ein Pull Request kann angeboten werden. Sie existiert als Route POST /api/orchestrations und als Bildschirm, auf dem du den Ablauf Schritt für Schritt verfolgst.
Zwei Dinge gilt es zu beachten: Die Prüfungen benötigen worktree: true in der Graph Engine, und Worker überleben keinen Neustart. Eine davon erfasste Aufgabe wird als unterbrochen markiert, und ihr Chat läuft in einer neuen Ausführung weiter, solange Versuche übrig sind.
Jedes Claude Konto erhält sein eigenes CLAUDE_CONFIG_DIR und meldet sich einmalig an. Claudio liest die Nutzung pro Zeitfenster aus, verschiebt neue Arbeit auf ein Konto mit Kontingent, bevor ein Limit erreicht wird, spielt einen Zug, der sein Limit erreicht, auf dem nächsten Konto erneut ab und wartet nur auf das Zurücksetzen, wenn keines mehr Kontingent übrig hat. Außerdem gibt es eine kleine CLI, claudio-accounts, in packages/accounts.
Für einen Chat, eine Aufgabe oder den Integrationsbranch gibt es einen Diff Bildschirm, der aus git und dem Transkript erstellt wird. Jede Änderung trägt den Satz, den Claude unmittelbar davor geschrieben hat, sodass du die Änderung zusammen mit ihrer Begründung liest.
Du kannst ein Verzeichnis als Projekt importieren. Es erhält ein Tasks Board mit Arbeitselementen (Schlüssel im Stil von AGN-12, fünf feste Spalten, Epics, Milestones) und ein Team, in dem jedes Mitglied eine Claude Code Agent Datei mit einer Rolle ist. Ist der Flow eingeschaltet, startet eine Karte, die in eine Spalte wechselt, den Lauf dieser Rolle. Nur du bewegst eine Karte nach Done.
Claudio kann PreToolUse Hooks hinzufügen, die auch in bypassPermissions gelten: kein Push, kein --no-verify, kein rekursives Löschen außerhalb des worktree, kein Schreiben von Secrets. Sie sind für Orchestrierungs Worker und den Flow aktiv und lassen sich pro Projekt für Chats konfigurieren. Der Mechanismus ist eine Einstellungsdatei mit ausschließlich Claudios Hooks, übergeben mit --settings. Siehe docs/guards.md.
docker run -d --init --name claudio --restart unless-stopped -p 127.0.0.1:8797:8797 mit den Volumes claudio-config auf /home/node/.claude, claudio-data auf /data und claudio-workspace auf /workspace sowie dem Image ghcr.io/yeyo11/claudio. Öffne http://localhost:8797, melde dich mit dem Owner Token an, das der Container einmal ausgegeben hat (docker logs claudio), und melde dann im Einrichtungsassistenten bei Claude an. Benenne alle drei Volumes, sonst beginnt beim Ersetzen des Containers zur Aktualisierung alles mit leeren Volumes.
Desktop App (Linux x86_64,.deb oder AppImage):
curl -fsSL https://raw.githubusercontent.com/yeyo11/claudio/main/scripts/install.sh | bash. Wie bei jedem Skript, das in eine Shell geleitet wird, lies es zuerst. Die App läuft mit deinem eigenen claude und deinem ~/.claude Login, also ist nichts sandgeboxt und Chats starten in acceptEdits.
Aus dem Quellcode (Node 22+, pnpm 10, ein angemeldetes claude auf deinem PATH):
git clone https://github.com/yeyo11/claudio, cd claudio, pnpm install, pnpm dev. Die API läuft auf Port 8797, die UI auf Port 5181. Danach: Claudio öffnen, den Einrichtungsassistenten Claude Code prüfen lassen, New chat drücken, ein Verzeichnis auswählen und einen Prompt schreiben.
Ein Container erzeugt beim ersten Start ein Owner Token. Bei einer Installation aus dem Quellcode oder in der Desktop App ist die Authentifizierung ausgeschaltet, bis du sie aktivierst. Das ist richtig für einen an 127.0.0.1 gebundenen Port und falsch für alles andere: Ohne Authentifizierung kann jeder, der den Port erreicht, einen Chat auf deinem Konto starten und jedes Transkript auf dem Rechner lesen. Die Modi sind none, token (es wird nur der SHA-256 gespeichert) und oidc (Claudio validiert ein JWT; es meldet niemanden an). Claudio beendet kein TLS, also setze einen Proxy davor. In docs/securing.md stehen die Details.
Claudio ist ein Claude-spezifischer Fork von Agentry, einem unabhängigen Projekt, und steht in keiner Verbindung zu Anthropic.
Die Roadmap sagt, dass derzeit nichts geplant ist. Was übrig blieb, wurde vorerst mit Begründung abgelehnt: native App Store Hüllen, Push pro Nutzer, Offline Nutzung, ein Browser Login Flow für OIDC. Wenn dir einer dieser Punkte wichtig ist, öffne ein Issue und sag mir warum.
Der Code steht unter MIT Lizenz auf github.com/yeyo11/claudio.
Automatisch übersetzt. Das Original auf Englisch ist unten aufklappbar.
Original (Englisch) anzeigen
Posted on Oct 24 • Originally published at josegarrido.dev
Claude Code lives in a terminal. That is fine until you want to start a chat from your phone, check on an agent that is still working while you are away from the desk, or run five of them in parallel without losing track of which one needs an answer. I built Claudio to cover that gap: it runs Claude Code as a service.
This post covers what Claudio is, how it talks to Claude Code and how to install it.
Claudio puts the Claude Code CLI behind a REST API and a web UI. The same server also backs a Linux desktop app and an installable web app for your phone. Everything runs on your machine or your server, with your own Claude login.
Claudio does not scrape the terminal, call undocumented endpoints or log in a second time on its own. It reaches Claude Code through the CLI's flags, its stream protocol and the files it writes. docs/cli-surfaces.md lists every surface in use, one row per need. For example:
Run / continue a conversation claude -p --input-format stream-json --output-format stream-json Auth status claude auth status --json Session history $CLAUDE_CONFIG_DIR/projects/*/*.jsonl Enter fullscreen mode Exit fullscreen mode The practical consequence is a ceiling: what the CLI cannot do, Claudio cannot do. Web artifacts and claude.ai chat memory have no CLI surface, so Claudio does not touch them.
A chat is one long-lived claude process fed over stdin, with --resume when the process is gone. You can start one from the UI or from the API:
curl -X POST http://localhost:8797/api/chats \ -H 'Content-Type: application/json' \ -d '{"prompt": "Add a unit test for parseDuration", "cwd": "/workspace/my-app"}' Enter fullscreen mode Exit fullscreen mode The request also accepts worktree (run inside a new git worktree of that name) and jsonSchema (structured output). From there you have POST /api/chats/:id/messages, /stop, /interrupt, /resume and /fork, and GET /api/chats/:id/stream to follow it. When the agent asks for permission, a question or a plan approval, you answer from the UI (or POST /api/chats/:id/permissions/:requestId ).
The interactive reference is served at /docs and the OpenAPI 3.1 document at /openapi.json. If you turned authentication on, send Authorization: Bearer <token>.
The UI does not poll. One server-sent events feed, GET /api/events, carries chats, prompts waiting for you, tasks, orchestrations and account rotation, and it resumes with Last-Event-ID after a drop.
An orchestration is a graph of tasks. Workers run in parallel, each in its own git worktree, and their branches are merged into one integration branch. After that, a verification phase runs your checks (build, tests) on the integration branch under a timeout, and a pull request can be offered. It exists as the POST /api/orchestrations route and as a screen where you follow the run as steps.
Two things to watch for: the checks need worktree: true on the graph engine, and workers do not survive a restart. A task caught by one is marked interrupted and its chat continues in a new execution while it has attempts left.
Each Claude account gets its own CLAUDE_CONFIG_DIR and is signed in once. Claudio reads usage per window, moves new work to an account with quota before a limit is hit, replays a turn that hits its limit on the next account, and waits for the reset only when none has any quota left. There is also a small CLI, claudio-accounts, in packages/accounts.
For a chat, a task or the integration branch there is a diff screen built from git and the transcript. Each edit carries the sentence Claude wrote just before it, so you read the change together with its reason.
You can import a directory as a project. It gets a Tasks board with work items ( AGN-12 -style keys, five fixed columns, epics, milestones), and a team where each member is a Claude Code agent file with a role. With the flow switched on, a card entering a column starts that role's run. Only you move a card to Done.
Claudio can add PreToolUse hooks that hold even in bypassPermissions: no push, no --no-verify, no recursive delete outside the worktree, no secret written. They are on for orchestration workers and the flow, and configurable per project for chats. The mechanism is a settings file with only Claudio's hooks, passed with --settings. See docs/guards.md.
docker run -d --init --name claudio --restart unless-stopped -p 127.0.0.1:8797:8797 \ -v claudio-config:/home/node/.claude -v claudio-data:/data -v claudio-workspace:/workspace \ ghcr.io/yeyo11/claudio Enter fullscreen mode Exit fullscreen mode Open http://localhost:8797, sign in with the owner token the container printed once ( docker logs claudio ), then sign in to Claude in the setup assistant. Name all three volumes, or replacing the container to update starts again with empty ones.
Desktop app (Linux x86_64,.deb or AppImage):
curl -fsSL https://raw.githubusercontent.com/yeyo11/claudio/main/scripts/install.sh | bash Enter fullscreen mode Exit fullscreen mode As with any script piped to a shell, read it first. The app runs with your own claude and ~/.claude login, so nothing is sandboxed and chats start in acceptEdits.
From source (Node 22+, pnpm 10, a logged-in claude on your PATH ):
git clone https://github.com/yeyo11/claudio && cd claudio pnpm install pnpm dev # API on:8797, UI on:5181 Enter fullscreen mode Exit fullscreen mode Then: open Claudio, let the setup assistant check Claude Code, press New chat, pick a directory and write a prompt.
A container creates an owner token on its first start. A source install or the desktop app has authentication off until you turn it on. That is right for a port bound to 127.0.0.1 and wrong for anything else: with auth off, anyone who reaches the port can start a chat on your account and read every transcript on the machine. The modes are none, token (only the SHA-256 is stored) and oidc (Claudio validates a JWT; it does not log anyone in). Claudio does not terminate TLS, so put a proxy in front. docs/securing.md has the details.
Claudio is a Claude-only fork of Agentry, an independent project, and is not affiliated with Anthropic.
The roadmap says nothing is planned right now. What is left was decided against for now, with reasons: native app-store shells, per-user push, offline use, a browser login flow for OIDC. If one of those matters to you, open an issue and tell me why.
The code is MIT-licensed at github.com/yeyo11/claudio.