Bundles

A bundle is a composable “packaging unit” defined by amplifier-foundation. A bundle combines: (1) a mount plan (session + providers/tools/hooks/agents) and (2) resources (context files, agent markdown, examples), and it can include other bundles. Bundles are designed for applications that want a turn-key way to ship and run a curated setup without depending on the profile/collection conventions.

When to use bundles

Primary configuration: Bundles are the recommended way to configure Amplifier (replaces profiles/collections)
Apps and services: a web app/daemon can load a bundle and run sessions without a "profile catalog"
Reproducibility: share a single "thing" that includes config + resources + module sources
Composition: build a stack by including smaller bundles (see examples below)
Default in CLI: New users start with the foundation bundle

Mental model

Bundles are the new standard. They replace profiles/collections with a simpler, more composable system. A bundle is just a markdown file with YAML frontmatter - easier to create, share, and understand than Python packages.

Bundle composition (inheritance)

Bundles can include: other bundles, enabling powerful composition patterns:

Example: LSP Bundle Inheritance

The LSP bundles demonstrate composition:

# lsp-python bundle (simplified)
---
bundle:
  name: lsp-python
  version: 1.0.0

includes:
  - bundle: lsp  # Inherit core LSP functionality

agents:
  - agent: python-code-intel  # Add Python-specific agent
---

# Python code intelligence via Pyright

The lsp-python bundle extends lsp (core Language Server Protocol support) and adds Python-specific capabilities. Similarly, lsp-typescript extends lsp for TypeScript/JavaScript.

Example: Foundation Bundle Composition

Most bundles build on foundation:

# Your custom bundle
---
bundle:
  name: my-custom-setup
  version: 1.0.0

includes:
  - bundle: foundation  # Get all core tools/providers/hooks

tools:
  - module: tool-custom  # Add your custom tool
    source: git+https://github.com/you/tool-custom@main

agents:
  - agent: my-expert  # Add your custom agent
---

# Your custom system instructions here

What changes when you switch to bundle mode

Session config source switches from “compile a profile” to “load a bundle’s mount plan”.
Module acquisition can become turn-key (foundation can download modules from bundle URIs).
Namespace mentions become more important (@foundation:… resolves within the bundle’s resources).

Existing bundles (scanned)

This list is rendered from data/catalog.json.

CLI impact

Bundles are opt-in in the CLI. When a bundle is active, it takes precedence over profiles for session configuration. See CLI configuration.

Deep references

Bundle data model: amplifier-foundation/amplifier_foundation/bundle.py
Bundle concepts/patterns: amplifier-foundation/docs/CONCEPTS.md and amplifier-foundation/docs/PATTERNS.md