# Shelbi

> Do more with your agents — an open source, multi-machine orchestrator built on tmux. Dispatch tasks to a team of agents locally or over SSH.

## Guides

- [Getting Started](https://shelbi.dev/docs/guides/getting-started.md): Install Shelbi, confirm its detected setup plan once, run a task, then scale to a pool of workspaces and hand the loop to the orchestrator.
- [Install](https://shelbi.dev/docs/guides/getting-started/install.md): Install Shelbi with Homebrew on macOS, APT on Ubuntu, or from source for development.
- [Set up your first project](https://shelbi.dev/docs/guides/getting-started/first-project.md): Let Shelbi inspect your repo and machine, confirm one setup card, and land on a dashboard that is ready to use.
- [Run your first task](https://shelbi.dev/docs/guides/getting-started/first-task.md): Open the TUI, add a task, watch a workspace pick it up, and review the diff.
- [Run a multi-workspace dispatch loop](https://shelbi.dev/docs/guides/getting-started/multi-workspace.md): Fill the backlog, promote a stack of cards, and watch the orchestrator keep every workspace in your pool loaded with work in parallel.
- [Set up review workspaces](https://shelbi.dev/docs/guides/getting-started/review-workspaces.md): Tag a workspace, require that tag on your review status, and give the workflow a `review:` serve recipe — the end-to-end path from a `review` tag in your YAML to clicking through a change on a live server and accepting or rejecting it from the review interface.
- [Enable Zen Mode](https://shelbi.dev/docs/guides/getting-started/enable-zen-mode.md): Add local checks, flip the toggle, and let the orchestrator auto-promote work and run the exact-provenance merge flow.
- [Author a custom Shelbi workflow](https://shelbi.dev/docs/guides/getting-started/custom-workflow.md): Edit the orchestrator agent's instructions to encode routing rules, project-specific Zen judgment, and reporting style — the workflow is two markdown files you own.
- [Workflows](https://shelbi.dev/docs/guides/getting-started/workflows.md): A per-project YAML that declares the statuses a task moves through, who owns each one, and what side-effects fire on each transition. The default workflow is the canonical Backlog → Todo → InProgress → Review → Done board; custom workflows are a YAML edit.
- [Understanding Workflows](https://shelbi.dev/docs/guides/understanding-workflows.md): Deep-dives that map a well-known git branching model — trunk-based, git-flow, feature-branch, or forking — onto a Shelbi Workflow. Assumes you already know what a workflow is; each guide gives the statuses, transitions, and orchestrator tweaks for one model.
- [Trunk-based](https://shelbi.dev/docs/guides/understanding-workflows/trunk-based.md): Short-lived branches that merge to main fast, with no separate review column. The merge is action-based, so it pairs naturally with Zen Mode auto-merge.
- [Git-flow](https://shelbi.dev/docs/guides/understanding-workflows/git-flow.md): A long-lived develop integration branch with feature, release, and hotfix branches. Model it as two Shelbi Workflows — features land on develop, releases ship develop to main.
- [Feature-branch (GitHub-flow)](https://shelbi.dev/docs/guides/understanding-workflows/feature-branch.md): Branch per task off main, open a PR, merge back. This is the default Shelbi shape — the workflow every project ships with, written out in full.
- [Forking](https://shelbi.dev/docs/guides/understanding-workflows/forking.md): Contributions arrive as pull requests from forks, and a review gate stands between them and main. Model the maintainer's side — triage, an automated review pass, and a human sign-off before merge.
- [Doing More with Agents](https://shelbi.dev/docs/guides/doing-more-with-agents.md): An agent is just a role, a system prompt plus a skill set, so nothing stops you authoring your own and slotting it into a workflow's statuses. This guide builds an Adversarial Review agent, an automated skeptic that tries to break a change before a human sees it, and wires it into a workflow. Shelbi already ships that reviewer as a preset; the guide is the mechanism behind it.
- [Create the Adversarial Review agent](https://shelbi.dev/docs/guides/doing-more-with-agents/adversarial-review-agent.md): Scaffold an adversarial-review agent with shelbi agent new, understand the instructions.md / preamble / skills model, and drop in a concrete role prompt that tries to break a change instead of approving it.
- [Add it to a workflow](https://shelbi.dev/docs/guides/doing-more-with-agents/add-to-workflow.md): Declare an adversarial-review status in statuses.yaml, reference it from a workflow with owner + agent, and rewire the transitions so a branch flows through the automated skeptic on its way to human review.

## Concepts

- [Agents](https://shelbi.dev/docs/concepts/agents.md): An agent is a role, a system prompt plus a skill set, not the task it's handed or the slot it runs in. Shelbi ships six (orchestrator, developer, review, and the qa, security, and adversarial reviewers); each is a directory you can edit, and you can author more.
- [Workspaces](https://shelbi.dev/docs/concepts/workspaces.md): A workspace is capacity — a persistent slot pinned to a machine, made of one tmux pane and one git worktree. The orchestrator dispatches tasks to it; whichever agent the task calls for runs inside it.
- [Review workspaces](https://shelbi.dev/docs/concepts/review-workspaces.md): Review routing is ordinary tag primitives: a status requires a tag, a workspace carries it, and the task loads onto a matching slot. On top of that, Shelbi ships a dedicated `review:` serve recipe that boots the branch, a review sidebar that lists tasks Ready and Queued for review, and a review interface for clicking through the running app and accepting or rejecting it.
- [Orchestrator](https://shelbi.dev/docs/concepts/orchestrator.md): One agent in window 1 you talk to — it dispatches tasks to workspaces, tails the events log, and reports back. You are the priority-setter; it is the scheduler.
- [The events log](https://shelbi.dev/docs/concepts/events-log.md): An append-only file at ~/.shelbi/events.log — every workspace state change and task status move, in one stream the orchestrator tails.
- [Zen Mode](https://shelbi.dev/docs/concepts/zen-mode.md): The orchestrator triages backlog and lands work through an exact-provenance high-confidence bar.
- [Global vs Repo Config](https://shelbi.dev/docs/concepts/config-modes.md): Two places Shelbi will look for a project's config — under ~/.shelbi/ or committed at <repo>/.shelbi/ — and how to move between them.

## Configuration

- [Project config](https://shelbi.dev/docs/configuration/project.md): Field-by-field reference for a project's YAML — name, repo, machines, orchestrator, agent runners, workspaces, and Zen Mode.
- [Workflow](https://shelbi.dev/docs/configuration/workflow.md): Field-by-field reference for a workflow YAML — statuses (reference-only), initial_status, transitions and their actions, and per-workflow git/zen overrides.
- [Statuses](https://shelbi.dev/docs/configuration/statuses.md): Field-by-field reference for statuses.yaml — the project-wide status catalog that gives every status its id, display name, and category.
- [Global config](https://shelbi.dev/docs/configuration/global.md): Field-by-field reference for the hub-wide files — ~/.shelbi/config.yaml (UI preferences) and ~/.shelbi/keys.yaml (keybindings).

## CLI Reference

- [shelbi init](https://shelbi.dev/docs/cli/init.md): Create a project from Shelbi's detected setup plan, interactively or without prompts for automation.
- [shelbi wizard](https://shelbi.dev/docs/cli/wizard.md): Run the same detected, one-confirmation project setup used by first-run Shelbi.
- [shelbi project](https://shelbi.dev/docs/cli/project.md): Manage projects: add a new one with the detected setup card, or migrate an existing global-mode project into committed in-repo mode.
- [shelbi task](https://shelbi.dev/docs/cli/task.md): Manage the project's Kanban task board — add, list, move, assign, start, and resume tasks from the CLI.
- [shelbi agent](https://shelbi.dev/docs/cli/agent.md): Manage the project's agents — the roles (system prompt + skills) a workspace runs. List them, print one's instructions, scaffold a new one, or open one in your editor.
- [shelbi workspace](https://shelbi.dev/docs/cli/workspace.md): Inspect and control the project's declared workspace pool — list slots with their host, runner, and loaded agent, change slot runners, and stop stuck panes.
- [shelbi workflow](https://shelbi.dev/docs/cli/workflow.md): Manage the per-project workflow YAML files — list, show, scaffold, and edit the status schemas tasks run under.
- [shelbi events](https://shelbi.dev/docs/cli/events.md): Inspect the hub-global workspace-state transition log — the same feed the orchestrator reacts to.
- [shelbi merge](https://shelbi.dev/docs/cli/merge.md): Merge a workspace's branch into the project's default branch, locally or via a GitHub PR.
- [shelbi reload](https://shelbi.dev/docs/cli/reload.md): Respawn the Shelbi-owned tmux panes in place so a freshly installed binary takes effect.
- [shelbi zen](https://shelbi.dev/docs/cli/zen.md): Toggle Zen Mode and run the exact-provenance merge primitives the orchestrator sequences.
- [shelbi open](https://shelbi.dev/docs/cli/open.md): Focus a workspace's tmux pane, creating it (with the agent running) if it doesn't exist yet.
- [shelbi attach](https://shelbi.dev/docs/cli/attach.md): Attach your terminal to a workspace's tmux pane.
- [shelbi status](https://shelbi.dev/docs/cli/status.md): Print the orchestrator's bootstrap snapshot — a concise human summary by default, or the full LLM-consumable payload with --full.
- [shelbi send](https://shelbi.dev/docs/cli/send.md): Inject a follow-up message as keystrokes into a running workspace's tmux pane.
- [shelbi message](https://shelbi.dev/docs/cli/message.md): Append a durable JSON record to a task's file-based message log that its workspace tails, then query or wait for the worker's delivery ack.
- [shelbi config](https://shelbi.dev/docs/cli/config.md): Inspect and validate Shelbi configuration: take a versioned inventory of every owned surface, lint live or staged candidates, and manage keybindings.
- [shelbi daemon](https://shelbi.dev/docs/cli/daemon.md): Run the hub-side daemon that ingests worker messages and appends them to the events log — or manage its platform supervisor.

## Docs

- [AI prompts](https://shelbi.dev/docs/ai-prompts.md): Curated, copyable prompts for handing Shelbi's docs to a coding agent — plus how to wire them into Claude Code, GitHub Copilot, or your agent of choice.
- [Changelog](https://shelbi.dev/docs/changelog.md): Major Shelbi features and when they landed on main, newest first.

## Maintainers

- [System Configuration](https://shelbi.dev/docs/maintainers/system-configuration.md): How Shelbi's reserved configuration skill, system plugin, and config inventory/lint interfaces fit together: ownership, fallback, lint scope, and compatibility.
- [Release Runbook](https://shelbi.dev/docs/maintainers/release.md): Maintainer checklist for tagging, GoReleaser dry runs, package verification, rollback, and signing-key recovery.