Quickstart

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

1. Install and connect

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

From the repo you want the team working on:

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

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:

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

• 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

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.