Big News: Socket raises $60M Series C at a $1B valuation to secure software supply chains for AI-driven development.Announcement →
Sign In

ctxbrew

Package Overview
Dependencies
Maintainers
1
Versions
4
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

ctxbrew - npm Package Compare versions

Comparing version
0.1.3
 to
0.1.4
+21
LICENSE
MIT License
Copyright (c) 2026 Artem Mangilev
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
+5
-1
bin/ctxbrew.js

@@ -10,2 +10,3 @@ #!/usr/bin/env node

const req = createRequire(import.meta.url);
const packageVersion = req("../package.json").version;

@@ -21,3 +22,6 @@ let binaryPath;

const result = spawnSync(binaryPath, process.argv.slice(2), { stdio: "inherit" });
const result = spawnSync(binaryPath, process.argv.slice(2), {
stdio: "inherit",
env: { ...process.env, CTXBREW_VERSION: packageVersion },
});
if (result.error) {

@@ -24,0 +28,0 @@ console.error(`ctxbrew: failed to run ${binaryPath}: ${result.error.message}`);

+6
-6
package.json
{
"name": "ctxbrew",
"version": "0.1.3",
"version": "0.1.4",
"devDependencies": {

@@ -20,7 +20,7 @@ "@pnpm/lockfile-file": "^9.1.3",

"optionalDependencies": {
"@ctxbrew/darwin-arm64": "0.1.3",
"@ctxbrew/darwin-x64": "0.1.3",
"@ctxbrew/linux-x64": "0.1.3",
"@ctxbrew/linux-arm64": "0.1.3",
"@ctxbrew/win32-x64": "0.1.3"
"@ctxbrew/darwin-arm64": "0.1.4",
"@ctxbrew/darwin-x64": "0.1.4",
"@ctxbrew/linux-x64": "0.1.4",
"@ctxbrew/linux-arm64": "0.1.4",
"@ctxbrew/win32-x64": "0.1.4"
},

@@ -27,0 +27,0 @@ "bin": {

+112
-52
README.md

@@ -1,100 +0,160 @@

# ctxbrew
<p align="center">
<img src="./assets/logo.png" alt="ctxbrew logo" width="220" />
</p>
`ctxbrew` packages repo context into versioned markdown slices and reads those slices from installed npm dependencies.
<p align="center">
<strong>Ship & Use AI-friendly package context.</strong>
</p>
## Install
`ctxbrew` is a CLI and protocol for shipping and consuming AI-friendly library context.
```bash
npm install -g ctxbrew
ctxbrew --version
```
It helps:
## Author workflow
- library authors ship context with minimal effort and configuration
- library users get better AI responses to prompts related to their dependencies.
Initialize config and publish wiring:
## ✨ Features
```bash
ctxbrew init
```
- 🧑‍💻 **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.
This creates `ctxbrew.yaml`, updates `package.json` (`files`, `scripts.prepack`) and adds generated-artifact markers.
## 🗺️ Roadmap
Build artifacts:
- [x] 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
1. Install `ctxbrew` and create a config:
```bash
ctxbrew build
npm install ctxbrew --save-dev
npx ctxbrew init
```
Validate without writing files:
This creates `ctxbrew.yaml`.
2. 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.
3. Validate and build the context:
```bash
ctxbrew build --check
# 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
```
Generated files:
4. Publish the generated `ctxbrew/` folder with your package.
- `ctxbrew/index.yaml`
- `ctxbrew/<slice-id>.md`
The exact setup depends on your release pipeline. You can see an [example integration](https://github.com/artem-mangilev/ngx-vflow/pull/284/changes/0f362044c834dfe26c321c8e9c3abc5f40defaab).
## Consumer workflow
### 🧭 Library Consumer Workflow
Discover installed packages with context:
1. Install `ctxbrew` globally to use it across repositories:
```bash
ctxbrew list
ctxbrew list @acme/ui
npm install -g ctxbrew
```
Read one slice:
2. Set up agent skills:
```bash
ctxbrew get @acme/ui components
# Generate ctxbrew skills in supported agent locations.
ctxbrew setup
# OR print the skill markdown to stdout.
ctxbrew skill
```
Search across slices:
3. Let the generated skill guide your agent:
```bash
# 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"
ctxbrew search "theming" --limit 5
```
## Config format (`ctxbrew.yaml`)
## 🧩 Config Format
`ctxbrew.yaml` describes the context artifacts that will be generated into `ctxbrew/`.
```yaml
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/**
- 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:
### ✅ Rules
- `version` is required and currently must be `1`.
- `slices` must contain at least one slice.
- `id` must be unique kebab-case.
- `include` is required and non-empty.
- `compress` is optional and defaults to `false`; when enabled, JS/TS files are reduced to top-level signatures.
- Overlap policy: first matching slice owns the file.
- `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.
## Setup for agents
## 🛠️ CLI Reference
```bash
ctxbrew setup
ctxbrew skill --agent cursor
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
```
## Exit codes
## 🧪 Development
- `0` success
- `1` not found
- `2` validation error
- `64` usage error
```bash
bun install
bun run dev -- --help
bun test
bun run typecheck
bun run build
```
## 📄 License
This project is licensed under the MIT License.