From 518149939ce281187db156241b68998614849e85 Mon Sep 17 00:00:00 2001 From: Lucy Wolfe Date: Fri, 28 Aug 2026 16:25:26 +0000 Subject: [PATCH 1/5] docs: reorganize the README so a stranger can install without scrolling past a lecture What it is in two sentences, the animation, install, and the first company now lead the page. Depth moved into short skimmable sections or linked docs: the crate table went to docs/ARCHITECTURE.md, which already carries it, and the long GIF caption and quick-start asides were trimmed. New: an Everyday commands table, derived from the routed operator verbs in chief-cli's OPERATOR_VERBS, and a Contributing section naming the two open workstreams (finishing apps/web, and multi-machine hosting so one busy company stops pegging a single box's CPU) plus the issue tracker and CONTRIBUTING.md. Every command documented was checked against install.sh and the routed verb table. The Pi floor line keeps Pi and 0.80.10 on one line for pi-floor-single-definition.test.mjs. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01TMNbixeJo8rpeijUKyxhD2 Signed-off-by: Lucy Wolfe --- README.md | 170 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 87 insertions(+), 83 deletions(-) diff --git a/README.md b/README.md index 6e155a2..2e5c11b 100644 --- a/README.md +++ b/README.md @@ -15,20 +15,24 @@ [![Discussions](https://img.shields.io/github/discussions/tribes-protocol/chief)](https://github.com/tribes-protocol/chief/discussions) [Quick start](#quick-start) · -[What is a company](docs/WHAT_IS_A_COMPANY.md) · -[Architecture](#architecture-in-sixty-seconds) · -[Examples](examples/) · -[Contributing](CONTRIBUTING.md) +[Commands](#everyday-commands) · +[How it works](#how-it-works) · +[Examples](#examples) · +[Contributing](#contributing) +chief creates and operates a persistent company of AI agents: a CEO, a +recursive tree of departments, and stable people who each have a name, a job +title, a mandate, and a private memory. You talk to them, and they talk to +each other. + ![Switching between the rail and department panels](docs/assets/panels.gif) -The asciinema recording behind that GIF is -[`docs/assets/panels.cast`](docs/assets/panels.cast), and it is a **capture of -a running company** — a real `chiefd`, a real rail, real tmux panes, and real -Pi agents answering for themselves. Nothing in it is drawn by hand. The -company — Northwind Robotics — and everyone in it are fictional. +A capture of a running company: a real `chiefd`, real tmux panes, and +real Pi agents answering for themselves. The company, Northwind Robotics, and +everyone in it are fictional. The asciinema recording behind the GIF is +[`docs/assets/panels.cast`](docs/assets/panels.cast). ## Quick start @@ -41,103 +45,102 @@ curl -fsSL https://chief.zipbox.ai/install.sh | sh export PATH="$HOME/.chief/bin:$PATH" ``` -Then found your first company. Any empty directory will do: +Found your first company in any empty directory: ```bash mkdir acme && cd acme && chief ``` -That opens **Founder**. Founder learns exactly two things — the company's -**name** and its **purpose** — then creates the company and boots its CEO. -**The CEO is what builds the organisation**; Founder deliberately designs -nothing, and the founding boot is told so in as many words. -So tell the CEO what you want built — "a three-person research desk that -writes me a daily market brief" — and it creates the departments, appoints -the heads and hires the people. Come back later with `chief` in the same -directory. - -`chief ls` lists every company on the box; `chief upgrade` installs the latest -release over this one. +That opens **Founder**, which asks for exactly two things: the company's name +and its purpose. It then boots the CEO, and the CEO builds the organisation. +Tell it what you want, for example "a three-person research desk that writes +me a daily market brief", and it creates the departments, appoints the heads, +and hires the people. Come back later with `chief` in the same directory. + +## Everyday commands + +| Command | What it does | +| --- | --- | +| `chief` | Found a company here, or start and attach the one that exists | +| `chief ls` | List every company on this machine and its state | +| `chief attach` | Put this terminal in this company's CEO, starting it if stopped | +| `chief stop` | Stop this company's runtime, then its daemon | +| `chief stand-down [reason]` | Stop everyone except the CEO; queued mail is held, not lost | +| `chief resume` | Let the company work again after a stand-down | +| `chief reset [--yes]` | Shed the company back to CEO-only, deleting nothing | +| `chief rm [--yes]` | Remove the company for good | +| `chief upgrade [--check\|--rollback]` | Install the latest release over this one | + +The full command surface, the disk layout, and the runtime are in +[`docs/OPERATING.md`](docs/OPERATING.md). ## Why chief -Most tools orchestrate agents as a flat pool of workers, or as panes in a -multiplexer that knows a process is running but not who it is. chief runs a -real **company**: a CEO, a recursive tree of departments, and stable people who -each have a name, a job title, a mandate, a private memory, and their own agent -home. You talk to them, and they talk to each other. - -Everything durable is a row in that directory's own SQLite database — not a -process, not a scrollback buffer, not a JSON file. A company survives being -closed, moved, and reopened, because **the company is the database**. Nothing on -disk records which window or pane anybody is in; placement is derived from the -org chart on every pass. - -And the whole thing is two programs you meet, plus **`beacond`**, a small -discovery daemon the installer puts beside them. **`chiefd`** is the backend: one daemon per -company directory, and it decides *who should be running*. **`chief`** is the -client: it owns tmux and your terminal, and it decides *where they are shown*. -The daemon cannot see a terminal and the client cannot decide policy, so an -observation is always a report from a client and never a second copy of the -truth. +Most tools orchestrate agents as a flat pool of workers. chief runs a real +organisation, and everything durable in it is a row in the directory's own +SQLite database. A company survives being closed, moved, and reopened, +because the company is the database. - A CEO and recursive departments, with named heads and specialists. - One private Pi history, workspace, inbox, and memory directory per person. -- Placement derived from the org chart, never from ad-hoc panes. -- Explicit skills and tools for every hire; models are Pi's own. +- Messages and reminders that survive a restart. - Durable assignments with acknowledgement, progress, escalation, and result - delivery — instead of relying on chat timing. -- Messages and reminders that survive a restart: a message is how work reaches - a person, and a reminder is how a person comes back to it. -- Safe stop, restart, transfer, and removal that keep a person's history until - you explicitly delete it. + delivery. +- Safe stop, restart, transfer, and removal that keep a person's history + until you explicitly delete it. - Parking: a quiet person costs no compute and loses nothing. -## Architecture in sixty seconds - -A company is a directory. Running `chief` in it starts one `chiefd` for that -directory, which opens `.chief/db/chief.db` and runs a supervisor loop of six -duties — reconcile, health, mailbox wake, deadlines, reminders, memory. That -loop decides which people should be active right now, and publishes the answer. +## How it works -The client asks for that answer over HTTP, compares it to the tmux session it -can actually see, and applies the difference: it opens panes, moves them, and -closes them. Every person in a pane is a Pi agent with its own home. `beacond` -is a small box-wide registry that answers "which daemon serves this company", -and admits exactly one daemon per company. +A company is a directory. Running `chief` in it starts one **`chiefd`** for +that directory: a daemon that opens `.chief/db/chief.db` and decides *who +should be running*. The **`chief`** client owns tmux and decides *where they +are shown*: it asks the daemon over HTTP, compares the answer to the session +it can actually see, and opens, moves, and closes panes. Every person in a +pane is a Pi agent with its own home. **`beacond`**, a small box-wide +registry, answers "which daemon serves this company" and admits exactly one +daemon per company. ![How chief, chiefd, beacond and the Pi panes fit together](docs/assets/architecture.svg) -| Where | What it owns | -| --- | --- | -| `apps/chiefd/crates/chiefd-daemon` | The backend binary — `chiefd`. | -| `apps/chiefd/crates/chiefd-core` | The typed docstore: the manifest and every ledger, as SQL. | -| `apps/chiefd/crates/chiefd-api` | The HTTP surface over that store. | -| `apps/chiefd/crates/chiefd-host` | Everything the backend touches on the machine. It names no tmux. | -| `apps/chiefd/crates/chief-cli` | The operator client — `chief`: tmux, the terminal, and every verb. | -| `apps/chiefd/crates/beacond` | The small no-auth discovery daemon. | -| `apps/web` | The browser client, and a full second host for a person. | -| `packages/chiefing` | The TypeScript client of chiefd and beacond. No business logic above it. | -| `packages/piing` | Pi artifacts: the skills and extensions copied into Pi homes. | - -> **Note:** `apps/web`, the browser host, is **not live and currently broken**. -> The terminal client is the product today. The web host stays in the tree -> because the daemon/client split is designed for a second host; see -> [`apps/web/README.md`](apps/web/README.md) for status. +The code map, crate by crate, is in +[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). ## Examples -Three companies you can copy and found in a minute — see +Three companies you can copy and found in a minute. See [`examples/`](examples/). | Example | The company | | --- | --- | -| [`trading-desk`](examples/trading-desk/) | **Meridian Desk** — a paper-trading research desk. Research, Execution, and Risk, with Risk reviewing every trade memo. | -| [`growth-studio`](examples/growth-studio/) | **Signal & Co.** — a growth and social agency. Content, Distribution, and a one-person Analytics unit. | -| [`oss-maintainers`](examples/oss-maintainers/) | **Patchwork Labs** — a company that maintains an open-source repo. Triage, Engineering, and Release. | +| [`trading-desk`](examples/trading-desk/) | **Meridian Desk**, a paper-trading research desk: Research, Execution, and Risk, with Risk reviewing every trade memo. | +| [`growth-studio`](examples/growth-studio/) | **Signal & Co.**, a growth and social agency: Content, Distribution, and a one-person Analytics unit. | +| [`oss-maintainers`](examples/oss-maintainers/) | **Patchwork Labs**, a company that maintains an open-source repo: Triage, Engineering, and Release. | + +## Contributing + +Contributions are welcome, and two large pieces of work are open right now. + +**1. Finish the web client.** [`apps/web`](apps/web/) is a Next.js browser +host for a company. Real code exists: the API and SSE client services, the +hooks and providers, and unit suites that run in CI on every pull request. +But it does not build a working host today, nothing a user installs contains +it, and the terminal client is the product. +[`apps/web/README.md`](apps/web/README.md) describes what it was built to do +and asks that a revival start with a +[Discussion](https://github.com/tribes-protocol/chief/discussions), with a +written account of what actually breaks. + +**2. Run departments on different machines.** Today an entire company runs on +the machine where its directory lives, and a company with many active people +pegs that one machine's CPU. The goal is to let different departments be +hosted on different machines. No design exists yet; bring proposals to +[Discussions](https://github.com/tribes-protocol/chief/discussions). + +Smaller work lives in the +[issue tracker](https://github.com/tribes-protocol/chief/issues). Setup, +conventions, and the pull-request contract are in +[`CONTRIBUTING.md`](CONTRIBUTING.md). ## Where to read next @@ -152,6 +155,7 @@ Three companies you can copy and found in a minute — see ## Licence -Apache-2.0 — see [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE). Contributions are -accepted under the [Developer Certificate of Origin](CONTRIBUTING.md#developer-certificate-of-origin); +Apache-2.0. See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE). Contributions +are accepted under the +[Developer Certificate of Origin](CONTRIBUTING.md#developer-certificate-of-origin); sign your commits with `git commit --signoff`. From 254c6484701b3d3b3fe484ab6e30bd7c8d55a244 Mon Sep 17 00:00:00 2001 From: Lucy Wolfe Date: Fri, 28 Aug 2026 16:29:25 +0000 Subject: [PATCH 2/5] docs: drop the manual PATH export from the quick start The installer already edits the shell profile and reports exactly which file it touched, so the extra line was a second copy of work the script does itself. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01TMNbixeJo8rpeijUKyxhD2 Signed-off-by: Lucy Wolfe --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 2e5c11b..ea36b4d 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,6 @@ You need macOS or Linux, [`tmux`](https://github.com/tmux/tmux), and ```bash curl -fsSL https://chief.zipbox.ai/install.sh | sh -export PATH="$HOME/.chief/bin:$PATH" ``` Found your first company in any empty directory: From ac50ca34c71b6003a81e87e867e96b1e586e22fa Mon Sep 17 00:00:00 2001 From: Lucy Wolfe Date: Fri, 28 Aug 2026 16:30:22 +0000 Subject: [PATCH 3/5] docs: drop the GIF caption The animation speaks for itself; the recording provenance note is not needed on the front page. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01TMNbixeJo8rpeijUKyxhD2 Signed-off-by: Lucy Wolfe --- README.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/README.md b/README.md index ea36b4d..b9d1403 100644 --- a/README.md +++ b/README.md @@ -29,11 +29,6 @@ each other. ![Switching between the rail and department panels](docs/assets/panels.gif) -A capture of a running company: a real `chiefd`, real tmux panes, and -real Pi agents answering for themselves. The company, Northwind Robotics, and -everyone in it are fictional. The asciinema recording behind the GIF is -[`docs/assets/panels.cast`](docs/assets/panels.cast). - ## Quick start You need macOS or Linux, [`tmux`](https://github.com/tmux/tmux), and From 04f2941f6cabfe79dd5058bf4f37dab16486e2eb Mon Sep 17 00:00:00 2001 From: Lucy Wolfe Date: Fri, 28 Aug 2026 16:34:12 +0000 Subject: [PATCH 4/5] docs: number the quick start and give the Pi install its own code block Three steps a stranger can paste in order: Pi, chief, first company. The Pi floor stays on one line with the name for the pi-floor guard. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01TMNbixeJo8rpeijUKyxhD2 Signed-off-by: Lucy Wolfe --- README.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index b9d1403..bd3893a 100644 --- a/README.md +++ b/README.md @@ -31,15 +31,21 @@ each other. ## Quick start -You need macOS or Linux, [`tmux`](https://github.com/tmux/tmux), and -[Pi](https://github.com/earendil-works/pi) 0.80.10 or newer -(`npm install -g --ignore-scripts @earendil-works/pi-coding-agent`). +You need macOS or Linux and [`tmux`](https://github.com/tmux/tmux). + +**1.** Install [Pi](https://github.com/earendil-works/pi), the agent runtime, at 0.80.10 or newer: + +```bash +npm install -g --ignore-scripts @earendil-works/pi-coding-agent +``` + +**2.** Install chief: ```bash curl -fsSL https://chief.zipbox.ai/install.sh | sh ``` -Found your first company in any empty directory: +**3.** Found your first company in any empty directory: ```bash mkdir acme && cd acme && chief From 038e60ac1bbe0c2db7447d7802bfb3a0f96b4d05 Mon Sep 17 00:00:00 2001 From: Lucy Wolfe Date: Fri, 28 Aug 2026 16:35:03 +0000 Subject: [PATCH 5/5] docs: the quick start explains the Founder-to-CEO transition Step 3 says what the first run is (Founder, two questions, then the CEO boots) and step 4 says what every later run is (the same bare chief starts and attaches the company). The transition is the part a stranger cannot guess from the command alone. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01TMNbixeJo8rpeijUKyxhD2 Signed-off-by: Lucy Wolfe --- README.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index bd3893a..c5fa69e 100644 --- a/README.md +++ b/README.md @@ -51,11 +51,16 @@ curl -fsSL https://chief.zipbox.ai/install.sh | sh mkdir acme && cd acme && chief ``` -That opens **Founder**, which asks for exactly two things: the company's name -and its purpose. It then boots the CEO, and the CEO builds the organisation. -Tell it what you want, for example "a three-person research desk that writes -me a daily market brief", and it creates the departments, appoints the heads, -and hires the people. Come back later with `chief` in the same directory. +With no company in the directory, `chief` opens **Founder**. Founder asks for +exactly two things, the company's name and its purpose, then creates the +company and boots its CEO. Founder designs nothing; the CEO is what builds +the organisation. + +**4.** Talk to the CEO. Tell it what you want, for example "a three-person +research desk that writes me a daily market brief", and it creates the +departments, appoints the heads, and hires the people. Once the company +exists, Founder never appears again: from then on, `chief` in that directory +starts the company if it is stopped and attaches your terminal to the CEO. ## Everyday commands