Cardloop

Your AI dev team on your own server — steered from your phone.

Drop a card on the board. An agent picks it up in its own git worktree, writes the code, and parks it in Review: one tap runs your tests, one tap merges or discards it. It keeps working while your laptop sleeps.

• Runs 24/7 on your box — systemd or Docker, not a desktop app.
• Phone-first — an installable PWA that pushes a notification when a run finishes.
• Claude Code by default, OpenAI Codex and xAI Grok Build optional — on your own accounts.
• Built with itself — over 80% of its commits are co-authored by AI agents · 5,400+ tests · OpenSSF Best Practices: passing.

Watch the 80-second ad — made inside Cardloop.

⭐ If this saves you time, a GitHub star helps other people find it.

---

What it is, in 5 seconds

• What: a kanban board where each card auto-runs a coding/ops agent to completion — full-auto. Claude by default; OpenAI Codex and xAI Grok Build are optional providers.
• Who: one operator running many projects (software, content, ops) who isn't always at a desk.
• Why: the board is the agent's memory. Work lives on a board the agent keeps honest, not in a chat log that scrolls away. You write the ticket; Claude does the work; you watch it happen — on your phone.

Three things make Cardloop different from the dozen other agent kanbans:

1. 📱 Pocket DevOps — mobile-first PWA. Not "responsive" — installable. Add it to your home screen and run agents from your phone: live SSE streaming, reconnect on wake, safe-area, pinch-zoom, plus an interactive PTY terminal. The phone is the primary surface, not an afterthought.
2. 🤖 Claude-native, no middleman. Cardloop doesn't reimplement an agent — it drives the official Claude Code CLI / Agent SDK on your own host, with your own Anthropic account: a Claude Console API key (recommended, and required for teams/commercial use) or your personal claude login for individual use — the same auth you'd use running Claude Code by hand. No SaaS in the middle, no per-seat markup, nothing sent anywhere but to the model provider you chose.
3. 🗂️ Cards that code — safely. A card's task text becomes the agent prompt. Moving a card to In Progress runs the engine in an isolated git worktree, attaches the diff, and lands the card in Review behind a Check / Apply / Discard gate — your working copy is never touched until you merge.

A 12-second tour — board, a live agent-driven browser, usage analytics, and the same cockpit on your phone

---

Features

• Kanban-as-a-runtime — TASKS.md in each repo is the board. Sections are columns, lines are cards. The agent reads and writes it every turn and reconciles it against real commits/diffs after each run, so the board stays the single source of truth instead of a chat log that scrolls away.
• Full-auto card runs — drag a card to In Progress; the engine runs the task, attaches result + git diff, and moves it to Review or Failed, then pings you.
• Isolated worktree runs + review gate — on a clean git repo, each card runs in its own .worktrees/card-<id> branch (falls back to in-place "legacy" mode when git is off). The C2 gate gives you 🧪 Check (run the test suite in the worktree → safe / risky verdict), ✓ Apply (git merge --no-ff), and ✗ Discard (trash the branch + worktree, restore clean state).
• Deferred runs — auto-resume on rate limit — hitting Claude's 5-hour limit doesn't abort the agent. Cardloop suspends the run, polls the usage quota, and resumes automatically when the limit resets.
• Mobile-first installable PWA — home-screen install, offline-aware SSE reconnect, touch-optimized, achromatic dark UI, plus a bidirectional WebSocket PTY terminal (@xterm/xterm) with OSC 52 clipboard so you can copy an OAuth login link on mobile.
• Run-finished notifications — a browser notification when a run completes, with click-to-jump to the project. In-app when the tab is open, Web Push when the app is fully closed (messenger-style), with smart de-dup so you never get both. Opt-in. See docs/notifications.md.
• Live agent-driven browser pane — a real browser embedded in the cockpit that the agent drives and you watch live, and co-drive (click/scroll/type alongside the agent, on desktop and mobile — type a login from your phone). Three pluggable backends: built-in Chromium (default, no stealth), a one-click free CloakBrowser stealth tier (anti-detect, MIT), or external CDP / Cloak Manager persistent logged-in profiles the agent reuses. Read-only by default; a gate decides when it may click/type. Opt-in. See docs/browser.md.
• Bring your own Claude — the engine drives the official claude CLI under your own Anthropic auth (CLAUDE_AUTH_MODE: API key, or personal subscription login for individual use). Cardloop never extracts, stores, or transmits your tokens — the official binary handles auth itself.
• Multi-project cockpit — explicit projects, each with its own cwd, model, persistent session, and board.
• One transport-agnostic engine — run_engine() feeds every channel against the same session and board.
• CLI-style chat — SSE stream, tool rendering (Bash / Edit / Read / Write with diffs), on-the-fly model switch, message queue, prompt library, real interrupt.
• Production-grade internals — 2400+ tests, per-project secrets vault (.claude-ops/secrets/secrets.env, chmod 600), a deny list for a few host-wide irreversible commands (see the Security model), double path-traversal defence, single-operator auth (web password + optional TOTP 2FA).
• Always-on self-hosted service — systemd or Docker, accessible over HTTPS / Cloudflare Tunnel.

---

Quickstart

Setup time: ~3 minutes — clone, run install.sh, claude login, set a password.

Prerequisites

• Python 3.11+ and Node 20+
• Claude Code CLI — curl -fsSL https://claude.ai/install.sh | bash (or npm i -g @anthropic-ai/claude-code). It installs to ~/.local/bin; make sure that's on your PATH. The engine drives this claude binary, so it's needed for both claude login and runtime.

# 1. Clone
git clone https://github.com/igdigitallab/cardloop.git && cd cardloop

# 2. Install (venv + deps + .env scaffold + frontend build) — idempotent
./install.sh                  # or: make install

# 3. Authenticate — pick ONE (see "Authentication" below for the ToS guidance):
claude login                  # personal use: your own Claude subscription, same as Claude Code itself
#   — or —                    # teams / products / anything beyond personal use:
#   .env → CLAUDE_AUTH_MODE=api_key + ANTHROPIC_API_KEY=sk-ant-...   (Claude Console)

# 4. Set your password
#    edit .env → WEB_PASSWORD=...   (.env is a hidden dotfile; WEB_COOKIE_SALT was auto-generated for you)

# 5. Run
venv/bin/python bot.py        # Cockpit → http://localhost:8787
#    or install as a background service:  make service

# 5b. Reach it from your phone right now — no Cloudflare account, no DNS, no config
venv/bin/python bot.py --tunnel   # prints a public https://*.trycloudflare.com URL + a QR code to scan

Prefer Docker? claude login on the host, set WEB_PASSWORD + WEB_COOKIE_SALT in .env, then:

docker compose up --build     # cockpit-only — see docker-compose.yml

On macOS: get the prerequisites with brew install python node (plus the Claude CLI above); install.sh and the cockpit run the same as on Linux. Two platform notes: make service is Linux/systemd-only, so run venv/bin/python bot.py (or wrap it in a launchd plist / tmux); and .env is a hidden dotfile — reveal it in Finder with ⌘⇧. or edit it from the terminal.

Access from anywhere (your own domain)

By default Cardloop listens on localhost only — perfect on your own machine, but to use it from your phone or away from home you need to reach it over the network. Three ways, fastest first (read the Security model first — you're exposing a full-auto agent, so keep WEB_PASSWORD strong and enable TOTP):

• Zero-config, try it now — --tunnel. venv/bin/python bot.py --tunnel (or CARDLOOP_TUNNEL=1 in .env for the systemd service) starts a cloudflared quick tunnel and prints a public https://*.trycloudflare.com URL plus a scannable QR code — no account, no config file, no DNS. The hostname is ephemeral: it changes every time the tunnel restarts, so it's for trying Cardloop out or a one-off remote session, not a link you bookmark. Needs the cloudflared binary on PATH (install); missing it just prints a hint and the cockpit keeps running on localhost. Tradeoffs vs. the two options below → docs/remote-access.md.

• Private, no public URL — Tailscale (simplest for a URL you keep). Install it on the host and on your phone/laptop; reach the cockpit at http://<tailscale-ip>:8787. Nothing is exposed to the public internet. Great when it's just for you.

• Public HTTPS on your own domain — Cloudflare Tunnel (named tunnel) (works behind CGNAT/NAT, no port-forwarding, free). This is the one you keep — a stable hostname on your own domain, not the ephemeral one from --tunnel above. Point a subdomain at the cockpit:

  cloudflared tunnel login                              # one-time, opens a browser
  cloudflared tunnel create cardloop                    # creates the tunnel + credentials
  cloudflared tunnel route dns cardloop cockpit.example.com
  # ~/.cloudflared/config.yml:
  #   tunnel: <tunnel-id>
  #   credentials-file: /home/<user>/.cloudflared/<tunnel-id>.json
  #   ingress:
  #     - hostname: cockpit.example.com
  #       service: http://localhost:8787
  #     - service: http_status:404
  cloudflared service install                           # run it as a background service

  Then set TRUSTED_PROXIES=127.0.0.1 in .env so the login rate-limiter sees real client IPs, and open https://cockpit.example.com. A public HTTPS origin is also what lets you install the PWA on iOS.

Updating

./update.sh        # or: make update

Pulls the latest version, reinstalls dependencies only if they changed, rebuilds the frontend, and restarts the systemd service if one is installed. Docker: git pull && docker compose up --build -d.

Troubleshooting

Something broken, or filing a bug report? Run the built-in diagnostic first:

make doctor                       # or: venv/bin/python tools/doctor.py
venv/bin/python tools/doctor.py --json   # machine-readable

In under 5 seconds it prints versions, auth state, config, systemd service health, runtime reachability, and data counts, ending with a ✗/⚠ verdict and a one-line remedy for each finding (exit code is non-zero when any ✗ is present). Read-only — it never restarts anything or touches your data — and secret values are always redacted. Paste its output into a GitHub issue.

Daily activity journal

Want a diary of what you did through the cockpit each day — every project, IT or non-IT, with times? tools/daily-journal.py scans the previous local calendar day's sessions, commits, board cards, and specs across every project, and asks a small model (Haiku, on your subscription — no extra API billing) to write a short Markdown note into your notes vault:

venv/bin/python tools/daily-journal.py                    # yesterday, written to $JOURNAL_DIR
venv/bin/python tools/daily-journal.py --date 2026-08-30  # a specific day
venv/bin/python tools/daily-journal.py --days 7           # backfill the last 7 days
venv/bin/python tools/daily-journal.py --dry-run --no-model --date 2026-08-30  # preview, no model call

Idempotent (--date/--days regenerate in place) and safe by construction: a generated note always carries generated: cardloop-daily-journal frontmatter, and a file at that path which lacks the marker (i.e. one you wrote by hand) is never overwritten — the note goes to YYYY-MM-DD-cardloop.md instead. Configure the destination and timezone with JOURNAL_DIR / JOURNAL_TZ in .env (defaults: $HOME/vault/Journal, America/Los_Angeles); the note's language follows RESPONSE_LANGUAGE. For a daily cron, source the vars it needs and log to a file, e.g.:

30 3 * * * RESPONSE_LANGUAGE=$(grep -m1 '^RESPONSE_LANGUAGE=' /path/to/cardloop/.env | cut -d= -f2-) /path/to/cardloop/venv/bin/python /path/to/cardloop/tools/daily-journal.py --data-dir /path/to/cardloop/data >> $HOME/logs/daily-journal.log 2>&1

(Extract just the variables you need rather than source .env wholesale — .env is written for systemd's EnvironmentFile= parser, not bash, and a value elsewhere in the file can break a plain source.)

---

Install it on your phone (PWA)

The cockpit is a Progressive Web App — install it to your home screen and it behaves like a native app.

1. Open your cockpit URL in mobile Chrome / Edge (or Safari on iOS).
2. Tap the browser menu → Install app (Android) or Share → Add to Home Screen (iOS).
3. Launch it from your home screen. You get full-screen, no browser chrome, live SSE streaming, and reconnect-on-wake — built for running agents while you're away from your desk.

Desktop browsers support Install app too, for a standalone window.

Turn on notifications: Global Settings → 🔔 Notifications. You'll get a browser notification when a run finishes (click it to jump to the project) — in-app when open, and Web Push when the app is fully closed (installed PWA + HTTPS required; on iOS, push needs the installed PWA). Full guide: docs/notifications.md.

---

How it works

flowchart LR
    C[Cockpit PWA]
    K[Kanban card]
    C --> E
    K --> E
    E[run_engine&#40;&#41;<br/>async generator] --> SDK[Claude Agent SDK<br/>your Anthropic auth]
    SDK --> O[files / git / deploy]
    E -. reconciles .-> B[(TASKS.md<br/>board)]
    K --- B

Loading

One transport-agnostic run_engine() generator feeds every channel. Whatever you do — type in the cockpit or move a card — runs through the same engine, against the same session, and updates the same board.

TASKS.md in each repo is the board — sections are columns, lines are cards:

## Backlog
- [a1b2c3] Add rate-limit headers to the login endpoint
- [d4e5f6] Write the onboarding email copy

## In Progress
- [99aa88] Fix mobile chat scroll jumping on keyboard open

## Review
- [77bb66] Bump vite to v8 + verify build  ← agent finished; diff waiting for you

## Done
- [55cc44] Add requirements.txt

The lifecycle: you add a card → drag it to In Progress → the engine runs the task in an isolated worktree → result + git diff are attached → the card lands in Review (or Failed) → you Check / Apply / Discard → you get a ping. Move a card, and the agent picks it up.

---

Authentication — bring your own Claude

Cardloop is orchestration software: it spawns and drives the official claude binary on your own host and never touches Anthropic's API or your OAuth tokens itself. Two supported modes (CLAUDE_AUTH_MODE in .env):

• api_key — recommended, and required for anything beyond personal use. Set ANTHROPIC_API_KEY from Claude Console (pay-as-you-go). This is the mode Anthropic's authentication policy prescribes for developers and products, and the only permitted mode for teams, hosted, or commercial deployments.
• subscription — personal, individual use only. claude login once; the official CLI uses your own Claude account exactly as if you ran Claude Code in a terminal. Anthropic's terms scope subscription auth to "ordinary, individual usage of Claude Code and the Agent SDK" — one person, their own account, their own machine. Do not use this mode to serve other users, share an account, or run a hosted service; that violates Anthropic's Consumer Terms and risks your account.

Either way there's no middleman: your Anthropic account, your host, zero markup. You are responsible for complying with the terms of your own plan — see Legal & Terms.

---

Channels

The cockpit is the home base. Everything runs through one engine and one session, so you can start on your phone and finish in the browser.

Cockpit (the PWA)

A browser IDE — React + Vite SPA with an aiohttp backend.

Sidebar: projects with drag-and-drop sorting, collapse, unread badges. Project tabs at the top — switch between projects without losing state.

Tab	What it does
Overview	Git status, health card (6 checks), "↑ Sync" button (commit+push), run tests
Board	Kanban from TASKS.md — Backlog / In Progress / Review / Failed, with the Check/Apply/Discard gate
CLAUDE.md	View + inline editing (double-click)
Terminal	Interactive PTY (xterm) over WebSocket, OSC 52 clipboard
Logs	Configurable log command (log_cmd in topics.json)
Files	Project file tree + viewer (MD render, code mono)
Memory	Agent memory files

Chat (persistent): SSE stream, CLI-style tool rendering (Bash / Edit / Read / Write with diffs), shared sessions, on-the-fly model switch, message queue, prompt library, real interrupt (client.interrupt). Plus free-form chats, a global $HOME file browser, attachments (📎 / drag-drop / Ctrl+V), a subscription usage badge (5h + week), and project creation / audit / health-check / rename.

Kanban auto-run

Moving a card to In Progress → _run_card triggers run_engine → result written to data/runs/<card>.md → card moves to Review/Failed → notification.

---

How this compares

The agent-kanban space is crowded, but it splits into desktop-local agent runners (you must be at a dev machine) and enterprise orchestration dashboards (RBAC, fleet management). Cardloop targets neither — it's the personal cockpit you run at home and operate from your phone.

	Cardloop	Desktop agent runners	Orchestration dashboards
Mobile-first PWA	✅ installable, primary surface	❌ desktop binary	⚠️ responsive at best
Card = agent run	✅ task text becomes the prompt	⚠️ manual trigger per task	❌ dispatch layer over agents
Git isolation (worktrees)	✅ runs on an isolated branch + review gate	❌ edits your workspace directly	❌ needs your own git/CI setup
Resilient queue	✅ deferred auto-resume after rate limit	❌ halts on rate limits	❌ halts on rate limits
No-middleman billing	✅ your Anthropic account, zero markup	✅	❌ per-seat SaaS pricing
Always-on self-hosted service	✅ systemd / Docker / HTTPS	❌ launch from terminal	✅
Multi-project structured cockpit	✅ explicit projects + sessions	⚠️ per-repo	✅

Trade-offs, stated plainly: it's Claude-first. Claude Code is the default engine and the deepest integration (per-tool approval in ask mode and several subscriptions in one cockpit exist only for Claude); OpenAI Codex and xAI Grok Build are optional providers, off by default (CODEX_ENABLED / GROK_ENABLED), each on its own subscription. And webapp.py is a large monolith we're decomposing in the open. PRs welcome.

---

Security model

Cardloop is a single-operator tool that runs agents with full host access. Read this before exposing it to a network.

• Agents run with bypassPermissions — full host access by design. They edit files, run git, and deploy without per-action prompts. Run Cardloop only on a host you're comfortable handing to an autonomous agent. Only a short, fixed deny list of host-wide irreversible Bash shapes is blocked before it runs: rm -rf aimed at / or $HOME (the bare path or a glob right under it), chmod -R opening up / or $HOME, a forced git push to master/main (or with no branch named), git reset --hard, writes or deletes under ~/.ssh, docker system prune, mkfs, dd onto a raw device, a fork bomb, plus any regex you add in DENY_COMMANDS_EXTRA. It matches the command text only: deleting a project directory, force-pushing any other branch, and anything a script or interpreter does inside is not gated. The model is "trusted operator," not "sandboxed."
• Single-user, not multi-tenant. Cockpit auth is a web password + optional TOTP 2FA. There is no per-user isolation.
• An authenticated session can read the decrypted secret vault. By design — the vault's confidentiality reduces to your login (password + TOTP) and the session cookie.
• log_cmd / test_cmd are allowlisted, not sandboxed. They run without a shell (shell metacharacters are rejected) and only for a fixed list of programs (journalctl, docker, tail, head, cat, grep, pytest, python, npm, make, cargo, go), given as a bare name, as the full path of the same file the bare name resolves to, or as a project-relative path such as venv/bin/python; wrapper scripts, and an absolute path to an interpreter elsewhere (e.g. /srv/app/venv/bin/python), only from directories you list in DIAG_CMD_ALLOW_DIRS. The list includes interpreters and docker on purpose, so this guards against mistakes and injected values — it is not a boundary: the authenticated operator already has a shell.
• The global file browser excludes ~/.ssh, ~/.gnupg, ~/.claude, ~/.config/claude-ops, and .env*.
• Put it behind HTTPS. Set WEB_COOKIE_SECURE=true whenever you're not on localhost. Behind a reverse proxy, set TRUSTED_PROXIES (CSV of proxy IPs/CIDRs) so the login rate-limiter sees real client IPs instead of the proxy's.
• WebSockets check Origin. The terminal (a PTY shell) and the browser pane refuse a browser upgrade whose Origin is not the cockpit's own, because SameSite=Lax does not stop another page on the same host from riding your cookie. Extra origins go in WS_ALLOWED_ORIGINS; scripts that send no Origin work as before.
• Rate-limit state is in-memory and resets on restart.
• No third-party login. Cardloop never asks for your GitHub or Anthropic account credentials. It runs on your own host and uses your machine's existing git config and your local claude login — nothing is sent anywhere. Updating is a plain git pull from the public repo; no token, no account.

Found a vulnerability? Please report it privately — see SECURITY.md (GitHub private advisory or security@igdigi.com), not a public issue.

---

Configuration

Set in .env (scaffolded by install.sh):

Variable	Purpose
WEB_PASSWORD	Cockpit login password (required)
WEB_COOKIE_SALT	Session-cookie salt. Leave blank: a private one is generated on first start and stored in data/cookie_salt (install.sh sets one in .env)
WEB_COOKIE_SECURE	Set true when not on localhost (HTTPS)
TRUSTED_PROXIES	CSV of proxy IPs/CIDRs behind a reverse proxy
WS_ALLOWED_ORIGINS	Extra origins (CSV of scheme://host[:port]) allowed to open the terminal / browser-pane WebSockets; the cockpit's own origin is always allowed
AGENT_ENV_PASSTHROUGH	CSV of variable names that agents and terminals should still inherit. By default the cockpit removes every secret (*_PASSWORD, *_SALT, *_TOKEN, *_SECRET, *_API_KEY, plus a fixed list; not ANTHROPIC_*) from its own environment at start; list one here only if a tool the agent runs needs it (e.g. GITHUB_TOKEN). See SECURITY.md
OPERATOR_NAME / RESPONSE_LANGUAGE	Operator name and the agent's reply language
CLAUDE_AUTH_MODE	api_key (recommended; required for teams/commercial) or subscription (personal use)
ANTHROPIC_API_KEY	Claude Console key — required when CLAUDE_AUTH_MODE=api_key

The project registry, sessions, and board state live under data/ (gitignored). Full reference and manual steps → CONTRIBUTING.md.

---

Documentation

File	Purpose
ARCHITECTURE.md	Code map: where to find what, flow diagram
CLAUDE.md	Working rules and gotchas for agents
docs/API.md	HTTP API reference — the main flows, written by hand
docs/API-routes.md	Complete HTTP route index (every method + path, auth, handler) — generated from the live router, drift-tested
docs/notifications.md	Run-finished notifications (in-app + Web Push) — setup & troubleshooting
docs/browser.md	Live browser pane — backends (built-in / CloakBrowser / Cloak Manager), co-control, safety gate
docs/remote-access.md	--tunnel quick tunnel vs. Tailscale vs. named Cloudflare Tunnel — which to use when
CONTRIBUTING.md	Setup, tests, lint, commit style
TASKS.md	Live board (kanban) — backlog and current tasks

---

Tech stack

Python 3.11 · aiohttp · Claude Agent SDK · React 18 · Vite · TypeScript · @xterm/xterm · systemd · pytest

---

Contributing

PRs are welcome — this is an open project and the monolith is being decomposed in the open.

• Read CONTRIBUTING.md for setup, tests, lint, and commit style.
• Tests: venv/bin/python -m pytest tests/ (3,500+, should be green). New functionality comes with tests.
• All new code, comments, docs, and UI strings are English-only; the agent's reply language is configurable separately via RESPONSE_LANGUAGE.
• Found a bug or have an idea? Open an issue. Found a vulnerability? Report it privately — SECURITY.md.

---

Legal & Terms

Trademark. "Claude" and "Anthropic" are trademarks of Anthropic, PBC. Cardloop is an independent open-source project and is not affiliated with, endorsed by, or sponsored by Anthropic. Cardloop invokes the official claude CLI; it does not reimplement, bundle, or modify Anthropic's software.

Anthropic Terms of Service. Cardloop runs the official claude CLI on your own host and never reads, extracts, or transmits your OAuth tokens or API keys itself — authentication is handled entirely by Anthropic's own binary. That said, how you authenticate matters under Anthropic's authentication and credential-use policy:

• API key (CLAUDE_AUTH_MODE=api_key) is the mode Anthropic prescribes for developers and products, and the only permitted mode for teams, hosted, multi-user, or commercial deployments.
• Subscription mode (claude login) is for personal, individual use only — Anthropic scopes consumer-plan auth to ordinary, individual usage of Claude Code and the Agent SDK by the account owner. Never share an account, route other users through your plan, or offer Claude.ai login as a service — Anthropic prohibits this and enforces it (typically by account action, without notice).
• In subscription mode bot.py removes ANTHROPIC_API_KEY from the environment to prevent accidental API billing; in api_key mode it is passed through to the SDK.

Anthropic's policies evolve — check the legal & compliance page for the current text. You are responsible for your own compliance.

This project is provided "as is" under the MIT License; see also the NOTICE file for third-party attributions.

---

Credits

The built-in default prompt templates (spec-writer, debug-triage, pre-deploy-gate) and the executor sub-agent addendums (planning mode, source-driven development, doubt-check) are adapted from addyosmani/agent-skills, published under the MIT License by Addy Osmani et al.

---

Built for shipping from the couch. ⭐ Star it if you'd use it → github.com/igdigitallab/cardloop