ctxbrew

Ship & Use AI-friendly package context.

ctxbrew is a CLI and protocol for shipping and consuming AI-friendly library context.

It helps:

• library authors ship context with minimal effort and configuration
• library users get better AI responses to prompts related to their dependencies.

✨ Features

• 🧑‍💻 Simple authoring: define a ctxbrew.yaml, build context artifacts, and publish them with your package.
• 🤖 Simple consumption: install ctxbrew, generate an agent skill, and let the LLM discover context from installed libraries.
• 📦 No extra hosting: ship context as part of your library.
• 🏷️ Version correctness: read context from the installed package version.
• ⚡ Fast local access: extract context from local package files with no network calls.
• 🪄 Token efficiency: split context into focused slices and compress supported sources into top-level signatures.

🗺️ Roadmap

• JavaScript ecosystem support
• Python and pip support
• Go modules support
• Rust and Cargo support
• Java and Gradle support
• C# and NuGet support
• PHP and Composer support
• Ruby and RubyGems support
• Dart and pub.dev support
• Homebrew support
• Community context registry for packages without first-party support
• Website

🚀 Quick Start

🧑‍🍳 Library Author Workflow

• Install ctxbrew and create a config:

npm install ctxbrew --save-dev
npx ctxbrew init

This creates ctxbrew.yaml.

• Edit ctxbrew.yaml and describe context slices.

Each slice may cover one focused feature, workflow, or concept. Smaller slices help agents request only the context they need and keep token usage lower.

• Validate and build the context:

# Validate config and input files without writing artifacts.
npx ctxbrew build --check

# Generate ctxbrew/index.yaml and ctxbrew/<slice-id>.md files.
npx ctxbrew build

• Publish the generated ctxbrew/ folder with your package.

The exact setup depends on your release pipeline. You can see an example integration.

🧭 Library Consumer Workflow

• Install ctxbrew globally to use it across repositories:

npm install -g ctxbrew

• Set up agent skills:

# Generate ctxbrew skills in supported agent locations.
ctxbrew setup

# OR print the skill markdown to stdout.
ctxbrew skill

• Let the generated skill guide your agent:

# List packages with ctxbrew context in node_modules.
ctxbrew list

# List slices for one package.
ctxbrew list @org/library

# Read one slice.
ctxbrew get @org/library components

# Search slices by id and description.
ctxbrew search "dialog focus trap"

🧩 Config Format

ctxbrew.yaml describes the context artifacts that will be generated into ctxbrew/.

version: 1
slices:
    - id: overview
      description: High-level architecture
      include:
          - README.md

    - id: components
      title: Components
      description: UI components and usage
      compress: true
      include:
          - src/components/**
          - docs/components/**

✅ Rules

• version is required and currently must be 1.
• slices must contain at least one slice.
• id must be unique kebab-case.
• description is required and is used by ctxbrew search.
• include is required and must match at least one file during build.
• title is optional; when omitted, it is generated from id.
• compress is optional and defaults to false. When enabled, supported files are reduced to top-level signatures.

🛠️ CLI Reference

ctxbrew init [--cwd <dir>] [--force]
ctxbrew build [--check] [--cwd <dir>]
ctxbrew list [package]
ctxbrew get <package> <slice>
ctxbrew search <query> [--limit <n>]
ctxbrew setup [--cwd <dir>]
ctxbrew skill

🧪 Development

bun install
bun run dev -- --help
bun test
bun run typecheck
bun run build

📄 License

This project is licensed under the MIT License.