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 в долгоживущих кодовых агентов, работающих по задачам (issues). Вы ставите цели в очередь в виде задач, а система проводит их через планирование, реализацию, проверку и доставку, пока вы следите за ходом работы в браузере или на телефоне.
Это замена Claude Code или Codex?Нет. Это обёртка над нативным CLI Claude Code или Codex, которая показывает их реальные сессии в браузере, а не запускает отдельный движок.
Как это запустить?Вставьте установочный промпт из README в Claude Code или Codex на целевой машине либо следуйте инструкции DEPLOY.md для ручной установки. При первом запуске создаётся учётная запись администратора и записывается одноразовый токен в ~/.panda/admin-token.
Что нужно установить заранее?На панели управления: Bun, Git, tmux и папка ~/.panda/, доступная для записи. На каждом исполнителе также нужны Git, tmux и авторизованный CLI Claude Code или Codex. Для уточнений и сводок настоятельно рекомендуется модель-драйвер с OpenAI-совместимым API.
В чём главное предостережение по безопасности?Доступ к терминалу в браузере даёт доступ к shell от имени учётной записи исполнителя, поэтому изолируйте непроверенные проекты, используя отдельные учётные записи или машины. Релизные сборки также не включают Bun, Git, tmux, Claude Code или Codex, их нужно установить самостоятельно.
На каких системах это работает?На рабочих станциях Mac или Linux для периодического локального использования и на небольшом Linux-сервере, который работает круглосуточно. Windows в README не упоминается.
Можно ли запускать это круглосуточно на облачном сервере?Да, это рекомендуемая схема: запускайте под systemd на облачном хосте, держите HTTP-сервис на 127.0.0.1:8802 за nginx или Caddy с TLS и подключайте исполнителей по SSH.
Где хранятся мои данные?Состояние системы, включая базу SQLite и данные переписок, хранится в ~/.panda/ на хосте, где вы её запускаете, поэтому резервное копирование остаётся на вас.
Это бесплатно?Да, система распространяется по лицензии Apache License 2.0. Подписки на кодовых агентов и любой эндпоинт модели-драйвера, который вы добавите, оплачиваются отдельно.
Как система одобрений решает, что запускается без участия человека?Вы выбираете осторожный, сбалансированный или автоматический режим. В сбалансированном режиме обычные безопасные и обратимые действия при разработке принимаются автоматически, а деструктивные, необратимые, связанные с продакшеном или секретами решения, а также неоднозначные, по-прежнему возвращаются к вам.
Могут ли несколько проектов работать одновременно?Независимые проекты выполняются отдельно, а работа с одним и тем же репозиторием выстраивается в очередь, чтобы снизить количество конфликтующих правок. За модулем может быть закреплён один назначенный агент.
Переносится ли контекст между задачами?Да. Знания модуля в MODULE.md обеспечивают преемственность между задачами, а проекты сохраняют переиспользуемые переписки и знания о репозитории. Незавершённую переписку можно возобновить.
Может ли моя команда пользоваться этим из Feishu?Да. Корпоративное приложение Feishu позволяет коллегам входить под своими учётными записями, задавать вопросы PM проекта в личном чате с ботом, а также получать уведомления и карточки для одобрений.
Какая цель стоит за этим?Освободить разработчиков от постоянного контроля над кодовыми агентами, чтобы они могли сосредоточиться на направлении продукта, проектировании систем, ревью и решениях, которые требуют настоящего суждения.
Какие есть похожие проекты?ovis, zuse, wicked-studio, emdash, kanzo, adhdev, hapi, gastown
Автор
uniquechao
Размер
25.9 MB
Звёзды
897
Возраст
3 мес
Коммиты · 90 дней