Skip to content
Barry Guides
WIP

This guide is a work in progress. Barry is also a work in progress.

Run sessions

Use this when you work in Barry day to day and want to start, name, leave, and pick up sessions, or run one prompt without opening a session.

A session is your identity running a harness under a policy.

Before you begin

Section titled “Before you begin”

Build a Barry. These commands act as the bonanza identity from that guide; use your own identity’s command in its place.

Start a session

Section titled “Start a session”

To start a session, run:

Terminal
bonanza session start

Running bonanza on its own does the same thing. Barry asks which traits to add, then launches the harness. To skip the picker, name the traits:

Terminal
bonanza session start --traits memory,git

Other ways to shape what the session can do:

Flag Effect
--all Grant every packed bag’s tools and skip the picker
-r, --read Read-only: every tool under the readonly bound
--bound <name> Start under a named bound (see barry bound list)
-n, --none Skip trait and directive selection; identity bags still grant their tools
-d, --directive Set a one-line directive for the session

Pick the harness and model

Section titled “Pick the harness and model”

A session runs the harness your identity marks as its default. Override it per session:

Terminal
bonanza session start --codex
bonanza session start --ollama -m qwen3:8b

--claude or --claude-code, --codex, --cursor, --opencode, and --antigravity or --agy select a harness. Each installed adapter adds its own flag, so barry adapter list shows the harnesses you can name, such as Pi. --adapter takes any installed adapter by ID or alias. --ollama, --zai, and --llamacpp select an endpoint; -m names the model. Adapters covers how these resolve.

Name a session

Section titled “Name a session”

A named session is quick to find when you resume. Name it at start, or let Barry prompt you when you exit:

Terminal
bonanza session start -N nightly-triage

Leave and resume

Section titled “Leave and resume”

Type /exit to leave a session. To pick one up again:

Terminal
bonanza session resume

resume shows a picker of recent sessions. To skip the picker, pass --last for the most recent session in the current directory. resume takes the same trait, harness, and endpoint flags as start, but not -m, --bound, or -d.

Run one prompt, non-interactively

Section titled “Run one prompt, non-interactively”

To run a single prompt and get the result back without an interactive session, use session prompt:

Terminal
bonanza session prompt --prompt "Summarize today's commits" --max-turns 5

This runs through the Claude Agent SDK. It takes --traits, --model, and --cwd to set the working directory.

More session commands

Section titled “More session commands”

These cover less common needs. The session command reference lists every flag.

Command Use it to
bonanza session start --no-ui Start a session in the background, with no renderer
bonanza session adopt <session_id> Move a terminal UI’s session to the background; close the UI first
bonanza session archive Hide a session from the resume picker, or every closed one with --all-closed
bonanza track setup cursor Track a session Barry did not launch, such as one in Cursor, through that tool’s hooks

bonanza track plan cursor shows what track setup would write and changes nothing. The track command reference covers removing the hooks again.

Verify

Section titled “Verify”

To see the sessions running now, run:

Terminal
bonanza session list

Each entry shows the session’s name or ID, its status, such as running, and the directory it runs in.

If it fails

Section titled “If it fails”
  • The session does not start, or the harness is missing. Install the harness’s own command-line tool, check it with barry adapter doctor, and give the identity the vendor’s key with bonanza identity secret set. See A session does not start.
  • resume --last picks the wrong session. It looks only at the current directory. Run bonanza session resume without it and choose from the picker.
  • A tool is missing from the session. Name its trait with --traits, or start with --all.

What’s next

Section titled “What’s next”