diff --git a/README.md b/README.md index 6e155a2..c5fa69e 100644 --- a/README.md +++ b/README.md @@ -15,129 +15,137 @@ [![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) -![Switching between the rail and department panels](docs/assets/panels.gif) +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. -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. +![Switching between the rail and department panels](docs/assets/panels.gif) ## 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 -export PATH="$HOME/.chief/bin:$PATH" ``` -Then found your first company. Any empty directory will do: +**3.** 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. +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 + +| 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 +160,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`.