- Автор
- uniquechao
- Размер
- 25.9 MB
- Звёзды
- 897
- Обновлён
- КоммитNov 17Релизv2.6.11Nov 17
- Возраст
- 3 мес
- Коммиты · 90 дней
README проекта с github.com/uniquechao/PandaDOS. Одним файлом markdown: README.md.
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

The workspace, users, issues, branches, and project names in the screenshots are sanitized demo data.
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.
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.
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.
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.
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

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.
PandaDOS exposes the native agent session instead of inventing a second execution engine. You can inspect and intervene at any time.
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.
An always-on deployment is the best fit for long issue queues:
127.0.0.1:8802.~/.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.
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.
PandaDOS can expose terminals, files, Git operations, and authenticated coding-agent sessions. Treat access to the web interface as remote shell access.
8802 directly to the public internet..env files, databases, administrator tokens, credentials, SSH private
keys, or agent session data.bun run check-i18n
bun run typecheck
bun test
bun run build-ui
Read AGENTS.md and CLAUDE.md before contributing.
PandaDOS is licensed under the Apache License 2.0.