Primitives

Barry builds every session from seven primitives. This page defines each one, where it lives, and the commands that act on it.

Primitive	What it is	Where you declare it
Identity	The persona a session runs as	An identity directory with identity.yaml
Bag	A bundle of capabilities	A directory with bag.yaml, or an MCP server URL
Trait	A named grant of tool access	traits: in bag.yaml, or generated per bag
Bound	A named or inline restriction	Builtin seed, bound: on a trait or identity
Instruction	Standing guidance for the agent	A markdown file under a bag’s instructions/
Action	A reusable, recorded procedure	actions/<name>/action.yaml in a bag
Schedule	An action on a trigger	schedules: in bag.yaml

Identity

An identity is the persona a session runs as. It holds the bags packed onto it, its default traits and bound, its default coding agent and model, and references to its secrets.

An identity lives in a directory that contains identity.yaml and a gitignored .env. Every field is optional:

Field	Type	Meaning
name	string	The identity’s name, which can differ from the directory name. Default: the directory name
displayName	string	Name shown in listings
aliases	list of strings	Extra command names on PATH that run Barry as this identity
bags	list of strings	Bags packed onto the identity
traits	list of strings	Traits merged into every session
default_coding_agent	claude, codex, cursor, or opencode	Agent a session runs on when no agent or endpoint flag names one. See Adapters
default_model	string	Model a session uses when -m names none
default_model_provider	string	Model endpoint for default_model, for example ollama
bound	bound object	Restrictions applied to every session. See the bound section
bag_grant	session or identity	session (default): a packed bag’s tools reach a session only when a trait selects them. identity: packing grants them to every session. Any other value reads as session
env	map	Environment variables. Each value is a literal or a secret reference
vault	string	Name of the vault that holds the identity’s secrets
allow_native_tools	boolean	In sessions that Barry’s session API runs, keep the agent’s own file tools available instead of Barry’s
status_notify	{tool, target}	Tool that sends status updates

A session picks its identity from, in order: --name, an identity command such as bgo, the repository’s .barry file, then the identity that barry use set.

Terminal

barry identity create "B. Goode"
barry use
barry identity show

Bag

A bag is a bundle of capabilities: tools, traits, instructions, actions, skills, schedules, hooks, services, and connections to other MCP servers. A local bag is a directory with a bag.yaml manifest. A remote bag is an MCP server URL.

barry install registers and builds a bag. barry pack puts it on an identity. Packing loads the bag’s hooks, skills, instructions, and actions for the identity; its tools reach a session only through a trait, unless the identity sets bag_grant: identity.

Terminal

barry install ~/repos/my-tools
barry pack my-tools
barry bag show my-tools

For the manifest, see Packing bags.

Trait

A trait is a named grant of tool access. It names bags or tool namespaces and an access level, read or readwrite (write means readwrite), and can mount skills and point at instructions.

• Traits are additive. Choosing another trait only adds tools.
• Every bag with tools or skills gets an automatic trait with the bag’s own name. It grants the bag’s namespaces at readwrite and its skills, plus, transitively, the namespaces and skills of every bag it composes under bags:.
• A trait declared in bag.yaml with the same name as the bag replaces the automatic trait, including everything it absorbed from composed bags.
• A trait can carry restrictions: bounds: names bounds, and bound: declares one inline.
• The traits coding, sessions, and instructions apply to every session. Missing grants fail closed: a tool no trait grants is not listed.

Terminal

barry trait list
barry --traits coding,sessions

Bound

A bound restricts what a session can do. It removes tools, write access, file paths, shell commands, and network destinations from what the traits granted. It never grants anything. When several bounds apply, Barry merges them toward more denial.

Terminal

barry bound list
barry --bound no-network
barry identity bound set readonly

The bounds reference lists every field, the merge rules, and which runtimes enforce what.

Instruction

An instruction is standing guidance the agent reads. It is a markdown file directly under the instructions/ directory of a bag or of an identity, with this front matter:

Field	Type	Default	Meaning
name	kebab-case string	The filename without .md	The instruction’s name
description	string, 1024 characters at most	None	What the agent reads when choosing. Required for on-demand
mode	always or on-demand	on-demand	always joins the system prompt. on-demand costs only the description until the agent fetches the body

An identity’s instruction wins a name collision with a bag’s. The agent lists instructions with the search_instructions tool and reads one with get_instructions.

Terminal

barry new instruction my-guidance --mode on-demand

Action

An action is a reusable procedure with declared inputs, requirements, optional validation, and a recorded run. It lives in actions/<name>/action.yaml, or under skills/, in a bag. An agent carries out its prompt, or Barry runs its run: command itself; an action declares exactly one of the two.

Sessions discover actions with the find_actions tool and start one with begin_action. An action with slash_command: true also appears as a slash command on Claude Code and Cursor: /<name>, or /barry:<name> in a Claude Code session that Barry’s session API runs. The actions bag owns the full action.yaml contract.

Terminal

barry new action triage-report
barry action runs

Schedule

A schedule runs an action on a trigger: an interval (every), a cron expression (cron), a single time (at, an ISO-8601 time), or once each time the machine starts (at: login). A bag declares schedules in bag.yaml and names each action or writes it inline. One scheduler service runs every schedule. Each schedule’s ID is <bag>/<name>.

Terminal

barry schedule list
barry schedule show sessions/reaper

The schedules: schema is schedule-manifest.ts. The schedules bag owns the scheduler.