# Quickstart (/docs/agent-orchestrator/quickstart)

Sessions are per terminal, not per account. A single `claude` install runs the
whole team.

## 1. Install and connect [#1-install-and-connect]

```sh
pipx install 'aisquare-cli[tui]'         # or: pip install 'aisquare-cli[tui]'
aisquare agents connect claude-code      # installs the lifecycle hooks
aisquare doctor                          # optional: verify the setup
```

`connect` merges five hooks into your Claude Code settings (it never touches
your other settings; `agents disconnect` removes them). If you run parallel
Claude installs through `CLAUDE_CONFIG_DIR` aliases, connect each one:
`aisquare agents connect claude-code --config-dir ~/.claude2`.

## 2. Launch the team [#2-launch-the-team]

From the repo you want the team working on:

```sh
AISQUARE_ROLE=planner claude             # terminal 1: talk to this one
AISQUARE_ROLE=coder   claude             # terminal 2
AISQUARE_ROLE=coder   claude             # terminal 3, as many as you like
AISQUARE_ROLE=runner  claude             # terminal 4: verifies the coders' work
aisquare board -w                        # terminal 5: you, watching live
```

Launching with `AISQUARE_ROLE` activates orchestration for that repo and
registers the session. Each session is told its id, its teammates, and its standing work
cycle automatically. Nobody needs pasted instructions:

* the **planner** keeps the board stocked with tasks,
* **coders** claim the next ready task, do it, and send it to review,
* the **runner** verifies each review item and closes it or reopens it with
  feedback that flows back to whichever coder picks it up next.

## 3. Drive it [#3-drive-it]

Talk to the planner like you would talk to a tech lead. It converts your intent
into tasks. You can also work the board directly from any shell:

```sh
aisquare task add "wire auth" --role coder     # idempotent, safe to re-emit
aisquare task add "ship it" --needs tsk_abc    # held until its dependency is done
aisquare note "JWT it is" --kind decision      # share a decision with everyone
aisquare board                                 # one-shot board (no TUI)
aisquare recall "what did we decide about auth?"
```

## Multi-repo and multi-install setups [#multi-repo-and-multi-install-setups]

* **One execution across several repos** (planner in one, coders in others):
  set `AISQUARE_TEAM_HUB=/path/to/hub` in every session and shell so they all
  share one board. Git worktrees already share their principal repo's board
  automatically.
* **Separate rate limits per session:** run each role under its own
  `CLAUDE_CONFIG_DIR` install and connect each config once.

## If the board looks quiet [#if-the-board-looks-quiet]

1. `aisquare doctor`. It flags missing or outdated hooks and tells you the fix.
2. Sessions load hooks at startup: relaunch any session that was already
   running when you connected.
3. Using a hub? Export `AISQUARE_TEAM_HUB` in the shell where you run
   `aisquare board`, or run it from the hub repo.