PandaDOS README

The project's README from github.com/uniquechao/PandaDOS. As one markdown file: README.md.

PandaDOS — Long-running autopilot for Claude Code and Codex

PandaDOS — Long-running autopilot for Claude Code and Codex

PandaDOS is an open-source, self-hosted control plane that turns Claude Code and Codex into long-running, issue-driven coding agents. You define outcomes and make the important product or architecture decisions; PandaDOS keeps the queue moving, preserves context, handles routine approvals, watches progress, records results, and brings you back only when a real decision is needed.

简体中文 · 日本語

Why PandaDOS · Quick start · Your first 10 minutes · How it works · 24/7 deployment · Security

PandaDOS workspace overview

The workspace, users, issues, branches, and project names in the screenshots are sanitized demo data.

Why PandaDOS

Claude Code and Codex are excellent native coding agents. PandaDOS does not replace them or hide their terminals. It adds the operating system around them:

The goal is not to remove people from software development. It is to free you from continuous supervision so you can focus on product direction, system design, review, and the decisions that actually need judgment.

Quick start

For occasional local use, run PandaDOS on your Mac or Linux workstation. For continuous operation, use a small cloud host that stays online, run PandaDOS as a system service, and attach local or remote executors over SSH. This lets issue queues continue while your laptop is closed.

The control plane requires Bun, Git, tmux, and a writable ~/.panda/. Every executor requires Git, tmux, and an authenticated Claude Code or Codex CLI. An OpenAI-compatible driver model is strongly recommended for clarification, PM decisions, summaries, and approval explanations.

Ask Claude Code or Codex to install it

Paste this prompt into Claude Code or Codex on the machine where you want PandaDOS to run:

Install the latest stable PandaDOS release for me from
https://github.com/uniquechao/PandaDOS/releases.

Before changing anything:
1. Inspect the operating system, current user, available ports, Bun, Git, tmux, Claude Code, Codex,
   systemd, and any existing reverse proxy.
2. Query the latest non-draft, non-prerelease GitHub Release and detect the machine architecture.
   Select exactly one matching asset: macOS arm64 -> macos-arm64, macOS x86_64 -> macos-x64,
   Linux aarch64/arm64 -> linux-arm64, or Linux x86_64/amd64 -> linux-x64. Never substitute an
   asset built for another operating system or architecture.
3. Download the matching `PandaDOS-v*-<platform>.tar.gz` and `SHA256SUMS` from the same Release.
   Verify the archive against its exact SHA-256 entry before extracting it.
4. After extraction, read ARTIFACT.md, README.md, and DEPLOY.md and use them as the source of truth.
5. Explain the exact installation plan and ask before any destructive change, firewall change,
   package removal, or replacement of an existing service or proxy configuration.

Then:
- Install the verified bundle in a dedicated versioned directory and start it with `./bin/pandados`.
- Preserve an existing `~/.panda/`, service definition, reverse proxy, and active tmux agent processes
  when upgrading.
- The bundle already contains the prebuilt UI and production dependencies. It still requires Bun,
  Git, tmux, and an authenticated Claude Code or Codex CLI; install only missing prerequisites.
- If no compatible Release asset exists, stop and explain why. Ask before falling back to cloning
  the source repository and running the full build.
- Keep PandaDOS bound to 127.0.0.1:8802.
- Start it and verify /healthz.
- If systemd is available, install a restart-on-failure service using the DEPLOY.md example and
  preserve tmux agent processes when the control plane restarts.
- If remote access is requested, configure a trusted nginx or Caddy reverse proxy with TLS,
  authentication, and WebSocket forwarding. Never expose port 8802 directly to the public internet.
- Tell me where the one-time admin token was written, but do not print, upload, or transmit secrets.
- Finish with the login URL, service status, health-check result, and any manual steps still needed
  to authenticate Claude Code or Codex.

Release bundles contain the prebuilt UI and target-specific production dependencies. They do not bundle Bun, Git, tmux, Claude Code, or Codex.

Install manually

git clone https://github.com/uniquechao/PandaDOS.git
cd PandaDOS
bun install --frozen-lockfile
bun run check-i18n
bun run typecheck
bun test
bun run build-ui
bun run start

Open http://127.0.0.1:8802. On first start, PandaDOS creates the administrator account and writes its one-time token to ~/.panda/admin-token with mode 0600.

For systemd, reverse proxies, environment variables, SSH executors, health checks, and routine operations, follow DEPLOY.md.

Your first 10 minutes

  1. Sign in. Use the one-time administrator token created during the first start.
  2. Check the executor. In Admin, confirm that the always-on host or SSH machine can find the Claude Code or Codex CLI and its authenticated state.
  3. Configure the driver model. Add an OpenAI-compatible endpoint in Admin if you want PM-assisted clarification, summaries, approval explanations, and project understanding.
  4. Import existing work or create a project.
    • Select Import, choose Claude or Codex, and pick an existing local project to attach its working directory and available conversation history.
    • Choose tmux to register a session that is already running.
    • Select New project to clone a Git repository or create a blank workspace.
  5. Choose how to work. All projects use the issue board.
    • For queued, traceable work, create an issue with the desired outcome, relevant context, and acceptance criteria. PandaDOS handles the execution stages.
    • For exploratory work or one-off changes, start a standalone conversation in the same project and work directly with Claude Code or Codex outside the issue queue.
  6. Set the approval level. Start with balanced mode, review what PandaDOS approves automatically, and increase automation only when the repository and executor are properly isolated.
  7. Leave the queue running. Watch from the browser or phone, answer genuine clarification requests, and spend the rest of your time on design and review.

How it works

You define outcomes and priorities
                │
                ▼
      PandaDOS issue queue and PM
                │
                ├── clarify missing requirements
                ├── plan and choose an agent
                ├── apply approval policy
                ├── observe progress and recover
                └── summarize and hand off
                │
                ▼
       Local or SSH executor
                │
                ▼
          tmux session
                │
                ▼
       Claude Code or Codex

PandaDOS issue workflow

Each issue is a traceable unit of work. Independent projects can run separately. With module workspaces, issues in the same module run sequentially, while issues in different modules can run concurrently up to the configured limit for the project. A module can keep one assigned agent. Issue conversations normally rotate; module knowledge in MODULE.md provides continuity across issues, while an unfinished conversation can be resumed.

Approval and safety model

PandaDOS exposes the native agent session instead of inventing a second execution engine. You can inspect and intervene at any time.

What you get

Feishu integration

Configure a company app in Admin → Feishu to let colleagues sign in with their own identities, select an authorized project in bot private chat, ask the project PM questions, and receive subscription notifications and approval cards. Login and messaging have independent switches; the admin page provides credential verification, connection status, reconnection, and a test message to the current administrator's linked account.

See the Feishu setup and user guide (Chinese) for permissions, setup, private-chat commands, configuration precedence, troubleshooting, and current limitations.

Run PandaDOS 24/7

An always-on deployment is the best fit for long issue queues:

  1. Use a cloud host or other machine that will not sleep.
  2. Run PandaDOS under systemd with restart-on-failure.
  3. Keep the HTTP service on 127.0.0.1:8802.
  4. Put nginx or Caddy in front with TLS, strong authentication, and WebSocket forwarding.
  5. Register the same host as a local executor, or connect dedicated executor machines through SSH.
  6. Confirm that Claude Code or Codex is authenticated for the service account and that its workspace permissions are intentionally limited.
  7. Back up ~/.panda/ with a WAL-aware SQLite backup method and monitor /healthz.

Do not restart the control plane while an issue is actively changing a repository unless necessary. See DEPLOY.md for the maintained service and operations reference.

Architecture

core ← executor ← issues ← agents
  ↑
web / notify
Directory Responsibility
src/core/ SQLite, migrations, users, conversations, files, skills, and project data
src/executor/ Local and SSH executor boundary
src/issues/ State machine, queue, modules, clarification, and execution engine
src/agents/ Driver-model client, PM decisions, progress, and approval policies
src/notify/ Subscriptions, aggregation, and notification channels
src/web/ HTTP API, WebSocket, terminal bridge, and service composition
ui/ Preact and Vite browser interface
shared/i18n/ Typed catalogs, ICU formatting, locale matching, and timezone formatting

Read the execution model for the runtime architecture and module boundaries.

Security

PandaDOS can expose terminals, files, Git operations, and authenticated coding-agent sessions. Treat access to the web interface as remote shell access.

Development

bun run check-i18n
bun run typecheck
bun test
bun run build-ui

Read AGENTS.md and CLAUDE.md before contributing.

License

PandaDOS is licensed under the Apache License 2.0.

PandaDOS (uniquechao/PandaDOS)

Searching Database…

What is this?A self-hosted control plane that turns Claude Code and Codex into long-running, issue-driven coding agents. You queue outcomes as issues, and it runs them through planning, implementation, verification and delivery while you follow progress in a browser or on your phone.
Is it a replacement for Claude Code or Codex?No. It wraps the native Claude Code or Codex CLI and exposes their real sessions in the browser instead of running a separate engine.
How do I get it running?Paste the install prompt from the README into Claude Code or Codex on the target machine, or follow DEPLOY.md for a manual install. On first start it creates the admin account and writes a one-time token to ~/.panda/admin-token.
What do I need installed first?On the control plane: Bun, Git, tmux and a writable ~/.panda/. Every executor also needs Git, tmux and an authenticated Claude Code or Codex CLI. An OpenAI-compatible driver model is strongly recommended for clarification and summaries.
What is the main security caveat?Browser terminal access gives shell access as the executor account, so isolate untrusted projects with separate accounts or machines. Release bundles also do not include Bun, Git, tmux, Claude Code or Codex, so you install those yourself.
Which systems does it run on?Mac or Linux workstations for occasional local use, and a small always-on Linux host for 24/7 operation. Windows is not mentioned in the README.
Can I run it 24/7 on a cloud server?Yes, that is the recommended setup: run it under systemd on a cloud host, keep the HTTP service on 127.0.0.1:8802 behind nginx or Caddy with TLS, and attach executors over SSH.
Where is my data stored?Its state, including the SQLite database and conversation data, lives in ~/.panda/ on the host where you run it, so you are responsible for backing it up.
Is it free to use?Yes, it is released under the Apache License 2.0. The coding agent subscriptions and any driver model endpoint you add are separate costs.
How does the approval system decide what runs unattended?You choose cautious, balanced or automatic. Balanced mode automatically accepts common safe and reversible development actions, while destructive, irreversible, production, secret-related or ambiguous decisions still come back to you.
Can several projects run at the same time?Independent projects run separately, but work that shares one repository is serialized to reduce conflicting edits. A module can keep one assigned agent.
Does context carry over between issues?Yes. Module knowledge in MODULE.md gives continuity across issues, and projects keep reusable conversations and repository knowledge. An unfinished conversation can be resumed.
Can my team use it from Feishu?Yes. A company Feishu app lets colleagues sign in with their own identities, ask the project PM questions in bot private chat, and receive notifications and approval cards.
What is the goal behind it?To free developers from continuous supervision of coding agents so they can focus on product direction, system design, review and the decisions that need real judgment.
What are similar projects?ovis, zuse, wicked-studio, emdash, kanzo, adhdev, hapi, gastown
Creator
uniquechao
Size
25.9 MB
Stars
897
Age
3mo
Commits · 90 Days