Pi Dash Wiki
Internal reference docs for contributors and operators of Pi Dash — the AI agent orchestration platform.
These pages explain how the system fits together. They complement (not replace) the top-level README.md (user-facing install + product pitch) and CLAUDE.md (terse repo cheatsheet for coding agents).
New to Pi Dash as a user? Jump straight to 02 — Pi Dash Cloud Quickstart — a 15-minute, task-oriented walkthrough from “I just signed up” to “my first agent run shipped a diff.” The rest of this wiki is for contributors who want to understand or change the codebase.
Start here#
| Doc | What it covers |
|---|---|
| 01 — Architecture overview | The three Pi Dash components, how a task flows end-to-end, where the seams are |
| 02 — Pi Dash Cloud Quickstart | User-facing: sign up → install CLI → connect runner → first agent run |
| 03 — Repository layout | Polyglot monorepo tour: apps/, packages/, runner/, deployments/ |
| 04 — Getting started locally | First-time setup.sh, docker compose, pnpm dev, key URLs, god-mode |
Per-stack deep dives#
| Doc | What it covers |
|---|---|
| 05 — Frontend architecture | React Router 7 apps, shared packages/, MobX stores, conventions |
| 06 — Backend architecture | Django apps, URL tree, ASGI + Channels, Celery, settings layering |
| 07 — Runner architecture | Rust crate layout, daemon supervisor, Codex bridge, IPC, TUI |
| 08 — Cloud ↔ runner protocol | Wire version, welcome frame, auto-update, version pinning |
| 09 — Agent orchestration | orchestration/ + prompting/ + scheduler/: how a work item becomes an agent run |
| 10 — Realtime collaboration | apps/live Yjs/Hocuspocus server and the Tiptap editor |
| 11 — Authentication | Instance admin, OIDC, device-code login, runner enrollment & token rotation |
Operating Pi Dash#
| Doc | What it covers |
|---|---|
| 12 — Deployment topologies | AIO container vs Compose/Swarm vs Kubernetes |
| 13 — Development workflow | pnpm/turbo, OxLint + oxfmt, max-warning ceilings, Husky, catalog deps |
| 14 — Testing | pytest markers, vitest, cargo test, Storybook |
| 15 — Releasing | Runner cargo-dist tags, web release flow, env-var version announcements |
| 16 — Glossary | Workspace, project, work item, cycle, module, runner, pod, run |
17 — pidash CLI reference | Complete reference for every pidash subcommand and flag |
How to contribute to the wiki#
- Edit existing pages in place rather than adding new ones unless a topic needs its own home.
- Keep each page focused on a single subsystem or workflow. Cross-link aggressively.
- Code-level docstrings and
CLAUDE.md/AGENTS.mdare still the source of truth for day-to-day commands. The wiki is for why and how it fits together. - When you rename a directory or rip out a module, grep this wiki and update the references.