Skip to content

README.md

Latest commit

 

History

History
159 lines (127 loc) · 8.89 KB

README.md

File metadata and controls

159 lines (127 loc) · 8.89 KB
Raw

panopticon

Agents write the code, you own what ships.

That's easy with one agent. Run a fleet of them and it breaks down: the fleet stalls waiting on you, and you lose track of which agent is doing what. Panopticon gives you one place to watch them all.

  • A live dashboard of all your tasks, showing which agents are working and which are blocked waiting on you, so you stop cycling through terminals to find the one that's stuck.
  • Configurable workflows that set the line between what an agent may do alone and what needs your sign-off, so agents run unattended without running unchecked. Other tools show you which agent is blocked; Panopticon decides when it blocks.
  • Sandboxed by default: each agent works in its own container on its own branch (secrets and environment handled per repo), so it can work freely and nothing reaches main without your review.

Self-hosted and terminal-native: your infrastructure, your secrets, your repos. A ground-up rewrite of the cloude-cade prototype.

New here? docs/overview.md explains how the pieces fit together: the mental model behind the dashboard.

The dashboard

The whole fleet in one terminal view — every task's state, whose turn it is (agent or you), its container status, and its repo and slug:

══════════════════════════════════════════════════════════════════════════
  panopticon                                                6 tasks
──────────────────────────────────────────────────────────────────────────
  state          turn       container   repo       slug[memo]
  ITERATING      agent      live        web-api    add-oauth[Add OAuth login]
  PLANNING       user       live        web-api    fix-upload[Flaky S3 upload]
  MERGING        agent      starting    dashboard  dark-mode[Dark-mode theme]
  ITERATING      user ⚠     down        web-api    migrate-db[Move to Postgres]
  ORCHESTRATING  agent      live        infra      q3-cleanup[Q3 tech-debt]
  PLANNING       agent      live        infra      └─ drop-py38[Drop Python 3.8]
  COMPLETE       agent      –           web-api    ship-readme[README refresh]
──────────────────────────────────────────────────────────────────────────
  t attach   n new task   x drop   / search   d detail   ? help   q quit
══════════════════════════════════════════════════════════════════════════

The turn column is color-coded live — green when the agent is working, yellow when it's your move, red (⚠) when a task is blocked waiting on you — so you can tell at a glance which agents need you. The container column tracks each agent's sandbox as it spawns (queued → … → live, or down when one needs a respawn), and governed sub-tasks nest under their governor (└─). Press t to drop into any task's session, ? for the full key list.

Requirements

Panopticon runs the control plane on your host and each agent in its own container, so it shells out to a few host tools. You need:

  • Python 3.11+
  • Docker, with the daemon running
  • tmux: the dashboard, console supervisor, and task sessions run on a dedicated tmux -L panopticon server
  • git: the session service clones a per-task workspace for each agent
  • The claude CLI: first-time setup runs claude setup-token on the host to mint the Claude auth token each agent uses inside its container. Minting a token needs a paid Claude subscription or Console login; an ANTHROPIC_API_KEY works instead. See docs/auth.md.

panopticon quickstart checks these first; run panopticon doctor to re-check any time. On macOS you need Docker Desktop specifically; see docs/macos-setup.md.

Install

Panopticon is a command-line app, so pipx is the recommended way to install it: it puts the panopticon command on your PATH in its own isolated environment. Plain pip works too.

# recommended: isolated, on your PATH
pipx install panopticon-app

# or with pip
pip install panopticon-app

The PyPI distribution is panopticon-app, but the command you run and the package you import are both panopticon.

Quickstart

Run panopticon quickstart from inside the repo you want agents to work on: it registers whatever repo you're in as the target for your tasks.

cd ~/code/my-project   # the repo you want agents to work on
panopticon quickstart  # first-time setup, then open the dashboard

panopticon quickstart checks your prerequisites, brings the stack up, registers the repo you're in, and drops you into a setup-repo task; it will walk you through minting a repo-specific Claude token (saved to the repo's env-file). Then you create tasks and watch your fleet from the dashboard.

Your first task

On the dashboard:

  1. Create it. Press n, then pick the repo and a workflow. quickstart already enabled the coding workflow that matches your repo: github-peer-reviewed for a GitHub repo (opens a PR), or local-git-self-reviewed for a local-only one (keeps commits local). spike (open-ended, no gates) is always available too. To use a different workflow, enable it for your repo in the repos form (press g, edit the repo, and check the workflows you want). GitHub workflows need a GH_TOKEN in the repo's env-file so the container's gh can open PRs (see docs/auth.md). Describe the work in a sentence or two; the workflow catalog explains how to choose.
  2. Watch it start. The task's container column moves queued → … → live as the runner spawns its container; once it's live the agent starts on its own branch and begins planning automatically. Press a to open its plan when it's ready.
  3. Respond when it needs you. The turn column shows whether the agent is working or waiting on you. When it wants a decision, like signing off on that plan, press t to attach to its session and steer it; run /advance there to approve its plan or to advance to the next stage in the workflow from whatever stage you're in. Detach any session with Ctrl-b d (or your own tmux prefix + d) to return to the dashboard.
  4. Review what ships. For github-peer-reviewed the agent opens a PR (press p on the dashboard to open it in your browser); for local-git-self-reviewed it commits to the task branch for you to diff locally. Either way nothing lands until you /advance it: you own what ships.

Configuration

Panopticon stores its data under standard XDG locations, each overridable by an environment variable (resolution is $PANOPTICON_* → $XDG_*_HOME/panopticon → the default below):

What Default location Override
Database ~/.local/share/panopticon/panopticon.db PANOPTICON_DB (or PANOPTICON_DATA)
Artifacts + per-task clones ~/.local/share/panopticon/ PANOPTICON_DATA
Layers, secrets, workflows ~/.config/panopticon/ PANOPTICON_CONFIG (workflows also via the --workflows-path flag)
Per-repo clone cache ~/.cache/panopticon/repos/ PANOPTICON_CACHE

Managing your install

  • Bring it back up after a reboot or after you quit: panopticon start starts the services and opens the dashboard. panopticon console re-attaches when the services are already running.
  • Stop everything: panopticon stop removes the task containers and the -L panopticon tmux server. Your data under ~/.local/share/panopticon is left in place.
  • Check your host: panopticon doctor verifies Python, Docker (and a running daemon), tmux, git, and the claude CLI, printing a line per check and exiting non-zero if anything is missing.
  • Stuck? docs/troubleshooting.md collects the common first-run failures — auth, missing tokens, a task stuck at awaiting, missing services — and where to fix each.
  • Upgrade: pipx upgrade panopticon-app (or pip install --upgrade panopticon-app), then panopticon migrate to apply any new database migrations.
  • Uninstall: panopticon stop, then pipx uninstall panopticon-app. To remove state too, delete ~/.local/share/panopticon, ~/.config/panopticon, and ~/.cache/panopticon, and remove the panopticon-* Docker images.

License

MIT. See LICENSE.