redpi

██████╗ ███████╗██████╗ ██████╗ ██╗
██╔══██╗██╔════╝██╔══██╗██╔══██╗██║
██████╔╝█████╗  ██║  ██║██████╔╝██║
██╔══██╗██╔══╝  ██║  ██║██╔═══╝ ██║
██║  ██║███████╗██████╔╝██║     ██║
╚═╝  ╚═╝╚══════╝╚═════╝ ╚═╝     ╚═╝
              powered by YITEC

flowchart LR
  Y["⚡ YITEC"] --> R["🔴 RedPi"]
  R --> P["π Pi Coding Agent"]
  R --> N["🧠 9Router"]
  R --> B["🌐 Browser CLI"]

The install-once, auto-applied Pi harness for serious coding teams

9Router · role-based thinking · subagents · skills · browser CLI · memory-lite · advisor-lite · auto-update

---

✨ The promise

RedPi is designed so a teammate does not need to understand model routing, skills, browser tooling, subagents, memory files, or fallback policy before getting value.

curl -fsSL https://raw.githubusercontent.com/ngocanhnckh/redpi/main/install.sh | bash
pi
# RedPi automatically opens first-run provider onboarding

After that, daily use is simply:

pi

RedPi auto-loads and applies the best available harness defaults.

---

🧭 What happens after install?

flowchart TD
  A["👤 User runs pi"] --> B["🔴 RedPi auto-loads"]
  B --> C["🧩 Registers 9router provider"]
  B --> D["🧠 Loads role + thinking policy"]
  B --> E["📚 Loads memory-lite + WATCHDOG guidance"]
  B --> F["🛠️ Exposes setup/config/update/browser tools"]
  B --> G["⬆️ Checks harness + skill updates"]

  C --> H["💬 User asks normally<br/>fix tests · review PR · cheap summarize"]
  D --> H
  E --> H
  F --> H
  G --> H

  H --> I["🎯 RedPi selects role"]
  I --> J["🧪 planner · executor · subagent · reviewer · vision · tiny"]
  J --> K["⚙️ Applies thinking level"]
  K --> L["🚦 Routes to 9Router or native provider"]
  L --> M{"⚠️ rate limit / quota / overload?"}
  M -- "no" --> N["✅ Response"]
  M -- "yes" --> O["🔁 Cooldown + fallback + retry"]
  O --> L

RedPi is designed to auto-create the best usable harness from your available 9Router models and then apply it automatically on future pi starts.

---

🚀 Feature map

	Feature	Default behavior	User effort
🔌	Auto-loaded harness	Installed as a Pi package; normal pi startup loads RedPi.	None after install
🧙	Automatic first-run setup	The first pi launch asks which provider to authenticate; /redpi-setup remains available later.	Guided once
🧠	9Router provider	Registers native provider 9router with OpenAI-compatible /v1 API.	Paste URL/key once
🎯	Auto 9Router role config	Auto-generates planner/executor/reviewer/subagent roles from live /models.	Confirm once
✳️	Claude subscription bridge	Optional pi-claude-bridge provider: use a signed-in Claude Code subscription in Pi.	/redpi-claude
⚙️	Thinking-aware routing	Each role has its own thinking level: off/low/medium/high/etc.	Preconfigured
🤖	Subagent defaults	Installs pi-subagents; defaults cheap workers/scouts/reviewers.	None
🧰	Skills	Installs Matt Pocock skills, the liquid-glass frontend skill, Anthropic's frontend-design skill, the RedPi Playwright browser skill, RedPi's docker-dev skill (services that take a port run in Docker with hot reload and sized memory/CPU limits), and office skills: SenseNova-Skills for slide decks, Excel analysis and HTML reports, plus RedPi's office-files for reading and writing Word, Excel, PowerPoint and PDF files.	None
🖼	Image size guard	Big screenshots and photos no longer break a session: before each model request, images over the size budget are recompressed and the oldest are left out so the whole request stays under 4 MB (gateways answer bigger ones with 413 Request Entity Too Large), without changing the saved session. redpi_image_compress writes a smaller copy of an image file.	None
🌐	Browser automation	One compact Playwright CLI tool, redpi_browser; console/errors/network/screenshot; no MCP overhead. Chromium installs with RedPi (opt out with REDPI_SKIP_BROWSER=1).	None
⏳	Job watcher	Long shell commands (builds, Docker, test suites) are moved to the background after 10 minutes instead of being killed or blocking the agent, with a health report (CPU, disk, network, Docker, errors in the log); the agent is told when they finish or look stuck.	None
🧾	Decisions and lessons	Agents record significant decisions as ADRs (docs/adr/) and what cost them time in docs/lessons-learned.md; every later session in the project reads both, so each run starts from what the last one learned.	None
🪶	Ponytail	Installs ponytail: the "lazy senior dev" mode that makes agents reach for the smallest code that works (stdlib, native features, no speculative abstractions). /ponytail lite|full|ultra|off.	None
🔁	Fallbacks	Detects quota/rate/session/overload errors and retries via fallback chains.	Preconfigured
📚	Memory-lite	Reads capped project/global memory and lets the agent save lessons.	Optional
🕵️	Advisor-lite	Manual reviewer pass via /yitec-review; optional auto-review.	Optional
🗺️	RedPlan + HQ	/redplan: plan with you, approve in a web page (stories, Gantt, critical path, architecture, verified tech), then a named team of Pi worker sessions in tmux builds it while you watch a live board.	One command
📊	Context display bar	Shows approximate context usage in the Pi status bar during requests.	Automatic
⬆️	Auto-update	Checks harness and skill repos on session start.	None
🔐	Public-safe	No vault, no bundled secrets, no committed credentials.	Safer by default

---

⚡ Quick start: easiest path

1. Install once

curl -fsSL https://raw.githubusercontent.com/ngocanhnckh/redpi/main/install.sh | bash

The installer:

• installs/updates Pi to avoid mixed dependency versions
• installs RedPi as a Pi package
• installs pi-subagents
• installs pi-claude-bridge for optional Claude Code subscription access
• installs Matt Pocock skills
• installs the liquid-glass frontend skill
• installs the superpowers subagent workflow skills (subagent-driven-development and friends)
• creates a default MainAgent/SubAgent routing config
• configures Pi skill discovery
• downloads Playwright Chromium for the redpi_browser tool and redpi-browser skill

Skip the browser download for a faster install:

curl -fsSL https://raw.githubusercontent.com/ngocanhnckh/redpi/main/install.sh | REDPI_SKIP_BROWSER=1 bash

Then install the browser later inside Pi:

/redpi-browser-install

2. Start Pi

pi

You should see a compact startup banner:

RedPi · powered by YITEC

If you want the full ASCII banner in the TUI, start Pi with:

REDPI_FULL_BANNER=1 pi

3. Complete automatic first-run onboarding

The first time you start Pi after installing RedPi, it automatically asks which provider you want:

Welcome to RedPi — choose your provider
  9Router (recommended): MainAgent + SubAgent
  Claude Code subscription: Opus + Sonnet
  Other / configure later

Choose the 9Router option to continue into /redpi-setup, then choose:

9Router login / connection

You can rerun the setup wizard later with /redpi-setup.

Paste:

Base URL: https://9router.yitec.dev/v1
API key:  your key

When RedPi asks whether to auto-configure roles from 9Router, choose yes.

RedPi will then:

• fetch live 9Router models/combos
• prefer MainAgent combos for main/heavy-thinking roles when present
• prefer SubAgent combos for fast/subagent/executor roles when present
• ask whether you want to select a model/combo for each role immediately
• set Pi's default provider/model to 9router
• save config under ~/.pi/agent/yitec/model-tiers.json

Restart Pi or run:

/reload

4. Daily use

pi

That's it.

---

🧙 Setup wizard

Run:

/redpi-setup

You get a guided menu:

RedPi setup
  9Router login / connection
  Install Playwright + Chromium
  Configure role models
  Check status
  Done

9Router login / connection

Stores private local config at:

~/.pi/agent/yitec/9router.local.json

Permissions are set to 0600.

Environment variables still override this file:

export NINE_ROUTER_BASE_URL=https://9router.yitec.dev/v1
export NINE_ROUTER_API_KEY=sk-...

Supported env var aliases:

NINE_ROUTER_BASE_URL
ROUTER9_BASE_URL
NINE_ROUTER_API_KEY
ROUTER9_API_KEY
NINEROUTER_API_KEY

🎯 Auto-configure from live 9Router models

If /v1/models works, RedPi can create a best-effort role config automatically. If 9Router exposes named combos like MainAgent and SubAgent, RedPi uses them as first-class defaults:

flowchart LR
  M["🧠 9Router /v1/models"] --> A["🔴 RedPi auto-config"]
  A --> MA["🔥 MainAgent combo<br/>main session + heavy thinking"]
  A --> SA["⚡ SubAgent combo<br/>fast delegated work"]
  MA --> P["🏗️ planner<br/>high thinking"]
  MA --> R["🕵️ reviewer<br/>medium/high thinking"]
  MA --> V["🖼️ vision<br/>vision-capable route"]
  SA --> E["🛠️ executor<br/>low thinking"]
  SA --> S["🤖 subagent<br/>low thinking"]
  SA --> C["📝 commit<br/>low-thinking summaries"]
  SA --> T["🪶 tiny<br/>thinking off"]

After auto-detection, RedPi asks whether you want to choose the model/combo for each role right away. You can accept the recommended default for each role or pick any live 9Router model/combo.

Everything remains editable through:

/redpi-config

---

⚙️ Role-based thinking

RedPi treats models as workers with jobs, not as a single global default.

flowchart TB
  U["💬 User task"] --> Q{"What kind of work?"}
  Q -->|architecture / hard bug| P["🏗️ planner<br/>thinking: high"]
  Q -->|edits / tests| E["🛠️ executor<br/>thinking: low"]
  Q -->|parallel research| S["🤖 subagent<br/>thinking: low"]
  Q -->|critique / PR review| R["🕵️ reviewer<br/>thinking: medium/high"]
  Q -->|screenshots / images| V["🖼️ vision<br/>thinking: medium"]
  Q -->|summaries / commits| C["📝 commit<br/>thinking: low"]
  Q -->|cheap classification| T["🪶 tiny<br/>thinking: off"]

	Role	Best for	Default thinking
🏗️	planner	architecture, plans, hard bugs	high
🛠️	executor	edits, tests, implementation	low
🤖	subagent	parallel cheap tasks	low
🕵️	reviewer	critique, safety, PR review	medium / high
🖼️	vision	screenshots/images	medium
📝	commit	commit messages, summaries	low
🪶	tiny	cheap summaries/classification	off

Magic keywords can override behavior for a single turn:

ultrathink design the migration before editing
cheap summarize this folder
orchestrate inspect auth, database, and frontend in parallel

🧭 Decision model: Jev picks the model for each prompt

Turn it on with /redpi-decision (or /redpi-setup → Decision model (Jev) + Jevgrep). It is off until you turn it on. When you do, RedPi asks for:

1. Provider: OpenRouter, Vercel AI Gateway, TypeSafe, OpenCode Zen, or a custom endpoint that speaks the TypeSafe /systemone protocol.
2. Endpoint: press Enter for the provider's standard URL, or type your own.
3. API key: typed masked and saved owner-only in ~/.pi/agent/yitec/decision-model.json.
4. Model id: press Enter for the provider's Jev model.

RedPi checks the connection before saving.

Jev is TypeSafe's decision model. It writes no text. It answers typed questions (choice, score, yes/no) with calibrated probabilities in about the time of a network round trip, and it is very cheap (about $0.04 per million input tokens, with output free). For every prompt you type, RedPi sends Jev the prompt, plus the start and end of the previous reply so that "yes, do it" inherits the difficulty of what it approves. It asks two questions.

• Which model? Jev chooses one of three tiers, each mapped to a role:

  Jev's choice	Role used
  strong: design, multi-file work, unclear bugs, reviews, long autonomous work	planner
  fast: small, clear edits, known commands, direct questions	executor
  tiny: greetings, acknowledgements, one-line answers	tiny, or executor if unset

• How much effort? A score from 0 (trivial) to 4 (very hard) sets the thinking level within each tier's band:

  Tier	Thinking range
  strong	medium or above
  fast	low to medium
  tiny	off

RedPi leans towards quality:

• A cheaper tier is used only when Jev is at least 60% sure. Otherwise the prompt goes to the strong model.
• If Jev is slow (5-second limit) or unreachable, the prompt goes to the planner as usual.
• The magic keywords (ultrathink, cheap), a model you pinned with /model, and images keep working as before, without asking Jev.

The status line shows each decision, for example executor on 9router/SubAgent:low · jev fast 85% · effort 1.0. Try routing a prompt in the menu shows the decision for any text without sending it to a coding model. /redpi-decision on|off|test|status works without the menu.

🔎 Jevgrep: find code by asking what it does

With the decision model on, the agent gets a redpi_jevgrep tool powered by Jevgrep (jg, MIT). Ask it something like "How are database connections created, pooled, and closed?" and it returns:

• a summary
• the relevant files, ranked by their role
• reading leads
• verbatim source excerpts with line numbers

Jevgrep reports that coding agents solved the same tasks at about 30% lower cost with it.

Setup:

• RedPi installs jg into its own tools folder (~/.pi/agent/yitec/tools) when you turn Jevgrep on. There is no global npm install.
• jg reuses your decision-model key through its supported jg auth --provider … --stdin, kept in a RedPi-only config folder.
• jg only knows the four listed providers. With a custom endpoint, it falls back to your own jg auth.
• Jevgrep can be switched off separately in the menu. When the decision model is off, the tool is hidden from the agent entirely.

Searches send the repository's eligible source (ignored, hidden, dependency and obvious secret files are skipped) to Jev through your provider.

🛡 Jev in the agent loop: command safety check and stale-output pruning

Following the Jev engineering playbook, the routine decisions inside the agent loop go to Jev instead of a full model call. Simple rules in code come first; Jev answers bounded yes/no questions in about 300 ms; you get the irreversible calls. All of this runs only while the decision model is on, and each part has its own switch in /redpi-decision.

Command safety check (default ask). Before bash or a redpi_job start runs, the layers apply in order:

1. Rules in code. Commands that only read (ls, git status, npm test, docker ps…) run without a question, unless they touch credential files such as .env or ~/.ssh. A few catastrophic patterns (rm -rf ~, mkfs, shutdown…) are flagged straight away.
2. One Jev call for everything else, asking four yes/no questions about the same command. Would it:
   • delete data that can't easily be recreated;
   • change something outside this project;
   • expose secrets;
   • publish or send something that can't be taken back?
3. You decide. A command that is 50% or more likely to do one of those asks you: Block it, Allow once, or Allow this exact command for the rest of the session.
   • RedPlan workers never get a dialog. They are blocked only at 80% or more, and are told to ask you through HQ.
   • shadow mode only logs what it would have asked, for trying it out.
   • If Jev is unreachable, nothing is blocked.

On a test set, everything that should be caught was flagged:

• force-pushing main
• npm publish
• cat .env
• docker compose down -v
• pkill -f node
• git reset --hard
• DROP TABLE
• a Slack webhook
• sudo apt-get

Ordinary work ran without a question: rm -rf node_modules, npm install, pushing a feature branch, writing source files.

Stale-output pruning (default on). Once the context passes 30% of the window (and at least 60k tokens), Jev judges older, large tool outputs in one call. It asks whether each one is still needed for the current task.

• Only outputs Jev is at least 90% sure are no longer needed are replaced by a one-line stub, which says what ran so the agent can run it again.
• The newest 8 outputs are never touched.
• Those outputs are then not re-sent on every following turn.
• Decisions are saved in the session, so the prompt prefix stays stable and caching keeps working.

/redpi-jev-stats [days] shows the decisions:

• per kind, which layer answered (code, Jev, you) and the outcomes;
• confidence bands, speed, and the cost of Jev input (about $0.042 per million tokens; output is free);
• how many flagged commands you approved, which tells you when a threshold can go up.

The log (~/.pi/agent/yitec/jev/decisions.jsonl) keeps commands only as hashes unless you set logInputs: true.

Thresholds live in decision-model.json:

Setting	Default	Controls
safety	ask	ask, shadow or off
safetyThreshold	0.5	flag a command at this likelihood
safetyBlockThreshold	0.8	block at this likelihood when nobody can be asked
prune	on	stale-output pruning on or off
pruneAt	0.3	share of the context window before pruning starts
pruneConfidence	0.9	how sure Jev must be that an output is no longer needed

📁 Strict role models for one folder

By default RedPi picks the planner model at the start of every turn and can fail over to other models. When a project needs exact models, open:

/redpi-config

Choice	Applies to	Behavior
📁 This folder	every new session in this folder and its subfolders	strict: only the models you set, no MainAgent default, no fallbacks or failover
⏱ This session only	the current session	strict, forgotten when a new session starts
🌐 Global default	folders without their own config	normal routing with tiers and fallbacks
📦 Project file	.pi/yitec/model-tiers.json (trusted projects)	shared with the repo if committed

Pick a role, choose its model and thinking level, repeat for other roles, then 💾 Save. Roles you don't touch keep the model they currently resolve to, so the saved folder config is complete on its own.

• Folder configs are stored privately in ~/.pi/agent/yitec/folders/, keyed by the folder path, so they need no project trust and never land in the repo.
• Subagent models for the folder are written to the folder's .pi/settings.json, the only per-project place pi-subagents reads.
• New sessions in the folder start directly on its planner model.
• 🔎 Show current routing shows which config is active and the model for each role; 🗑 Remove this folder's config returns the folder to the global defaults.

🛡 Preset profiles: Cybersecurity

/redpi-config → 🛡 Apply a preset profile applies a ready-made strict role setup in one step. Choose where it applies (this folder, this session, global, or the project file), just like a hand-made config.

The Cybersecurity profile is tuned for security research and pentest work:

Role	9Router combo	Thinking
planner	OpenMed	high
executor	norail	high
subagent	norail	xhigh
reviewer	OpenMed	high
vision	OpenMed	high
commit	SubAgent	low
tiny	OpenSmall	off
default	norail	medium

⚠️ Combo names must match exactly. Presets point at 9Router combos by name, so they only work on a 9Router gateway that defines combos named OpenMed, norail, OpenSmall, and SubAgent (as the YITEC 9Router does). Names are case-sensitive. If your gateway names them differently, RedPi lists the missing combos and asks before applying; roles pointing at a missing combo fail until you create it. You can also apply the profile and then rename individual roles with /redpi-config.

Profiles are always strict: exactly these combos, no MainAgent default and no automatic failover. 🔎 Show current routing shows which profile is active.

Manual /model picks stick. If you switch models with /model (or by cycling), RedPi pins that model for the rest of the session: it no longer switches back to the planner model on the next turn and does not fail over. Use /redpi-config → ▶ Resume role routing to unpin.

---

🗺️ RedPlan: plan, approve, then run a team

/redplan build a security triage assistant with LangChain Deep Agents and a Next.js UI

The Pi session you type this into becomes the CEO. It works in four phases:

1. Intake. If the request leaves decisions open, it uses Matt Pocock's grill-me skill and asks you one question at a time. If the request is already a clear spec or prototype, it skips straight to planning.
2. Verify the technology. Every library, framework, or service is checked against its real docs or package registry. The plan records the exact package, what is used from it, the source link, and what it is not ("LangChain Deep Agents" is the deepagents package and create_deep_agent, not "an agent that thinks deeply"). Anything unverified is flagged.
3. Plan. User stories with acceptance criteria, human-readable tasks with estimates and real dependencies, the architecture, and a proposed team. HQ validates it and computes the schedule, critical path, and what can run in parallel.
4. Execute (only after you approve). The CEO starts one worker per parallel lane: a full Pi session in tmux with a name and a role ("Alex, backend developer", "Peter, full-stack developer"). Each works in the shared folder or in its own git worktree and branch, whichever avoids collisions.

Only /redplan plans. Everything else is a quick ticket, done right away with no plan, no approval and no interview:

• In a RedPlan CEO session, a new request you type without /redplan, or send the CEO from HQ, goes on the board as a ticket (redplan_add_ticket). The CEO then gives it to a free worker, spawns a new worker for it, or does it itself if it is small.
• In any other RedPi session, a request is simply done: the agent makes reasonable assumptions, says them in one line, and carries the work through to a verified result. It asks only when it truly cannot go on (missing access, or a choice that would be costly to undo).

Tickets

Add your own work to a run from HQ: + New ticket on the run page takes a title, a description (Markdown), a priority (Urgent, High, Normal, Low), an optional estimate in hours, and attachments (up to 10 files of 10 MB each: choose files, drop them, or paste a screenshot). The ticket goes straight onto the board and the timeline as TK-1, TK-2… and the CEO gets it at once:

• Urgent tickets come before everything else. The CEO acts right away: it assigns the ticket to someone free, and if nobody is free it spawns another worker rather than wait.
• Other tickets go to the first free person, or to a new worker when they shouldn't wait.
• The CEO tells you in one line who is on it. The worker gets your description and the attachments' file paths (images included), so it can open them.
• A ticket on a finished run reopens the run.
• Tickets follow the same review and done rules as planned tasks.

Board cards show the priority (urgent cards in red, first in their column) and a 📎 for attachments. The task panel shows the description, image previews, and downloads. Images open in the browser; other files always download, never render.

The plan page

RedPi prints a link like http://<this-machine>:47291/plans/<id>. It shows:

• expandable stories and tasks
• a flowchart for each feature
• a Gantt chart with the critical path in red, and the parallel waves
• an architecture diagram
• the tech stack with verification status

Flows show how each feature works, step by step, so you can confirm the business logic and the technology before anything is built. For example: "User types username and password (Browser · Next.js login form)" → "POST /auth/login (NestJS AuthController)" → "Compare with the bcrypt hash (NestJS AuthService · Postgres)" → Match? yes: "Issue a JWT in an httpOnly cookie" / no: "Show 'wrong username or password'" → try again.

• Each step names where it runs and what data moves.
• Decisions show every branch.
• Each story links to its flow.
• Below the chart, the same steps are listed as text, one comment button per step.

Big diagrams (flows, Gantt, architecture) sit in a pan/zoom viewer: drag to move, Ctrl/⌘ + scroll or pinch to zoom, Fit to see everything, Expand for a full-window view.

Review it like a document.

• Highlight any text (a task, an acceptance criterion, the summary, a tech choice) and click 💬 Comment.
• Or press the 💬 Comment button on any story, task, acceptance criterion, flow step, risk, tech card or panel to comment on the whole thing.
• On the flows, timeline and architecture tabs, press 💬 Comment on diagram and click anywhere on the chart to drop a numbered comment bubble. RedPi records what you clicked on (for example "Architecture diagram › Support agent" or "Gantt chart › T3 · React widget").
• Comments are saved as drafts as you go, listed in the side panel (click one to jump to it, ✎ to edit or delete), and counted on each tab.
• When you are done, click Send feedback: the CEO session in your terminal receives one message with every comment numbered and anchored to its place, revises the plan, and submits a new version. The terminal shows "HQ: plan feedback received", and you can keep chatting with the CEO there as usual.
• The new version opens with What changed since v1, one line per comment (#1 …), and your earlier comments beside it.
• Approve (optionally "with N notes", which go to the CEO as guidance for the workers) starts execution.

Coding agent per task: Pi, Claude Code, Codex, OpenCode

Every task runs on Pi by default. On the plan page (Stories & tasks), pick a different coding agent for any task, or use Run every task with for all of them. Only agents installed on this machine can be chosen (HQ checks claude --version, codex --version, opencode --version); the others show as "not installed". The approval tells the CEO which task runs where, and the CEO gives each worker tasks of one agent.

• Pi workers are full Pi sessions with RedPi, as before.
• Claude Code, Codex, and OpenCode workers run in tmux too, driven by a small RedPi runner through each tool's own headless, resumable mode: claude -p --resume <session>, codex exec resume <thread>, opencode run --session <id>. Each message from HQ becomes one turn of the same session, so HQ always knows whether the worker is busy, and a crashed worker resumes its session. Nothing is written to your Claude, Codex, or OpenCode config.
• They work with the team through a redpi-hq command in their shell (redpi-hq task T2 in_progress, redpi-hq send ceo "…", redpi-hq send --reply alex "…?" when an answer is needed, redpi-hq team), with the same rules as Pi workers: blocked needs a reason, done needs how it was verified.
• Everything else is the same: board, team chat, Ask (btw) (answered on a fork of the session: --fork-session, codex exec fork, opencode run --fork), Interrupt + send, "needs you" on provider trouble, and Resume. tmux attach shows each turn as it happens, and typing a line there messages the worker. The worker panel also shows the command to open the worker's own session interactively (for example claude --resume <id>).
• They use each tool's own login and default model. Permissions: REDPI_WORKER_AUTONOMY=full (default) matches Pi workers (Claude bypassPermissions, Codex --dangerously-bypass-approvals-and-sandbox, OpenCode --auto); sandboxed keeps each tool's rails (Claude acceptEdits, Codex workspace-write, OpenCode's own rules). Headless runs never stop to ask: anything not allowed fails and the agent adapts.

RedPi HQ dashboard

/hq prints the dashboard link. One hub serves every project on the machine.

Sign in. The first time you run /redplan or /hq, RedPi asks you to choose an HQ username and password (the password is typed masked and stored only as a scrypt hash in ~/.pi/agent/yitec/hq/auth.json, mode 0600). Browsers then sign in on a login page and stay signed in for 30 days. Change the password with /hq-password; that signs every browser out. Scripts can use HTTP Basic auth (curl -u user:password).

Home: all projects. The home page lists every project on the machine as a card: its latest run, progress, blocked tasks, the faces of the workers online, and a red "needs you" count (plans awaiting approval, workers that are stuck or waiting on you). Projects with active runs come first. Switch between Active and All, or search by name or path. Click a project to see its runs, active first, then open a run.

The run page puts the live view (Office, Board, Timeline, Stats or Screenshots) beside the event board, with the team below. It updates in place: the page never jumps while you scroll, and whatever you are typing stays put. The view area keeps one height, so switching views never moves the page.

Every run has five views. Auto-play (the button beside the tabs) fades through them, ten seconds each: handy on a wall screen. It pauses while your pointer is over the view, clicking a tab restarts the ten seconds, and the choice is remembered.

🏢 Office (default once workers exist): an animated pixel office where the team works, in a bright, cosy top-down style (all art is original and drawn in code).

• The office is a building in a small park, with lawns and trees, a pond, a car park and a street with passing cars. The camera never shows past the edge of that world, so there is never an empty margin: the view opens on the whole building with the park filling the rest of the screen. The light theme is daytime; the dark theme is the same office at night, with lit windows, stars and glowing lamps.
• Inside, cream-tiled corridors connect three bands of rooms:
  • along the top: the CEO's glass office with the live whiteboard, the glass Boardroom, the Library (files), the Server room, and on wider floors a huddle room, a focus room, a wellness room and a studio
  • in the middle: an open-plan zone per department, picked from each worker's role (Engineering, Design, Research & Data, Review & QA, Platform & Ops, Security, Docs & Content), labelled on the floor, with breakout nooks in the space left over
  • along the bottom: the Lobby with the front door, reception, the NEEDS YOU mat and the YOU terminal; the Café; and the Lounge
• The CEO plans at the whiteboard, then leads from the glass office; each worker has a desk in their department's zone.
• Working people sit and type, their monitor lit; a bubble shows what they are doing right now ($ pytest -q, > Report.tsx, < README.md) or ... while the model thinks.
• Where they are follows the real tool calls:
  • searching or reading the codebase (grep, find, ls, read, Jevgrep, cd/rg/cat in bash) sends them running to the Library, where they stand at the bookcases
  • builds, tests, installs and deploys often take them to the racks in the Server room
  • writing code (edit, write) brings them straight back to the desk to type
• Nobody sits still for long: every 20–45 seconds at the desk they take a short trip to the servers, the coffee machine, the window, the files, or a teammate's desk, then go back to typing.
• Teammates talking meet in the glass Boardroom. They sit facing each other across the table, the speaker's bubble shows the real message, a reply keeps the meeting going, and the room's screen lights up with the run's progress.
• Idle people wander the lounge and now and then chat over coffee in pairs. The chat is shown as a ... bubble, never invented text.
• Anyone waiting on a long command (a build, Docker, a test suite, a background job) takes a seat in the café with a coffee and a "☕ waiting on …" bubble, and goes back to the desk when it finishes.
• People with nothing left to do (their tasks are done, or the run is finished) head to the Lounge at the bottom: the couch and games console, the ping-pong table, the treadmills and weights, or an armchair or bean bag with a book (arcade cabinets and a pool table fill the corner). Everyone has their own spot (no two people ever share a seat or a chair, in the meeting room too), and they switch activities now and then.
• Anyone blocked, parked, rate-limited, or waiting on a prompt walks to the red NEEDS YOU mat by the door with a !. Someone leaving the team walks out of the front door.
• Every message flies as an envelope from sender to recipient (cyan chat, violet brief, amber decisions, red to or from you); a worker writing to you walks to the YOU terminal to post it.
• The floor grows with the team: department zones grow a bench of two desks at a time, and there are café tables, lounge seats and room on the NEEDS YOU mat for everyone, so nobody ends up sharing a seat or standing on someone else. The building keeps a wide-screen shape as it grows.
• Finishing a task after real work (at least a minute busy) earns confetti.
• People are small chibi characters whose look comes from their name and whose clothes hint at their role (a hoodie, a cardigan, a suit for the CEO); their faces show their mood (focused, blocked, happy when done). Name tags are pills with a status dot (green working, amber idle, red needs you, blue resting) and a context gauge. Speech is a white bubble; tool activity and thinking are dark. Click a person or desk to open them; drag to pan, scroll to zoom, double-click to reset.
• The whiteboard shows the live board as sticky notes, and clouds drift past the windows (stars at night).

📋 Board: the live Kanban (to do, in progress, review, blocked, done), with your tickets marked by priority. Cards stay compact: long titles and notes are cut to a few lines, with the full text on hover. Click a card for its full history: who moved it, when, and why.

📅 Timeline: the approved plan as a Gantt chart with live progress, and your tickets in their own group, placed when they were filed (or started). Each story and task sits where the plan scheduled it (hours from the start, critical path outlined in red), and its bar fills as the work moves: done 100%, in review 90%, not started 0%, and in-progress work estimated from how long finished tasks really took against their estimates (the team's pace), capped at 85% until it is done. The top shows overall progress by estimated hours. Click a row for the task's history.

📈 Stats: the project charts, live from the task history:

• Burndown: estimated hours left (or tasks, without estimates), with a forecast of the finish at the current pace
• Cumulative flow: tasks in each column over time
• Throughput: tasks done per time slot
• Cycle time: from in progress to done per task, with the average; open tasks show how long they have run so far
• Workload: each person's tasks by status
• Status: the board as a donut with % done
• Team activity: tool calls per person in 5-minute cells over the last two hours
• Token use: tokens per person (input, output, cache read, cache write), model calls, the share of input served from cache, and cost when the provider reports it
• Tokens over time: tokens per time slot over the run, by person

📷 Screenshots: what the team checked in the browser, newest first, with who took it, the task, and a caption. Workers on frontend tasks are asked to check their pages with Playwright (redpi_browser) at desktop (1280 px) and phone (390 px) widths and share what they see (redplan_share_screenshot); screenshots from redpi_browser are shared automatically, and reviewers re-check the page themselves. Click one to enlarge it, use the arrow keys for the next, Esc to close.

📣 Event board (beside the view, same height): everything the team does, live. Filter it:

• Updates: what each agent (and the CEO) says it is doing, in its own words ("Reading the auth module to see how sessions are stored"), plus every task move with who moved it and why, background jobs (⏳ started, finished, looks stuck), and shared screenshots (📷). Agents are asked to narrate each meaningful step in one plain sentence.
• Chat: messages between the team and with you; messages to or from you are marked in red, and agents' answers to you are tagged reply.

Messages and updates are rendered as Markdown (headings, lists, code, tables, links) on the event board, in chats, and in panels. Links open in a new tab, and only web and mail links are allowed.

• Tools: every tool call with its duration; failed calls in red.
• All: everything together.

Click a name to open that person, click a task id to see its history, and send a message to the CEO, everyone, or one worker from the box at the bottom.

Around the views:

• Chat, a Slack-like tab: channels on the left (#team: messages to everyone, and what you post there reaches the whole team; #agents: the team talking to each other, read-only; #hq-notes: HQ's alerts, check-ins and notes to the CEO, read-only), then a direct message with the CEO and with each teammate, each with a presence dot and what they are doing. People who left fold into "Left the team". Messages are grouped by sender with day dividers; long ones fold behind Show more. Unread counts show in the sidebar and on the tab, with a New line where you left off. The composer grows as you type (Enter sends, Shift+Enter for a new line, @ mentions a teammate); in a DM, Ask on the side and Interrupt + send work as in the person's panel. Drafts survive live updates, older history loads on demand, ⤢ goes full screen (Esc leaves), and on a phone it is a conversation list, then the conversation.

• your Inbox (the header's Inbox link for every project, and an Inbox tab on each run): only real decisions and questions reach you, each a ticket with a status (Waiting on you, Waiting on the agent, Approved, Declined, Resolved) and a comment thread:

  • blockers: a task the CEO blocked on you (waitingOn: "human"). A worker who says it needs you goes to the CEO first, who decides it or asks you. Reply to answer, or Unblock to send your answer and put the task back to work. Blocked again, the same ticket reopens with the new note.
  • approvals: a plan waiting for you (Approve, or Request changes with a comment), or a yes/no the CEO asked with redplan_ask_human.
  • questions: the CEO's questions to you (redplan_ask_human, or a message ending in ?). Answering in the ticket or in chat both count. A worker's question to you stays in your chat with them.

  Your answer goes to whoever must act (the task's owner, the asker, or the CEO) as [Inbox #N …]; their reply lands in the same thread. Tickets close themselves when the work moves on (the task is unblocked, the alert stops, the plan is decided). A draft you are typing survives live updates.

• no alert strip: problems inside the team (HQ watch findings, stuck, parked or lost workers, sessions that ended, review loops) are the CEO's to handle and never page you; the Inbox tab shows a count when something waits on you, and a red CEO not connected pill next to the run status is the one problem only you can fix. A worker who blocks a task says who must act (waitingOn: a teammate, the CEO, something external, or the human); HQ sends the note to that teammate and always tells the CEO. Without waitingOn, a teammate named in the note is assumed, else the CEO. Cards and panels show "waiting on Alex" and the like

• the team with pixel portraits, the CEO included; each card quotes that person's latest update. Workers who finished or were dismissed leave quietly: no alert, and they fold into Past teammates under the team. Only a worker whose session ended while holding work stays on the team, marked in red. Click anyone (in the team list, on the office floor, or on the event board) to open their panel:

  • Chat (the default) is a messenger: your messages on the right, theirs on the left, the box pinned at the bottom (Enter sends, Shift+Enter for a new line). Every message gets two answers. A quick answer arrives within seconds: a separate call on the agent's model reads its recent work and live state, then answers your question or confirms what it will do and when. Meanwhile your message goes into the live session (without aborting it), and when the agent finishes that turn its full answer is posted in the same chat. A note shows while the full answer is still coming. Both also appear on the event board. This works for Pi, Claude Code, Codex, and OpenCode workers and the CEO alike. Interrupt + send stops their current work first, and Ask on the side (btw) asks without stopping them, for workers and the CEO alike.
  • Details: what they are doing now, their tasks, context use, and their messages with teammates (for the CEO: the plan and what they last told the team).
  • Activity: their updates in their own words, newest first, and for workers the tool waterfall and activity log.

  A worker's panel also has the tmux attach command (Details) and Resume when its session is gone.

• the event board opens on the newest entry and follows new ones while you are at the bottom; scroll up to read and it stays put, with a ↓ N new button to jump back (the worker, CEO and task panels keep their place on live updates too)

The office is drawn on a canvas that pauses when the tab is hidden, respects reduced motion (people stay put: no errands, meetings, or flying envelopes), and is decorative for screen readers: the roster, board, and a live announcement region carry the same information.

Reliability

• Resume after a crash or reboot. Each worker reports its Pi session file. redplan_resume_worker (or the dashboard's Resume button, which asks the CEO) relaunches it in tmux with pi --session <file>, so it keeps its whole conversation. Without a saved session it only starts fresh when asked, and then gets its original brief. Every launch has its own id, so a leftover process can never make a new one look alive.

• Honest task closure. Blocked needs a reason; done needs a note saying how it was verified; a handoff to a teammate needs a note on what is done and what is next, and happens atomically. Every change is kept in the task's history.

• Independent review (default). Builders move tasks to review; a separate reviewer worker checks the exact diff against the acceptance criteria and marks it done or sends it back with findings. Set "review": "self" in the plan to let builders close their own tasks.

• Reviews go straight to a reviewer. When a task reaches review, HQ sends it directly to a reviewer (the one who reviewed it before, else the one with the shortest queue) with the author, their workspace and branch, how they verified it, and the acceptance criteria. The CEO no longer relays each one. The board shows each card's reviewer and how long it has waited. When a reviewer has three tasks queued, the CEO is told to spawn another reviewer.

• Sent-back work returns to its author. A reviewer sends work back with findings (required), and the task goes back to whoever built it, never to the reviewer. The author is told to fix it before anything else, and the same reviewer re-checks it. Reviewers are told to pass work with minor issues listed in the note, and to send it back only for a failed criterion or a real bug.

• Parked workers get nudged. A worker that sits idle while owning in-progress work is nudged after 5 minutes, then the CEO is told, then the CEO is pressed again to fix it (never you) (REDPI_HQ_PARK_MS changes the interval).

• Needs input. Workers report when a rate limit or quota stops them, or when a prompt is waiting in their terminal.

• Managers for big runs. When a plan has more than about 6 tasks over distinct areas (frontend, backend, security, infra…), the CEO leads through managers: redplan_spawn_worker with manager: true and a team starts a manager who owns that area's tasks. A manager is a live Pi with its own staffing tools (spawn, resume, dismiss and ask its own people, assign and hand over its team's tasks). Its people report to it: their blockers, release notes and HQ watch alerts go to the manager first, and the CEO and you hear about an alert only if it persists. A manager may only take its own team's tasks and dismiss its own people, hears once when its whole area is done, and when it leaves, its team reports to the CEO (or to the manager its work was handed to). The team panel, the chat sidebar and redplan_status show each manager with their team.

• Dismissing workers the team no longer needs. redplan_dismiss_worker (CEO only) lays off one worker, several, or every idle one. It is refused while the worker still owns work in progress unless the CEO hands it to a teammate (handoffTo, who gets a brief) or puts it back on the board (returnToBoard). Their reviews go to another reviewer, and their session is told to close. The CEO's check-in lists workers with nothing left for over 10 minutes.

• No session kills. Workers and the CEO cannot run tmux kill-session/kill-server/kill-pane, or pkill/killall of Pi, Node, tmux or RedPi: the command is blocked with what to do instead. Killing a worker's session used to leave its tasks with nobody on them.

• Work with nobody on it. When a worker's session ends while it holds a task (or a review), HQ tells the CEO within 2 minutes which tasks are orphaned and how to fix it (resume them, or hand the work on), and reminds the CEO if it is still orphaned 15 minutes later (REDPI_HQ_ORPHAN_MS). A worker is only counted as gone after two missed tmux checks in a row, and a check that times out on a busy machine does not count.

• Stop when done. When a worker's last task is done, HQ tells it to report and wait until the CEO dismisses it. When the run is marked done or cancelled, every worker is asked to close; any still running a few minutes later has its tmux session closed (REDPI_HQ_STOP_GRACE_MS). A worker whose tmux session is killed exits instead of lingering headless, and a relaunched worker makes the old process stop.

• Quiet chat, quick answers. Messages mark whether they need an answer (needsReply, or a message ending in ?). A teammate's update that asks nothing does not wake a worker whose tasks are all done (it gets it if it has work again); everything else wakes an idle agent at once. Acknowledgements ("thanks", "got it") are discouraged. Two workers messaging each other more than 16 times an hour get a warning; at 30 HQ refuses and asks them to settle it or ask the CEO.

• Reviews end. A task moves to done only from review (the independent reviewer closes it), and a done task can be reopened only by whoever closed it, the CEO, or you, with a note, and only once; after that only you can reopen it.

• Staffing for speed. The CEO staffs one builder per task that can start now (up to 10), each with one task rather than a queue, plus about one reviewer per three builders. It orders the first wave as a thin end-to-end slice, so a first working version arrives early. When tasks that could start are waiting (unassigned, or queued behind a busy teammate) for 3 minutes, HQ tells the CEO exactly what to do: hand them to the free builders by name, or spawn more (REDPI_HQ_MAX_BUILDERS, REDPI_HQ_STAFF_NUDGE_MS, REDPI_HQ_STAFF_GRACE_MS). Spawning also warns when one person owns more than 60% of the critical path's hours.

• HQ watch: problems caught in minutes, not hours. Every minute HQ checks the run, at no token cost, for the patterns that have cost real runs hours:

  • two agents talking in circles (40+ messages to each other in two hours, or refused for messaging too much);
  • an agent burning tokens without moving a card (5M+ in an hour);
  • the same step repeated over and over;
  • a task far past its estimate (twice as long);
  • a task bouncing through review (third time);
  • a board that stopped moving while people work (45 minutes);
  • messages to a worker whose session is gone;
  • open work whose owner's or reviewer's session ended;
  • questions between agents nobody answers (30 minutes).

  Each finding wakes the CEO once, with the diagnosis and what to do. If it is still happening 15 minutes later, the CEO (and the manager first, in a managed team) is reminded, then less often each time (at most every 4 hours); you are not paged for it. It clears itself when the pattern stops. Replayed on a real run, it would have flagged a 19-hour, 651-message loop between two workers about 3 hours into the run, instead of never. Settings: REDPI_HQ_WATCH_MS, REDPI_HQ_ALERT_ESCALATE_MS, REDPI_HQ_CHATTER_2H, REDPI_HQ_BURN_TOKENS, REDPI_HQ_REPEAT, REDPI_HQ_STALL_MS.

• Token checks per task. Each time one agent's spend on one task passes another 5M tokens (5M, 10M, 15M, 20M…, REDPI_HQ_TASK_TOKEN_STEP), HQ asks the CEO to check that nothing is leaking or looping. The alert gives the facts: how long the task has run against its estimate, trips through review, how full the agent's context is, how much was re-read from cache, and the task's total across everyone. A reviewer's tokens count against the task it reviews. Board cards show each task's token spend, and the check-in lists the costliest tasks. Time-based checks miss a fast, expensive loop; this catches it.

• The CEO gets answers in seconds. redplan_ask is the CEO's "by the way": it asks one worker, several, or all. Each worker answers from its own session within seconds (what it is doing, what a command or log showed, what is blocking it) without stopping its live work, and the answers come back as the tool result. Every other message the CEO sends a worker also gets an instant reply first, while the live session takes it in. This works for Pi, Claude Code, Codex and OpenCode workers.

• Check-in every 30 minutes. HQ gives the CEO the numbers: cards moved and finished, what is in progress or in review and for how long, idle builders, open alerts, and tokens per agent. The CEO fixes anything wrong and posts you a 2-3 line status only when something changed or is wrong; otherwise it stays quiet (REDPI_HQ_CHECKIN_MS). The retrospective turns each finding into a lesson.

• Planning nudge. A plan still not submitted 30 minutes into the run gets a nudge to the CEO (REDPI_HQ_PLAN_NUDGE_MS).

• Long commands don't stall the team. Workers run builds and Docker through the job watcher (below): nothing blocks for hours, and no one polls with sleep loops.

• /redplan-doctor checks HQ, the token, tmux, LAN reachability, and every worker's session, workspace, and saved session, with a fix for each problem.

Is the CEO connected? The CEO session checks in with HQ every 30 seconds. If a run's CEO is running an older RedPi (it can't answer on the side or reply to you in HQ), or its terminal has closed, a red CEO not connected pill next to the run status says so (hover for details) and tells you what to do (/reload in its terminal), instead of showing a reply that never comes.

Talk to a worker or the CEO without interrupting them ("btw"). In anyone's panel, Ask on the side asks them anything while they keep working: their RedPi answers on the side with a separate call to the same model, reading the live session's conversation, tasks, and current activity (the CEO also reads the whole team and board). The live session never sees the question. If what you write is really an instruction ("please also make it return 202", "use Postgres instead"), the answer says so and passes it into the live session as a steer, without aborting what it is doing. Send to session delivers your message into the live session as its next message, and Interrupt + send stops the current turn first.

Workers are real Pi sessions, not subagents: they keep running if the CEO is busy, you can attach to them (tmux attach -t '=redpi-<run>-alex', detach with Ctrl-b d), and anything you or a teammate sends arrives in their session as a message. An interrupt stops the current turn first.

Command	What it does
/redplan <request>	Start a run in this session (this session becomes the CEO)
/redplan-status	Plan status, board counts, blocked tasks, workers, links
/redplan-stop	Leave RedPlan mode in this session (workers and the run stay in HQ)
/redplan-doctor	Health check for HQ, tmux, and every worker, with fixes
/hq	Print the HQ dashboard link (asks for an HQ password the first time)
/hq-password	Change the HQ username and password

No collisions between projects. HQ is one small server (port 47291) with one SQLite database in ~/.pi/agent/yitec/hq/. Nothing is written into your projects except worktrees under .redpi-worktrees/ (hidden from git status through .git/info/exclude) and the per-folder subagent settings. Every project, run, worker, and message has its own ID, so several projects, or several runs in one folder, run side by side.

Security. HQ listens on the LAN so you can open it from your laptop. Browsers need your HQ password; RedPi and its workers use the token in ~/.pi/agent/yitec/hq/token. Sessions are signed cookies (HttpOnly), wrong passwords are rate limited (8 per address per 10 minutes), and changes also need a header that other websites cannot send. HQ is plain HTTP, so use it on a network you trust (or behind an HTTPS reverse proxy). Anyone signed in can instruct your agents, which run commands as your user. Set REDPI_HQ_HOST=127.0.0.1 to keep HQ local-only. Before a password is set, the links RedPi prints carry the token instead.

Variable	Default	Purpose
REDPI_HQ_PORT	47291	HQ port
REDPI_HQ_HOST	0.0.0.0	Interface HQ listens on
REDPI_HQ_PUBLIC_HOST	first LAN IPv4	Host used in printed links
REDPI_WORKER_ARGS	(none)	Extra pi flags for worker sessions
REDPI_HQ_STOP_GRACE_MS	180000	How long workers get to close before HQ closes their tmux session
REDPI_HQ_PLAN_NUDGE_MS	1800000	When to nudge a CEO whose plan is still not submitted

Requires tmux for workers.

---

🐳 Services run in Docker

Unless you say otherwise, anything an agent starts that listens on a port runs in a Docker container: a web or API server, a dev server, a database, a queue. The code folder is bind-mounted, so edits hot-reload as usual. Every process the service starts stays inside the container, under a memory, CPU and process limit, so:

• nothing is left running on the host;
• no agent hunts for a stray Node child process to free a port;
• stopping it is one command.

Desktop apps, CLIs, builds and unit tests still run on the host.

The docker-dev skill and its redpi-dev helper (on PATH in RedPi sessions) do the work:

Command	What it does
redpi-dev init	Writes compose.dev.yaml for the project it finds, with a start command that listens on 0.0.0.0 and dependencies in a named volume that reinstall only when the lock file changes. Stacks: Next.js, Vite, Astro, Nuxt, Angular, a plain Node service, FastAPI, Django, Flask, Go.
redpi-dev up	Starts the stack and waits until the port answers, then prints the URL and memory/CPU use against the limits. On failure it prints the error and the last logs.
redpi-dev status	State, URL, use against the limits, restarts, and an out-of-memory kill together with the fix.
redpi-dev logs, restart, exec <service> -- <cmd>	The usual operations, without hunting for PIDs.
redpi-dev down	Removes the stack.
redpi-dev ls	Lists every RedPi dev stack on the machine.

• Limits are sized to the service. A Vite app starts at 1 GB, Next.js at 2 GB, an API at 768 MB, and Postgres at 512 MB. The agent adjusts them from real use: about 1.5× the working peak, and a limit is never removed.
• init: true puts a small init process in each container, which reaps finished child processes so they can't pile up as zombies.
• Files stay yours. The container runs as your user, so files it writes into the repo remain editable.
• Parallel stacks. Each folder and each RedPlan worker gets its own stack name, plus a free host port when the default is taken, so parallel workers never collide. Workers stop their own stack when their task is done.
• Existing setups win. A project with its own dev compose file keeps using it (redpi-dev up --file compose.yaml).
• Without Docker, the agent runs the service directly and says so.

⏳ Long commands: the job watcher

Builds, Docker, and big test suites used to either hit the 10-minute bash timeout (and get killed) or leave the agent sleeping and polling for hours without checking whether anything was still happening. RedPi's bash now watches them instead (Linux):

• Quick commands are unchanged: same output, same exit codes, and a short timeout still kills.
• A command still running after 10 minutes, or silent for 5 minutes with nothing happening, is moved to the background, not stopped. The agent gets the output so far and a health report: elapsed time, the last output and build step, the processes and their CPU and disk I/O, machine CPU, I/O wait, load, memory, free disk (and Docker's disk), network, running containers, error-like lines in the log, and repeated lines. The verdict says whether it looks healthy, slow, or stuck, and what to check next.
• The agent is told when it finishes, or when it starts to look wrong (stuck, errors piling up, out of disk), even while it is doing something else. Nothing is stopped automatically.
• redpi_job lets the agent start a long command in the background, check status, read logs (with grep), wait up to 30 minutes (it returns early when the job finishes or looks wrong), list jobs, and stop one, which needs a stated reason (what it found in the logs or health).
• Esc still stops the command and everything it started.
• In RedPlan, job progress shows on the event board and people waiting on a job sit in the office café.

/jobs shows the running jobs with their health reports, and the latest finished ones. Logs are kept in ~/.pi/agent/yitec/jobs/ (the last 40 jobs, up to three days). A new Pi session in the same folder keeps watching jobs an earlier one left running.

Variable	Default	Purpose
REDPI_WATCH	1	0 turns the watcher off (plain Pi bash)
REDPI_WATCH_CHECKPOINT_SEC	600	When a still-running command moves to the background
REDPI_WATCH_QUIET_SEC	300	How long a command can be silent with nothing happening before it counts as stuck
REDPI_JOB_WAKE	1	0: finish and warning notices wait for the agent's next turn instead of waking it

---

🖼 Image size guard

A conversation full of screenshots can grow past what the model provider accepts in one request (413 Request Entity Too Large / FUNCTION_PAYLOAD_TOO_LARGE; some gateways stop at 4.5 MB), and from then on every request fails, because the images are still in the history. RedPi checks the images before each model request:

• Too big: an image over 700 KB (encoded) or 1,568 px on a side is recompressed, keeping PNG or switching to JPEG, whichever is smaller. Compressed copies are cached, so repeat requests are instant.
• Too many: only the newest images go to the model: at most 8, at most 3 MB of them, and only as much as fits beside the text so the whole request stays under 4 MB; older ones are replaced by a short note saying the agent can read the file again if it still needs it.
• The saved session is not changed: only the outgoing request is. The status bar says when images were compressed or left out.
• redpi_image_compress writes a smaller copy of an image file (shot.png becomes shot.small.png or .jpg), for attaching or sharing a large screenshot.

Tune it with REDPI_IMAGE_MAX_PX, REDPI_IMAGE_MAX_KB, REDPI_IMAGE_MAX_COUNT, REDPI_IMAGE_TOTAL_MB and REDPI_REQUEST_MAX_MB, or turn it off with REDPI_IMAGES=0.

---

🧾 Decisions and lessons learned

Every run leaves the project smarter for the next one:

• ADRs. A significant technical decision (a library or service, the architecture, a data model, an API contract, a trade-off someone could question) is recorded with redpi_adr as docs/adr/NNNN-title.md, with context, the decision, the alternatives, and the consequences. docs/adr/README.md indexes them. Numbers are claimed atomically, so parallel workers never clash; a new record can supersede an old one, and the old one says so.
• Lessons learned. Anything that cost real time or went wrong goes into docs/lessons-learned.md with redpi_lesson: what happened, the lesson, and what to do next time. Entries are newest first and duplicates are skipped.
• Read back every time. In a trusted project, every agent session is told the lessons (newest first, capped) and the list of decisions, and is asked to follow them and to supersede a decision rather than quietly go against it.
• In RedPlan:
  • Workers record their decisions and lessons before moving a task to review, and reviewers send work back when a significant decision has no ADR.
  • Right after approval, the CEO records the plan's key decisions as ADRs.
  • At the end, the CEO holds a retrospective: redplan_finish_run requires at least one lesson for the next run.
  • Claude Code, Codex and OpenCode workers use redpi-hq adr and redpi-hq lesson.

/decisions lists the ADRs and where the lessons are. Commit both folders with the work; they are ordinary Markdown.

---

🤖 Subagents

RedPi installs pi-subagents and configures practical defaults:

oracle   → high-quality planning/research
reviewer → low-cost review pass
scout    → cheap discovery/search
worker   → cheap implementation/support

This is inspired by the useful subagent ergonomics in advanced Pi harnesses, but RedPi keeps the default setup simple and public-safe.

Automatic subagents (on by default)

On its own, pi-subagents only delegates when you ask for it. RedPi turns on automatic subagents by default: it tells the agent it is authorized to spawn subagents without asking, and when it pays off:

• independent research or exploration across several areas → parallel scouts/researchers
• two or more independent tasks or problems → dispatching-parallel-agents, one child per task
• executing a written implementation plan with mostly independent tasks → subagent-driven-development (fresh implementer per task, review after each, final branch review)
• a separate reviewer subagent after a non-trivial implementation, before summarizing

For small, single-file, or tightly coupled changes the agent still works directly. Subagents run on the subagent role's model (for example SubAgent, or norail in the Cybersecurity profile), so automatic delegation means more model calls.

Turn it off or on with /redpi-config → 🤖 Automatic subagents. The switch changes the active config: this session's, else this folder's, else the global one. When off, subagents run only when you ask, or with the orchestrate keyword:

orchestrate review this PR. Send independent subagents to inspect auth, migrations, and frontend.

---

🧠 9Router integration

RedPi registers this provider:

provider: 9router
api: openai-completions
base: https://your-9router/v1

RedPi lists only 9Router combos (models 9Router marks owned_by: "combo"), in Pi's /model list, /redpi-config, and the setup wizard. Raw provider routes such as kr/…, cx/…, or nano/… are hidden, so a gateway with hundreds of routes still shows a short, curated list.

9router/MainAgent
9router/SubAgent
9router/<your-combo>

• Need a raw route anyway? Choose ✍️ manual entry in the picker and type e.g. 9router/cx/gpt-5.6-terra, or start Pi with REDPI_9ROUTER_ALL_MODELS=1 to list everything (a search option appears on long lists).
• The model list is cached in ~/.pi/agent/yitec/9router-models.json, so menus and startup still work when 9Router is slow to answer.

Context windows. RedPi uses the context window that 9Router reports for each combo; Pi's auto-compaction and the ctx bar both work from it.

When 9Router does not know a model's size, it answers exactly 200,000. That is its built-in default, not a real limit. It happens for provider aliases such as syn:large:text and for every combo built on them. RedPi treats that number as unknown:

• the ctx bar shows 200k?;
• a one-time hint says to set the real size.

To set it:

/redpi-context          show the current model's window and where it came from
/redpi-context 1m       set it (1m = 1,048,576; also 256k or an exact number); applies at once
/redpi-context reset    go back to what the provider reports

Sizes you set are saved per model in ~/.pi/agent/yitec/context-windows.json and work for any provider, not only 9Router. Set a combo's size to that of the smallest model it can fall back to, so a fallback never overflows.

Check live status:

/yitec-9router

---

🌐 Browser automation without MCP

RedPi includes optional Playwright browser automation, but intentionally avoids MCP because MCP can be context-heavy. The default RedPi install downloads Chromium using the package's own Playwright version. If you skipped it with REDPI_SKIP_BROWSER=1, redpi_browser prompts to install the runtime when first needed, or you can install it explicitly:

/redpi-browser-install

Instead, RedPi exposes one compact tool:

redpi_browser

That tool executes CLI-style commands:

goto https://example.com --max 2000
text --max 3000
click text=Login
type input[name=q] "redpi 9router" --submit
wait-for [role=dialog]
wait-for-text "Dashboard loaded" --max 2000
ready --timeout 30000
viewport phone                  # or tablet, desktop, 1440x900
screenshot /tmp/redpi-page.png  # visible area; --full for the whole page
console --max 3000
errors --max 3000
network --max 3000
html --max 2000
close                           # close the browser, keep logins
reset                           # close it and clear everything

It knows when a page has loaded. Agents used to screenshot half-rendered pages (a blank app shell, a spinner) and then burn turns re-checking. Now every command that shows the page first waits until it is actually ready: the load event, no requests in flight for half a second (streams such as SSE and websockets do not count), web fonts and visible images loaded, no visible spinner or skeleton, and the DOM unchanged for 400 ms. The first line of the output says which:

ready: page fully loaded (1.4s)
NOT READY after 15s: 1 request still loading (GET http://localhost:3000/api/items); loading indicator visible (div.spinner)

The agent is told to trust ready and to act on the reason when it is not ready, instead of sleeping and retrying.

The page stays open between commands. One Chromium keeps running (each RedPlan worker has its own), so what a click opened is still there for the next text or screenshot, errors logged between commands are still collected, and the window size you set sticks. Agents close it when done; it also closes itself after 10 minutes unused (REDPI_BROWSER_IDLE_MIN) and when the Pi session that used it ends. Stopping it stops the whole Chromium process tree (zygote, GPU, network and renderer helpers), and each Pi start runs redpi-browser.js gc, which clears RedPi browsers left behind by a crash or an older version. A dev server that is down gets a plain "connection refused. Is the dev server running?".

Frontend shortcut:

/redpi-frontend-check http://localhost:3000

It opens the URL, captures page text, console errors, failed/4xx/5xx network responses, and saves a screenshot under .pi/yitec/.

Why this is efficient:

flowchart LR
  A["❌ Browser MCP"] --> A1["many tool schemas"]
  A --> A2["large context surface"]
  A --> A3["more token burn"]

  B["✅ RedPi Browser CLI"] --> B1["one compact tool"]
  B --> B2["CLI command string"]
  B --> B3["clipped output with --max"]

Browser state lives at:

~/.pi/agent/yitec/browser/

Manual CLI use:

node scripts/redpi-browser.js goto https://example.com --max 1000
node scripts/redpi-browser.js text --max 3000

---

🧰 Skills included

RedPi adds skills to Pi settings automatically:

~/.pi/agent/vendor/mattpocock-skills/skills/engineering
~/.pi/agent/vendor/mattpocock-skills/skills/productivity
~/.pi/agent/vendor/liquid-glass-frontend-skill
~/.pi/agent/vendor/superpowers/skills/<name>   (subagent workflow, see below)
~/.pi/agent/vendor/SenseNova-Skills/skills/<name>   (office skills, see below)
<redpi package>/skills/redpi-browser   (Playwright browser skill)
<redpi package>/skills/frontend-design   (Anthropic's frontend-design skill)
<redpi package>/skills/office-files   (read and write Word, Excel, PowerPoint, PDF)
<redpi package>/skills/docker-dev   (run services in Docker with limits, see "Services run in Docker")

Office work. From OpenSenseNova/SenseNova-Skills (MIT), RedPi registers only the office skills (a sparse clone keeps just their folders):

Skill	For
sn-ppt-entry (then sn-ppt-story, sn-ppt-standard, sn-ppt-dazzle or sn-ppt-creative)	A slide deck from a request and optional files: outline, designed HTML pages, speaker notes, PPTX export
sn-ppt-workbench, sn-ppt-doctor, sn-ppt-tools	Edit a deck in the browser, check the setup, search and image fallbacks
sn-da-excel-workflow, sn-da-large-file-analysis	Excel analysis: multi-sheet reads, cleaning, aggregation, exports, files over 10k rows
sn-da-non-spreadsheet-analysis, sn-da-image-caption	Pull tables and figures out of Word, PDF, PowerPoint and images
sn-md-to-html-report	A Markdown report as a designed, self-contained HTML page

Some of them need extras on first use (Python packages, Playwright Chromium, and for image generation or image captions a SenseNova API key in their .env); /skill:sn-ppt-doctor checks the deck setup. Their instructions are partly in Chinese; the agent follows them either way. SenseNova's search, deep-research and image skills are not registered.

RedPi's own office-files skill covers the quick jobs: read any .docx, .xlsx, .pptx or .pdf as Markdown, write a Word document or a plain PowerPoint from Markdown, turn CSV or JSON into a formatted spreadsheet, merge or split PDFs, and render pages to PNG. It runs through uv with open-source libraries (python-docx, openpyxl, python-pptx, pypdf), so nothing is installed into the system Python; LibreOffice, when present, adds Office-to-PDF and formula recalculation.

Design. frontend-design from Anthropic's skills repository (Apache-2.0) ships with RedPi unchanged, for distinctive, intentional UI work. Anthropic's Word, Excel, PowerPoint and PDF skills are not included: their license does not allow copies outside Anthropic's own products, which is why RedPi uses SenseNova's skills and its own office-files instead.

From obra/superpowers (MIT), RedPi registers only the plan-and-subagent workflow: subagent-driven-development, dispatching-parallel-agents, writing-plans, executing-plans, using-git-worktrees, requesting-code-review, finishing-a-development-branch, and verification-before-completion. The rest of superpowers (its TDD, debugging, and using-superpowers meta-skill) is not registered, to avoid overlapping Matt Pocock's skills.

Examples:

/skill:tdd implement this parser with tests
/skill:code-review review the current diff
/skill:domain-modeling design the order/payment model

Pi can also auto-select skills when the task matches their descriptions.

---

📚 Memory-lite

Project memory:

.pi/yitec/memory.md
.pi/yitec/lessons.md

Global memory:

~/.pi/agent/yitec/memory.md
~/.pi/agent/yitec/lessons.md

View memory:

/yitec-memory

Save a lesson through the agent tool:

yitec_remember

Memory is injected with a character cap and labeled as heuristic guidance, so the agent should verify it against the repo before relying on it.

---

🕵️ Advisor-lite and WATCHDOG.md

Run a reviewer pass:

/yitec-review check this auth change for security regressions

Optional watchdog guidance files:

~/.pi/agent/WATCHDOG.md
.pi/WATCHDOG.md
.pi/yitec/WATCHDOG.md

Enable auto-review in config if desired:

{
  "advisor": {
    "enabled": true,
    "autoReview": true,
    "modelRole": "reviewer"
  }
}

---

✳️ Use your Claude Code subscription

RedPi includes pi-claude-bridge, which uses the official locally signed-in Claude Code CLI via Anthropic's Agent SDK. It does not copy, store, or require an Anthropic API key.

1. Sign in once in a normal terminal:

   claude auth login --claudeai
   

2. Start Pi and run:

   /redpi-claude
   

3. Select Use Claude subscription: Opus + Sonnet. To return at any time, run /redpi-claude and select Use 9Router: MainAgent + SubAgent (1M context). RedPi snapshots each profile in ~/.pi/agent/yitec/provider-profiles.json, so your role mappings survive switching. Or select a bridge model directly with /model:

   claude-bridge/claude-opus-5
   claude-bridge/claude-sonnet-5
   

/redpi-claude can also enable the bridge's optional AskClaude delegation tool. The bridge uses your Claude Code subscription quota and its terms; it is independent of 9Router.

Everything RedPi does works on the bridge.

• RedPlan. The CEO protocol, worker briefs and team rules reach Claude. So do RedPi's working rules, the Docker policy and the decisions policy. The bridge builds Claude Code's system prompt from Pi's own parts and drops text that extensions add the usual way, so with the bridge RedPi adds its text at request time, which the bridge passes through. A test runs real Pi and the bridge against a fake claude executable to check this without using your subscription.
• HQ, tools and the Jev safety check. Tool calls run through Pi, so these work as usual.
• Side answers. The CEO's redplan_ask and instant answers run as one-off isolated queries.
• Long commands. RedPi removes the bridge's 120-second bash default, so long builds are watched and moved to the background as with any other provider.
• Jev routing switches between Opus and Sonnet as usual.
• Stale-output pruning is skipped, because Claude Code keeps its own copy of the conversation and the edits would not reach it.

Update the bridge with pi update --extension npm:pi-claude-bridge, then /reload.

🎨 Visuals and context bar

RedPi ships and selects a complete Pi theme named redpi-matrix—not just a colored banner. It replaces the default purple/yellow UI tokens across borders, selection, Markdown, syntax highlighting, tool panels, diffs, thinking levels, and status surfaces with phosphor green, deep green, and signal cyan.

◢ RedPi // YITEC SYSTEMS ONLINE

Preserve your existing Pi theme during installation with:

REDPI_THEME=0 curl -fsSL https://raw.githubusercontent.com/ngocanhnckh/redpi/main/install.sh | bash

Or select a different theme later in /settings.

It also shows a context status indicator during model requests:

ctx █████░░░░░░░░░░░░░ 32,100/200k 16%

Optional display flags:

REDPI_FULL_BANNER=1 pi      # full ASCII logo in TUI
REDPI_COLOR=0 pi            # disable ANSI color in RedPi widgets
REDPI_CONTEXT_WIDGET=1 pi   # show a larger context widget above the editor

⌨️ Commands

	Command	Purpose
🧙	/redpi-setup	Friendly TUI setup wizard for 9Router login, browser install/check, auto role config, and status.
🧙	/yitec-setup	Alias for /redpi-setup.
🎯	/redpi-config	Set role models and thinking for this folder (strict), this session, the project file, or globally; apply preset profiles (Cybersecurity); show or unpin routing.
🎯	/yitec-config	Alias for /redpi-config.
🧭	/redpi-decision	Decision model (Jev): on/off, endpoint and key, prompt routing, thinking from Jev, Jevgrep install/toggle, command safety check (ask/shadow/off), stale-output pruning, connection test, try a prompt. Also on, off, test, status.
📊	/redpi-jev-stats [days]	Jev decisions by kind, layer, outcome and confidence band, with speed and cost.
⬆️	/redpi-update	Force-update RedPi and vendored skill repos.
📏	/redpi-context [1m|256k|reset]	Show or set the current model's context window (for combos whose size 9Router does not know).
🌐	/redpi-browser-install	Install or reinstall the Playwright Chromium runtime.
🖼️	/redpi-frontend-check	Open a frontend URL and report page text, console/errors/network failures, and screenshot path.
✳️	/redpi-claude	Flexibly switch between Claude subscription (Opus/Sonnet) and 9Router MainAgent/SubAgent profiles.
⬆️	/yitec-update	Alias for /redpi-update.
🧠	/yitec-9router	Check 9Router provider, base URL, key presence, and live /models.
📊	/yitec-tiers	Print active model role/tier config.
🩺	/yitec-doctor	Validate role config, providers, and trust status.
🤖	/yitec-agents	Show subagent/reviewer/planner/executor model policy.
📚	/yitec-memory	Show local RedPi memory/lessons.
🕵️	/yitec-review	Run advisor-lite review using reviewer role.
⏳	/jobs	Background jobs with their health reports.
🧾	/decisions	This project's ADRs and where its lessons learned are.
🪶	/ponytail [lite|full|ultra|off]	Minimal-code mode (from the ponytail package).

---

🗂️ Files RedPi manages

flowchart TB
  A["~/.pi/agent"] --> S["⚙️ settings.json<br/>skills/subagents/defaults"]
  A --> Y["🔴 yitec/"]
  Y --> MT["🎯 model-tiers.json<br/>global role config"]
  Y --> NR["🔐 9router.local.json<br/>private URL/key"]
  Y --> DM["🧭 decision-model.json<br/>Jev endpoint/key (0600)"]
  Y --> TL["🔎 tools/ + jevgrep-config/<br/>jg and its credentials"]
  Y --> MEM["📚 memory.md"]
  Y --> LES["🧠 lessons.md"]
  Y --> BR["🌐 browser/<br/>Playwright profile/state"]
  A --> V["📦 vendor/"]
  V --> MS["🧰 mattpocock-skills"]
  V --> LG["🎨 liquid-glass-frontend-skill"]

  P["project repo"] --> PI[".pi/yitec/"]
  PI --> PMT["🎯 model-tiers.json<br/>trusted project override"]
  PI --> PMEM["📚 memory.md"]
  PI --> PLES["🧠 lessons.md"]
  PI --> W["🕵️ WATCHDOG.md"]

---

⚙️ Configuration example

Most users should use /redpi-setup and /redpi-config, not edit JSON manually.

{
  "roles": {
    "planner": { "models": ["9router/cx/gpt-5.6-terra:high"], "thinking": "high" },
    "executor": { "models": ["9router/cx/gpt-5.6-terra:low"], "thinking": "low" },
    "subagent": { "models": ["9router/cx/gpt-5.6-terra:low"], "thinking": "low" },
    "reviewer": { "models": ["9router/cx/gpt-5.6-terra-review:medium"], "thinking": "medium" },
    "vision": { "models": ["9router/cx/gpt-5.6-terra:medium"], "thinking": "medium" },
    "tiny": { "models": ["9router/cx/gpt-5.6-terra:off"], "thinking": "off" }
  },
  "memory": { "enabled": true, "injectionCharLimit": 5000 },
  "autoUpdate": { "enabled": true, "intervalHours": 24 }
}

---

⬆️ Updates

RedPi checks for updates on session start, once per configured interval.

Force update:

/redpi-update

Then restart Pi or run:

/reload

---

🔐 Security model

RedPi is public-repo safe by design:

• no bundled secrets
• no public credential vault
• no web GUI server for private tokens
• 9Router key stored locally or via env vars
• browser profile stored under user-local Pi agent directory
• project config only loads after Pi trusts the project

Never commit:

.env
API keys
OAuth tokens
models.json
9router.local.json

If a key appears in chat, logs, or a public issue, rotate it.

---

✅ Testing

From a checkout:

npm run smoke
npm pack --dry-run

Smoke coverage includes:

• automatic first-run provider onboarding
• chat: channels and direct messages, grouping, unread badges and the New line, @mentions, drafts kept through live updates, read-only channels, full screen, earlier history, phone layout
• inbox: plan approvals, the CEO's blockers on the human, the CEO's questions and yes/no approvals; workers' human blockers, watch alerts and parked workers stay with the CEO; tickets with a status and a thread; answers reach whoever must act; tickets close themselves when the work moves on; the browser UI (no alert strip, Inbox tab count, live updates keep your draft, /inbox across projects, phone layout); redplan_ask_human from the live CEO
• managers: a live manager spawns and dismisses its own builder; its people's blockers, release notes and alerts go to it; own-team tasks only; the team returns to the CEO when it leaves
• dismissing workers: refused while they own work in progress; work handed over (with a brief) or returned to the board; reviews rerouted; the worker leaves quietly; a worker's tmux kill-session is blocked
• HQ watch: agents talking in circles, token burn without progress, repeated steps, review loops, messages to a gone worker, work left with nobody on it and unanswered questions each alert the CEO within seconds, escalate to you when they persist, clear when they stop; the CEO check-in carries the numbers
• office floor scales with the team (1 to 40 people, one department or a mix): a desk, café seat, lounge spot and "needs you" spot for everyone, all reachable from the entrance, none shared
• browser: slow API behind a spinner and late images are waited for, the page stays open between commands (a dialog survives), a never-settling page says what is loading, errors logged between commands are collected, phone width sticks, a down dev server is explained, close and gc leave no Chromium helper processes behind
• context windows: real 9Router windows used as is, its 200k "unknown" default flagged, /redpi-context applies at once (Pi's footer and auto-compaction included), persists and resets
• docker-dev: init detects Next/Vite/FastAPI/Django/Go with sized limits; a Node app runs limited in Docker, hot-reloads an edit, gets its own stack and port per worker, reaps orphaned children, reports an out-of-memory kill, keeps repo files owned by you, and down removes it (Docker part skipped without Docker)
• image guard: big images recompressed before each request, only the newest kept, the whole request under 4 MB even with a long text history, the session untouched, redpi_image_compress
• office-files skill: Markdown to Word and PowerPoint and back, CSV to Excel, PDF merge and page pick (through uv; skipped without it)
• only SenseNova's office skills are registered
• core extension load
• commands/roles/memory in a real Pi TUI
• /redpi-setup one-shot flow in a real Pi TUI
• mocked 9Router /v1/models
• MainAgent/SubAgent auto-mapping
• local 9Router key file creation
• timeout settings patching
• guard that setup does not loop after success
• strict per-folder role config: saved, scoped subagents, global untouched, new sessions start on the folder planner
• manual /model picks stay pinned across turns
• Cybersecurity preset profile applies its exact combos strictly
• automatic subagents: on by default in the agent's system prompt, and the /redpi-config switch reaches the next request
• smoke tests run in a temporary Pi agent directory and never touch ~/.pi/agent
• HQ API: plan validation, critical path and parallelism maths, token auth and CSRF header, approve / request-changes loop, workers, inbox, tasks
• Harness workers: fake claude / codex / opencode binaries speaking each tool's JSON events; the runner takes the brief, the agent moves its card and messages the CEO via redpi-hq, every turn continues the same session, side questions run on a fork (instructions relayed), interrupt stops a stuck turn, provider trouble raises "needs you", and a killed worker resumes its session. The RedPlan end-to-end test also has the CEO spawn a Claude Code worker for a task the human switched to Claude Code.
• Plan review (headless Chromium): text highlights, pins on the architecture and Gantt diagrams, edit, send feedback → one numbered, anchored message to the CEO; the next version shows what changed and the earlier comments; phone layout
• Office (headless Chromium): real heartbeats and messages move the people. Searching sends a worker to the files room and writing code brings them back to type at the desk; teammates talking meet in the meeting room facing each other, with the real message and reply; messages to you go to the YOU terminal; restless trips from the desk and back; idle coffee chats with no invented text; nobody moves under reduced motion; board cards with long paths stay inside their columns; the event board and worker panel keep your reading place through live updates, with a new-entries button; the event board sits beside the office at the same height with working filters; the page never jumps and keeps half-typed text on updates; the CEO opens from the team list and the office floor and takes messages; the seven project charts show exact numbers from the task history and update live; no sideways scroll on a phone
• HQ sign-in: password login, signed sessions (tampering rejected), HTTP Basic, no open redirect, token links retired once a password exists, password change signs browsers out, rate limiting; the projects home API
• RedPlan end to end: /redplan → first-use HQ password (typed masked, never echoed, saved 0600, signs in) → plan → approval → three real Pi workers in tmux (shared folder, git worktree, independent reviewer) → board updates, teammate chat, reports to the CEO, human instructions, btw side questions answered while a turn is running (without touching it) and instructions relayed into the live session, an interrupt that stops a running turn, the review gate, a crash + resume that keeps the worker's conversation, and a healthy doctor report
• HQ rules: closure reasons, review gate, task history, atomic handoffs, stale-launch guard, and the parked-worker ladder; reopen limits, stop when done (and closing workers when the run ends), needs-reply flags and the chat cap between two workers, the critical-path staffing warning, the planning nudge, token use, and screenshots
• Decisions and lessons (in a temporary git repo): numbered ADRs with an index (five parallel writers get five numbers), supersede, lessons newest first without duplicates, the redpi-hq adr/lesson commands, and the lessons and decisions in every trusted session's prompt (never an untrusted one), capped
• Job watcher (against a stub Pi): quick commands unchanged, short timeouts still kill, long commands move to the background with a report instead of blocking, wait returns on finish, finish and stuck messages wake the agent and reach HQ, stop needs a reason, Esc stops the whole job, and errors in the log are called out
• Tickets: validation, attachments (stored privately, images inline, everything else downloads with a sandbox), the CEO told to act at once on urgent ones with who is free, assigning with a brief that carries the whole ticket, a worker spawned for a ticket without a plan, a ticket reopening a finished run; in the browser, filing one with an attachment (urgent first on the board, panel, timeline), Markdown rendered safely on the event board, and the form at phone width
• Office extras: people waiting on a build sit in the café with a coffee and go back when it ends; people with nothing left to do go to the lounge, each to their own spot; token use charts; the Screenshots tab with its lightbox
• Multi-line paste in terminals without bracketed paste: three pasted lines reach the model as one prompt, and a line typed with Enter still submits (real Pi TUI)
• Jev in the agent loop: read-only commands skip Jev, catastrophic ones are caught by rule, four safety questions in one call, you block or allow (once or for the session), workers never get a dialog, shadow/off/Jev-off/Jev-down behave; stale outputs pruned in one call with the newest kept and decisions persisted; the log keeps hashes only
• Decision model (Jev), against a fake Jev and a fake model:
  • /redpi-decision setup: the key is masked and saved 0600, and the connection is checked
  • routing to strong, fast and tiny, including the confidence floor, Jev errors, and magic keywords
  • the previous reply is sent for follow-ups, and turning it off returns to the planner and hides the tool
  • the agent calls redpi_jevgrep, and jg credentials are kept apart from your own
  • REDPI_TEST_REAL_JG=1 also installs the real @dzhng/jevgrep and runs a search through it

Browser CLI test:

node scripts/redpi-browser.js reset
node scripts/redpi-browser.js goto https://example.com --max 500

Expected title:

Example Domain

---

❓ FAQ

Why do I see simple-options.js does not provide an export named clampThinkingBudgetToAnswerRoom?

That means your local Pi install is internally mismatched: one @earendil-works/pi-ai file was upgraded while another stayed old. It is a Pi package dependency issue, not a 9Router key problem.

Repair by reinstalling Pi/RedPi cleanly:

npm install -g --prefix "$HOME/.local" --force --ignore-scripts @earendil-works/pi-coding-agent@latest
curl -fsSL https://raw.githubusercontent.com/ngocanhnckh/redpi/main/install.sh | bash

Then restart:

pi

Is RedPi a fork of Oh My Pi?

No. RedPi copies useful harness ideas, not private implementation wholesale. It focuses on a public-safe, install-once Pi package with 9Router routing and a smaller context footprint.

Did RedPi copy Oh My Pi's model thinking selection?

RedPi implements the same category of feature: model choice is role-aware and thinking-aware. Roles can specify both model and thinking level, and /redpi-config lets users select thinking in the TUI.

Did RedPi copy Oh My Pi's subagent ergonomics?

RedPi installs and configures pi-subagents, adds cheap role defaults, and encourages orchestration through the orchestrate magic keyword. It does not blindly clone every Oh My Pi subagent feature; it keeps defaults simple and maintainable.

Why no MCP browser?

Because browser MCP servers can add large tool schemas and context overhead. RedPi uses a single CLI-backed tool with clipped output.

Can I use native Pi /login instead of 9Router?

Yes. RedPi supports native providers and 9Router. 9Router is recommended for team routing/combos.

---

🙏 Credits

• The RedPi Office engine (walking, camera, bubbles, envelopes, desk screens) and the tool waterfall are ported from munder-difflin (MIT), which builds on the-office (ISC). The bounded, never-empty camera follows the approach of WorkAdventure's camera (no code or assets copied). The building, park, furniture, characters and layout are original RedPi art drawn in code: munder-difflin's LimeZu tilesets and WorkAdventure's tilesets are not redistributable and are not included.
• Worker resume, launch ids, closure reasons and handoffs, parked detection with a wake ladder, the doctor check, and the independent-review norms are adapted from designs in OpenRig (Apache-2.0).
• Prompt routing uses Jev, TypeSafe's decision model; redpi_jevgrep runs Jevgrep (MIT), installed from npm on demand, with usage guidance adapted from its agent skill.
• ponytail (MIT) by Dietrich Gebert is installed as a companion Pi package for minimal-code mode.
• Office skills from SenseNova-Skills (MIT) by SenseNova, installed alongside RedPi.
• The frontend-design skill by Anthropic (Apache-2.0), shipped unchanged.
• Plan-and-subagent workflow skills from obra/superpowers (MIT) and skills from Matt Pocock.

See NOTICE for licenses and details.

---

📍 Repository

https://github.com/ngocanhnckh/redpi

📄 License

MIT