<p align="center"><img src="https://raw.githubusercontent.com/cmgmyr/hive/main/docs/assets/logo-card.svg" alt="hive" height="112"></p>
<p align="center"><a href="https://www.npmjs.com/package/@cmgmyr/hive"><img src="https://img.shields.io/npm/v/%40cmgmyr%2Fhive?label=npm" alt="npm"></a> <a href="https://github.com/cmgmyr/hive/actions/workflows/ci.yml"><img src="https://github.com/cmgmyr/hive/actions/workflows/ci.yml/badge.svg" alt="CI"></a></p>

Run a crew of Claude Code and Codex workers from one lead session: visible tmux panes, exact state from hooks, one local SQLite store.

- Visible workers: each one is a real tmux pane you can read and type into.
- Exact state: workers report it through their own CLI's hooks, so nothing polls.
- One local SQLite store: no daemon. The MCP server, hooks, and scheduler make no outbound requests; the CLI contacts npm only to check for updates, and upgrades can download ([details](docs/security.md)).

![hive: a lead plans, spawns workers, and is woken when they finish](https://raw.githubusercontent.com/cmgmyr/hive/main/docs/assets/demo.svg)

## Install

Requirements: macOS, Node `^22.14.0 || >=23.6.0`, [Claude Code](https://claude.com/claude-code), and tmux, which is required: hive runs the lead and every worker in a tmux pane. New here? Start with the [quick start](docs/quickstart.md). codex is optional, only needed if a project opts a worker into it; see [docs/install.md](docs/install.md#codex-workers).

```bash
npm install -g @cmgmyr/hive
hive setup           # pins the hive command to one interpreter, prints the MCP line
brew install tmux
claude mcp add --scope user hive -- "$(command -v node)" "$(npm root -g)/@cmgmyr/hive/dist/index.js"
ln -s "$(npm root -g)/@cmgmyr/hive/claude-plugin" ~/.claude/skills/hive   # optional: session-start kickoff
hive doctor          # verify: node, ABI, tmux, claude, database, hooks all green
```

Working from a clone instead? See [docs/install.md](docs/install.md#from-source).

Put `~/.local/bin` on your PATH below your version manager's block. See [Node version and the interpreter pin](docs/install.md#node-version-and-the-interpreter-pin) for why the order matters.

## First run

Run `cd ~/Code/your-project && hive`. It is shorthand for `hive lead`, and it opens a `lead` window running Claude in this project's tmux session, with the lead session named after the project so your other Claude Code sessions can address it by that name; ask it to triage, and it reads the standing process and proposes work. Spawn workers with `agent_spawn`, and watch or take over any of them with `tmux -CC attach -t hive-main` (or plain `tmux attach`).

## How it works

Each Claude Code session runs its own `hive` MCP server over stdio, and every instance reads and writes one SQLite database (WAL mode) at `~/.hive/hive.db`, so every session sees the same state. There is no daemon. The MCP server, hooks, and scheduler make no outbound requests; the CLI contacts npm only to check for updates, and upgrades can download ([details](docs/security.md)). State is scoped to a project (a directory), resolved from the working directory; a lead spawns workers into tmux panes locked to that project.

## Why not subagents?

| | Subagents | hive workers |
|---|---|---|
| Visibility | report at the end | live terminal you read and type into |
| Persistence | vanish with the conversation | pads and todos outlive every session |
| Lifetime | die with the parent | keep running when the lead detaches |
| Scope | one session | several sessions, terminals, humans |

Hive workers can still use subagents. See [Why not subagents?](docs/concepts.md#why-not-subagents) for the longer answer.

## Running several projects

If you keep more than one project registered, `hive queen` starts a single lead that reads all of them. `hive portfolio` sorts them into waiting on you, stuck, moving and quiet, and `hive next` attaches you to the lead that needs you most. The queen writes into another project only through that project's lead, and hive records each write. [The queen guide](docs/queen.md) covers setup and limits.

## Status

hive is a personal daily-driver tool, released low-key. It is single-user by design and dogfooded daily by its author on macOS. The test suite also runs on Linux in CI, but nobody drives hive there yet. Issues are welcome; for bigger changes, open a discussion first. See [CONTRIBUTING.md](CONTRIBUTING.md). MIT licensed.

## Docs

| Page | What's there |
|---|---|
| [Quick start](docs/quickstart.md) | Zero to a running lead and first worker: requirements, install, the config keys you will touch, first-run fixes |
| [Architecture](docs/architecture.md) | Eight diagrams: process topology, module layering, spawn sequence, wake lifecycle, worker state (with the lead handoff), project scoping, store and server identity |
| [Patterns](docs/patterns.md) | Standing trades, refused approaches, evidence standards, and guard shapes distilled from the project's own decisions and dead-ends |
| [Concepts](docs/concepts.md) | Vocabulary, why not subagents, identity, the workflow, project scope, the shared store |
| [Daily driver](docs/daily-driver.md) | A day with hive, starting a session, watching workers, wake-ups |
| [The queen](docs/queen.md) | One lead across every project: `hive queen`, the portfolio, `hive next`, its reach and audit trail |
| [Commands](docs/commands.md) | Every `hive` subcommand and what it does |
| [Configuration](docs/configuration.md) | The `HIVE_*` environment variables |
| [Profiles](docs/profiles.md) | Standing instructions across projects, the session-start plugin |
| [Projects](docs/projects.md) | `hive init`, `hive.yml`, automatic backups, pads and todos from the shell |
| [Crew sidebar](docs/crew.md) | `lead_sidebar`: a crew pane in a Claude lead, and the read-only `hive crew --json` behind it |
| [Dashboard](docs/dashboard.md) | The generated dashboard: enabling it, where it lives, what it shows |
| [Install details](docs/install.md) | The interpreter pin, iTerm settings, the status line, MCP scope, codex workers, updating, uninstalling |
| [Troubleshooting](docs/troubleshooting.md) | Common errors and their fixes |
| [Security](docs/security.md) | What hive runs, writes and fetches on your machine, with the code to check |
| [Tools](docs/tools.md) | The MCP tools: what each does and when to use it |
| [tmux settings](docs/tmux.md) | Attach modes, pane options, and what to put in `~/.tmux.conf` |
| [Development](docs/development.md) | Building and testing hive itself |

## Updating

Run `hive upgrade` for a global npm install, or `hive upgrade --check` to preview the commands without changing your install. In a git checkout, the default prints the recipe; `hive upgrade --run` executes it. Upgrade reports Claude Code and Codex registration repairs without editing their configs. Restart every session with hive loaded after the upgrade. See [Updating and recovery](docs/install.md#updating).