Build a Barry

Use this when you are new to Barry and want to install it, set up your first identity, and start a session as that identity.

An identity is a persona a session runs as, with its own capabilities, permissions, and configuration. You can build as many as you like, each a different Barry.

Before you begin

A Mac with Homebrew. To check, run brew --version.
Homebrew Node 26, at least 26.9, and pnpm 12. To check, run node --version and pnpm --version.
The harness this guide drives, installed before you set up Barry. A harness is the coding agent Barry runs a session through, and Barry drives the harness’s own command-line tool. Setup registers only the harnesses whose command it finds, so install yours first:

Harness Install

Claude Code brew install --cask claude-code

Codex brew install --cask codex

Cursor brew install --cask cursor-cli

OpenCode brew install opencode

This guide uses OpenCode.
A local model. This guide runs one through Ollama, which needs no vendor key. Install Ollama with brew install ollama, then pull the model with ollama pull smollm2:135m.

Harness	Install
Claude Code	`brew install --cask claude-code`
Codex	`brew install --cask codex`
Cursor	`brew install --cask cursor-cli`
OpenCode	`brew install opencode`

1. Install Barry

Clone Barry, install its dependencies, build its packages, and set it up from the checkout:

git clone https://github.com/perintyler/barry.git && cd barry
pnpm install --frozen-lockfile
pnpm build:packages
node cli/bin/barry.js setup --link .

barry setup installs the barry command and one login job that runs Barry’s services, and prints the directory it put barry in. If that directory is missing from your PATH, add it. barry uninstall removes the command and the login job and keeps your data.

If you install a harness after setup, register it from your Barry checkout with barry adapter add, such as barry adapter add adapters/sessions/opencode.

2. Create an identity

An identity is a directory that holds your Barry’s settings, and every session starts from it. Barry creates that directory, barry-bonanza, in the directory you run the command from. Primitives describes an identity in full.

Create an identity named bonanza:
Terminal
```
barry identity create bonanza
```
The output is similar to the following:
Output
```
...
  Installed `bonanza` command

Identity bonanza is ready.
...
```
Barry writes the directory, registers the identity, and installs a bonanza command on your PATH. That command is Barry acting as this identity, so you drive it with bonanza from here on.
Choose the harness it drives. This example uses OpenCode; antigravity, claude-code, codex, cursor, and pi work the same way. Point the identity at a local model in the same step, and make the harness its default:
Terminal
```
bonanza identity adapters set opencode --model smollm2:135m \
  --provider ollama --default
```
The output is similar to the following:
Output
```
Set adapters.opencode on identity 'bonanza'
```
Agent, model, and provider are one setting on the identity’s adapter. See Adapters for every harness and its flags.
Read back what you built:
Terminal
```
bonanza identity show
```
The output is similar to the following:
Output
```
...
Identity: bonanza
  Source: ~/barry-bonanza
...
  Adapters: claude-code, opencode (default, model ollama/smollm2:135m)
```
The identity is one small file. It names the identity, its packed bags, the traits every session starts with, and the harness and model it drives. The claude-code entry comes from the base identity it inherits; opencode is the one you set, and it is the default.

3. Start a session

From a project you want to work in, start a session as your identity:
Terminal
```
bonanza session start
```
Running bonanza on its own does the same thing. Barry prints the identity the session runs as, the bags it loaded, and the session’s ID.
Barry asks which capabilities to add. Press Enter without selecting any. Traits covers what you can add here.
Talk to your agent as you normally would. Type /exit when you finish, and name the session if Barry asks. To pick the session up later, run bonanza session resume.

What a bag looks like

A bag is a directory with a bag.yaml at its root. Barry’s own memory bag is a short one worth reading (bags/memory/bag.yaml):

name: memory
description: Repo- and tag-scoped memories — agents save them, sessions start with them

tools:
  - update: deferred
  - forget: deferred
  - list_tags: deferred
  - import_claude: deferred

prompts:
  entry: prompt.ts

services:
  web:
    description: Memory browser — search, edit, and curate memories in a web UI
    entry: server/src/index.ts
    working-directory: .
    serves: http
    health: /health
    secrets: [BARRY_SECRET]

stores:
  memory:
    owned_by: identity
    engine: sqlite
    migrations: ./migrations/memory
  unscoped:
    owned_by: node
    engine: sqlite
    migrations: ./migrations/memory

A short manifest gives a session the memory tools, keeps the occasional ones (update, forget, list_tags, import_claude) behind tool search as deferred, runs a web app beside them, and declares the SQLite stores they read and write. The bag needs no traits: block: the automatic memory trait, named after the bag, already grants its namespace.

Verify

To confirm the identity exists, run:

barry identity list

The list includes bonanza and the directory it lives in, such as ~/barry-bonanza. To confirm Barry’s services are healthy, run barry doctor; each running, healthy service shows a PASS line.

If it fails

Your shell cannot find barry or bonanza. Open a new shell, or add the directory setup printed to your PATH.
The session does not start, or the harness is missing. Install the harness’s own command-line tool, register it with barry adapter add, and pull the local model first. See A session does not start.
A doctor check fails. Run barry doctor --fix to repair what it safely can.

What’s next

Packing bags to give your Barry tools.
Run sessions for the ways to start, name, and resume sessions.
Automate a recurring task to see the primitives work together.