Your first team

Ask a lead to find how to run a repository's tests. It will recruit a worker, get the answer, and report back. You'll inspect their messages and shut down the team when you're done.

Install

Gangline runs on Linux and macOS. Put Git, tmux, curl, and a checksum tool (sha256sum or shasum) on PATH for installation. Put claude or codex on PATH for the harness you use; this walkthrough needs both. The GitHub CLI (gh) is needed only if your task uses it. The installer downloads a verified release binary for Linux and macOS on amd64 or arm64. Go compatible with go.mod is needed only if no binary is available for your platform or you build from source. Run each native CLI you plan to use in your repository to complete account login and repository trust.

Install a stable Gangline release:

curl -fsSL https://raw.githubusercontent.com/adambiggs/gangline/main/install.sh | sh

The installer puts gang in ~/.local/bin. If that directory is missing from your PATH, add it to your shell startup file. For the current shell:

export PATH="$HOME/.local/bin:$PATH"
gang --version
gang collars

You should see a version and the claude-code and codex collar names. A collar is a CUE file that tells Gangline how to launch and communicate with a particular harness.

The installer also keeps a release checkout in ~/.local/share/gangline for upgrades. If claude is on PATH, it adds a statusLine command to ~/.claude/settings.json only when that setting is absent; existing settings are preserved. For a Codex-only install, it leaves Claude's settings alone. Set GANGLINE_CLAUDE_STATUSLINE=1 when running the installer to add the setting without claude on PATH. GANGLINE_BIN and GANGLINE_HOME change the binary directory and retained checkout path; see the installer variables.

Give the lead a task

From a shell outside tmux, in the repository you want to inspect, start a named team:

export GANG_SESSION=first-team
gang up -c claude-code

If another Gangline team is already running, also give this team its own state root and tmux socket as shown in the configuration example.

gang up opens the lead window and attaches your terminal to tmux. Type this request into the lead's Claude Code prompt:

Find how to run this repository's tests. Hitch a Codex worker named scout to inspect the test setup without changing files. Ask it to send you the test command and the file paths that support its answer. Summarize the result for me, and leave scout running until I finish checking.

Claude Code may ask you to trust the repository before the lead starts. Codex may show Hooks need review when the lead hitches scout; review that native prompt in scout's window. Either harness may ask for login or command approval. Answer these prompts yourself, then run gang tick from your shell if startup is queued. The startup guide shows how to inspect a blocked pane.

The recorded demo grants Codex full sandbox access so Gangline can observe the peer harness process while delivering a reply. This walkthrough does not set that permission mode. Native permissions apply; the permissions needed for process observation depend on your sandbox and host. Review any native request for access before proceeding.

The lead can now hitch scout, send the assignment, and use its reply to answer you. This is an instruction to the lead; its exact wording and tool choices depend on the agent and your repository's policy.

Watch the work

Use tmux's Ctrl-b w window chooser to visit scout and return to lead. Either agent may ask you to approve a command; answer in that agent's window. A window title marked !name! signals an agent that needs attention. To inspect from your shell, detach with Ctrl-b d and run:

gang roster
gang capture scout
gang capture lead

The roster should list lead and scout. The worker's window shows its inspection, and the lead's window shows the result when it arrives. If you want to narrow the task, run gang attach and tell the lead:

Include only commands documented in this repository. If none is documented, say what you found and leave the command unverified.

Detach again to check message delivery:

gang log --agent scout --type input_finished
gang log --agent lead --type input_finished

A record with status set to delivered confirms that an input was submitted to that recipient. Match the lead's msg-... record to the ID printed when scout sent its report; startup-... records only confirm agent launch. The report in the lead's pane should carry a gang:scout envelope. accepted means the native queue owns the input; it does not confirm a reply. To read all events for the worker, use gang log --agent scout.

Check the result and stop

Read the lead's answer and open the files it names. You should be able to connect its recommended command to the repository's test setup. That answer, the named worker in the roster, and a delivery record verify the workflow.

From your shell, save the log if you want to keep it, then stop the team:

gang log > first-team-log.jsonl
gang roster
gang down first-team
gang teams
unset GANG_SESSION

gang down stops the registered agents and deletes the team's runtime state and history. first-team should be absent from gang teams. For manual staffing, messaging, and stopping a turn, continue with the coordination guide.

Uninstall

Run gang roster before stopping each team with gang down TEAM. Then remove the installed gang command from ~/.local/bin/gang and the retained release checkout at ~/.local/share/gangline. Use the paths selected by GANGLINE_BIN and GANGLINE_HOME if you overrode the defaults. Remove any Gangline config at ${XDG_CONFIG_HOME:-~/.config}/gangline (GANG_CONFIG_DIR) and remaining team state at ${XDG_STATE_HOME:-~/.local/state}/gangline (GANG_STATE_ROOT) that you want to discard. If you selected a separate GANG_TMUX_SOCKET, remove that socket after stopping its team.

If the installer added Claude Code's status line, remove only the statusLine entry pointing to gang statusline from ~/.claude/settings.json; keep the rest of that file and native Claude Code or Codex account data. gang down also removes the team's scheduled watchdog.