Skip to content
Barry Guides
WIP

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

Packing bags

Use this when you want to add a bag’s tools to your Barry, or make a bag of your own.

A bag bundles tools, instructions, and actions; packing it puts it on your identity.

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.
  • To make a bag, have a directory for it, such as ~/repos/my-tools.

Install and pack a bag

Section titled “Install and pack a bag”

The example is the Blender bag, which renders 3D animation on your Mac. It also needs Blender and ffmpeg, which its README lists.

  1. Install the bag from its repository:

    Terminal
    barry install https://github.com/perintyler/blender-bag

    Barry clones the repository into ~/repos/bags, builds it, and registers it under the name its bag.yaml declares, blender. Installing is machine-wide and belongs to barry itself, not to an identity.

  2. Pack the bag onto your identity:

    Terminal
    bonanza pack blender

  3. Start a session that grants the bag’s tools:

    Terminal
    bonanza session start --traits blender

    Packing loads a bag onto the identity, and a trait hands its tools to a session. Empowering with traits covers the other ways to grant them.

To see everything a bag registered, run barry bag show blender.

Create a bag

Section titled “Create a bag”

  1. Scaffold the bag:

    Terminal
    barry new my-tools --path ~/repos/my-tools

    The scaffold holds a bag.yaml and an empty skills/ directory. The manifest starts with empty mcp-servers, traits, and tools entries, and a commented example of host dependencies.

  2. Add a tools.ts beside bag.yaml that exports your tools. Barry discovers the tools your tools.ts (or src/tools.ts) exports; you do not point bag.yaml at it. Write a tool shows the file. Edit the manifest’s description and add tool metadata or dependencies as you need them:

    version: v0.1
    name: my-tools
    description: Tools for my workflow
    mcp-servers: {}
    traits: {}
    tools: []

  3. Check the bag without installing it:

    Terminal
    barry bag check ~/repos/my-tools

  4. Register and build the bag, then pack it onto your identity:

    Terminal
    barry install ~/repos/my-tools
    bonanza pack my-tools

  5. Start a session that grants its tools:

    Terminal
    bonanza session start --traits my-tools

When you change the bag’s code, run barry install ~/repos/my-tools again to rebuild it.

What a bag.yaml holds

Section titled “What a bag.yaml holds”

A manifest needs only name and description. These are the fields a first bag uses:

Field What it does
name Required. The bag’s name, its automatic trait’s name, and the default namespace of its tools
description Required. One line on what the bag provides
tools A list that sets per-tool metadata and visibility (for example deferred). The tool code itself is auto-discovered from tools.ts or src/tools.ts; you do not name the module here
mcp-servers An MCP server the bag owns: url for HTTP, or command and args for stdio. The server’s name becomes its tool namespace
traits Extra named grants, each with description, access (read or readwrite), and the bags it grants
dependencies Host programs the bag needs on PATH, each with a name and an optional install and reason. Barry reports a missing one and installs nothing

The schema is strict: an unknown key fails the whole manifest, and a failed manifest contributes no tools and no traits. barry bag check reports it.

Beside bag.yaml, a bag can hold instructions/<name>.md, actions/<name>/action.yaml, and skills/<name>/. Using actions covers actions.

Verify

Section titled “Verify”

To confirm the identity packed the bag, run:

Terminal
bonanza identity show

The Bags: line lists blender and my-tools. To see what a bag registered, run barry bag show blender: it prints the bag’s path and its traits, along with any tools, services, and dependencies it declares.

If it fails

Section titled “If it fails”
  • barry bag check reports a manifest error. Fix what it reports in bag.yaml; an unknown key fails the whole manifest.
  • A host program is missing. Barry reports a dependency it cannot find on your PATH and installs nothing. Install it yourself: the Blender bag needs Blender and ffmpeg.
  • The session has no tools from the bag. Packing does not grant tools; a trait does. See A tool the agent should have is missing.

What’s next

Section titled “What’s next”