PandaDOS README

项目的 README,来自 github.com/uniquechao/PandaDOS。合并为一个 markdown 文件: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)

正在搜索数据库…

这是什么?这是一个自托管的控制平面,可以把 Claude Code 和 Codex 变成长时间运行、以议题驱动的编码智能体。你把目标以议题(issue)的形式加入队列,它会依次完成规划、实现、验证和交付,你则可以在浏览器或手机上查看进度。
它是 Claude Code 或 Codex 的替代品吗?不是。它封装的是原生的 Claude Code 或 Codex 命令行工具,并在浏览器中展示它们真实的会话,而不是另外运行一个独立的引擎。
我该怎么把它跑起来?在目标机器上,把 README 中的安装提示词粘贴到 Claude Code 或 Codex 里;或者按照 DEPLOY.md 手动安装。首次启动时,它会创建管理员账户,并将一次性令牌写入 ~/.panda/admin-token。
我需要先安装什么?控制平面需要:Bun、Git、tmux,以及一个可写的 ~/.panda/ 目录。每个执行端还需要 Git、tmux,以及已完成身份验证的 Claude Code 或 Codex 命令行工具。强烈建议配置一个兼容 OpenAI 的驱动模型,用于澄清问题和生成摘要。
主要的安全注意事项是什么?浏览器终端访问会以执行端账户的身份获得 shell 权限,因此请用独立账户或独立机器隔离不可信的项目。发布包也不包含 Bun、Git、tmux、Claude Code 或 Codex,需要你自行安装。
它能在哪些系统上运行?偶尔在本地使用时,可以用 Mac 或 Linux 工作站;如需 7×24 小时运行,则使用一台小型常开的 Linux 主机。README 中未提及 Windows。
我能在云服务器上全天候运行它吗?可以,这也是推荐的部署方式:在云主机上用 systemd 运行,让 HTTP 服务监听 127.0.0.1:8802,并在其前面放置配有 TLS 的 nginx 或 Caddy,再通过 SSH 连接执行端。
我的数据存放在哪里?它的状态(包括 SQLite 数据库和对话数据)保存在你运行它的主机上的 ~/.panda/ 中,因此备份需要由你自己负责。
使用它是免费的吗?是的,它以 Apache License 2.0 许可证发布。编码智能体的订阅费用,以及你添加的任何驱动模型端点的费用,需要另外支付。
审批系统如何决定哪些操作可以无人值守地运行?你可以选择谨慎、平衡或自动模式。平衡模式会自动批准常见的、安全且可逆的开发操作;而破坏性、不可逆、涉及生产环境、与机密相关或存在歧义的决定,仍会交由你来处理。
能否同时运行多个项目?相互独立的项目可以分别运行,但共享同一代码仓库的工作会被串行处理,以减少冲突的编辑。一个模块可以保留一个指派的智能体。
上下文能否在不同议题之间延续?可以。MODULE.md 中的模块知识让议题之间保持连贯,项目也会保留可复用的对话和代码仓库知识。未完成的对话可以恢复。
我的团队能否通过飞书使用它?可以。企业飞书应用允许同事使用各自的身份登录,在机器人私聊中向项目的 PM 提问,并接收通知和审批卡片。
它背后的目标是什么?让开发者不必持续盯着编码智能体,从而把精力放在产品方向、系统设计、代码审查,以及真正需要判断力的决策上。
有哪些类似的项目?ovis, zuse, wicked-studio, emdash, kanzo, adhdev, hapi, gastown
大小
25.9 MB
星标
897
时长
3个月
提交 · 90 天