Skip to content
Barry Guides
WIP

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

Package an app

Use this when your bag needs a native app beside its tools: a menu-bar helper, a window an agent opens, or a companion on your phone.

Before you begin

Section titled “Before you begin”
  • Have a bag of your own. Packing bags shows how to make one.
  • Keep the app’s source inside the bag. Barry builds it with a build script or an Xcode project.

Declare an app in bag.yaml

Section titled “Declare an app in bag.yaml”

An app is a block under apps: in a bag’s manifest. Each app names a platform, how to build it, and where the built bundle lands. This illustrative example declares a macOS app named Questions, which lets an agent ask you a question and wait for the answer:

apps:
  Questions:
    description: Answer questions from agent sessions
    platform: macos
    name: Questions
    build: build:app
    output: questions-app/.build/Questions.app
    macos:
      bundle-id: com.barry.questions
      url-schemes:
        - barry-question
      login-item: false

The required fields are description, name, platform (macos or ios), build, and output. The output must end in .app and sit inside the bag. build is either a build-script token like build:app, or an Xcode object for a project build:

    build:
      project: questions-ios/Questions.xcodeproj
      scheme: Questions

Under macos you can set bundle-id, url-schemes (deep links into the app), login-item (launch at login), and keep-alive. An ios block takes bundle-id, url-schemes, and device.

Build and register it

Section titled “Build and register it”

Barry builds an app during setup when its bundle is missing, and records it. After you install a bag that ships an app, run setup so Barry builds the bundle. With the example app in a bag named my-tools:

Terminal
barry install ~/repos/my-tools
barry setup

Setup skips an app whose bundle already exists. To rebuild after you change the app’s code, name the app as <bag>.<name>:

Terminal
barry setup --app my-tools.Questions

Verify

Section titled “Verify”

To confirm Barry registered the app, run:

Terminal
barry app list
barry app url Questions

barry app list shows every registered app with its ID, display name, protocol version, and capabilities. barry app url prints where you reach an app or its deep-link scheme; the example app prints barry-question://. barry app commands run under barry itself, not an identity.

If it fails

Section titled “If it fails”
  • The app is missing from barry app list. Run barry setup again so Barry builds the bundle and records it, and check that output points at the .app the build writes.
  • barry app url does not find the app. Look it up by the app’s ID or name, not the bag’s name.
  • The app still runs old code. Rebuild it with barry setup --app <bag>.<name>.
  • Setup reports other problems. Run barry doctor, and see Check installation health.

What’s next

Section titled “What’s next”