GitHub - shrug-labs/aipack

A package manager for AI agent knowledge.

Rules, skills, workflows, agent definitions, MCP server configs, hooks — authored once as portable packs, composed through profiles, and synced to whatever coding assistant you use.

The Problem

Agent knowledge exists everywhere and composes nowhere. Community skill libraries publish hundreds of capabilities. Teams build shared workflows that actually work. Individuals refine their MCP server configs and agent rules over months. All of it lives in places where it can't be combined: git repos with per-harness static renderings, chat threads that scroll off in days, personal dotfiles that never leave one machine.

The agent ecosystem has a content layer — growing fast — and no infrastructure layer to compose it. You can't install one team's deployment workflow alongside a community skill library and your personal rules, scoped to the right context, rendered for the harness you happen to use today.

The Solution

aipack is the infrastructure layer. Packs are portable, versioned bundles of agent knowledge. Profiles compose packs and curate which content and tools are active for a given context. A sync engine renders the result into each harness's native format — so the same pack works whether you use Claude Code, Codex, OpenCode, or Cline.

┌─────────────┐     ┌──────────┐     ┌──────────────┐
│  Pack A     │     │          │     │ Claude Code  │
│ (community) │────▶│          │────▶│ .claude/     │
├─────────────┤     │          │     ├──────────────┤
│  Pack B     │────▶│  aipack  │────▶│ Codex        │
│  (team)     │     │   sync   │     │ .codex/      │
├─────────────┤     │          │     ├──────────────┤
│  Pack C     │────▶│          │────▶│ OpenCode     │
│ (personal)  │     │          │     │ .opencode/   │
└─────────────┘     └──────────┘     ├──────────────┤
                                     │ Cline        │
                                     │ .clinerules/ │
                                     └──────────────┘

Supported Harnesses

Quick Start

Install

On macOS, install via Homebrew:

brew install shrug-labs/tap/aipack

On macOS and Linux, you can also use the release-backed installer script:

curl -fsSL https://raw.githubusercontent.com/shrug-labs/aipack/main/install.sh | sh

On Windows (PowerShell):

irm https://raw.githubusercontent.com/shrug-labs/aipack/main/install.ps1 | iex

On Windows, the PowerShell installer writes aipack.exe to ~/.local/bin.

If you already have Go installed and prefer a Go-native install path:

go install github.com/shrug-labs/aipack/cmd/aipack@latest

Set GOBIN to $HOME\.local\bin if you want go install to use the same destination as the installer:

[System.Environment]::SetEnvironmentVariable('GOBIN', "$HOME\.local\bin", 'User')

The installers detect your platform, download the matching release binary, verify SHA256SUMS, install aipack, and print the installed version.

Useful overrides (macOS/Linux):

# Pin a specific release tag
curl -fsSL https://raw.githubusercontent.com/shrug-labs/aipack/main/install.sh | VERSION=v0.3.0 sh

# Install into a specific directory
curl -fsSL https://raw.githubusercontent.com/shrug-labs/aipack/main/install.sh | BIN_DIR=$HOME/.local/bin sh

# Install under a prefix
curl -fsSL https://raw.githubusercontent.com/shrug-labs/aipack/main/install.sh | PREFIX=$HOME/.local sh

Windows override (PowerShell):

$env:AIPACK_VERSION = "v0.12.0"; irm https://raw.githubusercontent.com/shrug-labs/aipack/main/install.ps1 | iex

Release binaries are published for darwin/arm64, darwin/amd64, linux/amd64, windows/amd64, and windows/arm64. Stable releases also update the Homebrew formula in shrug-labs/homebrew-tap. If you prefer a manual install, use the matching release asset from https://github.com/shrug-labs/aipack/releases together with SHA256SUMS.

Build from source

git clone https://github.com/shrug-labs/aipack.git
cd aipack
make install    # builds and copies to ~/.local/bin/aipack

Building from source requires Go 1.25+.

First Use

# Initialize config directory, default profile, and fetch the public registry
aipack init

# Install a pack and add it to the active profile
aipack pack install ./my-pack --add
aipack pack install --url https://github.com/org/my-pack.git --add
aipack pack install my-pack --add    # looks up name in registry

# Preview what would change
aipack sync --dry-run

# Sync to your harness config
aipack sync

Full Setup (Recommended)

Packs can bundle profiles, registry entries, and dependency declarations. When a pack includes these, the install path bootstraps your entire agent environment:

# 1. Install a pack. -w all accepts its bundled profiles, registries, and extras.
aipack pack install --url https://github.com/org/my-pack.git -w all

# 2. Activate a profile and install its dependency packs from the registry.
aipack profile set frontend-dev --install

# 3. Sync to your harness.
aipack sync

Three commands: install, compose, sync. The profile pulls in whatever dependency packs it needs — community skill libraries, shared MCP configs, project-specific workflows — and aipack renders the combined result for your harness.

Documentation

• Getting Started — install packs and sync to your harness in five minutes
• Installing Packs — all installation methods, content_paths, quiet packs, registry entries
• Creating Packs — author your own pack from scratch or existing content
• Profiles — compose packs, filter content, expand parameters, scope to roles
• Pack Format Specification — format reference for content vectors, MCP servers, environment references, and manifests
• Harness Reference — per-harness rendering behavior, write targets, and configuration differences
• Sync and Save — sync workflow, save round-trips, restore, and clean
• aipack Reference — complete CLI reference
• Configuration and State — config directory layout, sync-config, ledger and state management
• CLI Specification — JSON output contracts and enumerations for tooling integration

Key Concepts

A pack is a directory of agent configuration — rules, skills, workflows, agent definitions, MCP server configs, hooks, and harness settings — with a pack.json manifest. Content is markdown or YAML with typed entry files. Drop files into the conventional directories (rules/, skills/, workflows/, agents/, mcp/, hooks/) and the sync engine discovers them automatically. Any git repository can also be consumed as a pack by mapping its directories to content types — no pack.json required in the source. See Installing Packs.

Profiles control which packs to sync and how — content filtering, parameter expansion, per-pack content overrides, context-based scoping. Packs can bundle profiles so setup is pack install -w all + profile set + sync. See Profiles for the full guide.

Sync resolves the active profile and writes to harness-native locations. Non-destructive by default — user modifications are detected via content digest and shown as diffs rather than overwritten.

Features

Releases and Versioning

• Public installs are distributed as GitHub Release binaries.
• macOS installs are also available via brew install shrug-labs/tap/aipack.
• install.sh is the primary cross-platform install path for macOS and Linux.
• CLI releases use semantic versioning tags: vMAJOR.MINOR.PATCH and prerelease tags such as vMAJOR.MINOR.PATCH-rc.1.
• aipack remains in the 0.x phase for now; breaking user-facing changes bump the minor version.
• The first public release line is v0.3.0.
• VERSION is the source of truth for the release line.
• Release process details live in RELEASING.md, and shipped user-facing changes are tracked in CHANGELOG.md.

Registry

aipack supports multiple registry sources. Each source is cached locally and fetched independently.

• aipack registry fetch <url> adds and fetches a single source.
• aipack registry fetch (bare) fetches all configured sources.
• aipack registry sources lists configured sources and their cache status.
• Sources are saved to registry_sources in sync-config.yaml and cached in ~/.config/aipack/registries/ (%APPDATA%\aipack\registries\ on Windows).
• Both HTTPS and SSH git URLs are supported. SSH URLs (git@host:path or ssh://) avoid credential prompts.
• Git repos are auto-detected from .git suffix, git@ prefix, ssh:// scheme, or --ref/--path flags.
• The compiled-in default points at registry.yaml in shrug-labs/packs and is used when no sources are configured.
• Even without registry entries, pack installs work via direct paths and aipack pack install --url ....

Building

make fmt       # format Go source
make fmt-check # fail if formatting is stale
make help       # show all targets
make build      # build for current platform → dist/
make test       # run Go tests
make dist       # cross-compile for darwin/arm64, darwin/amd64, linux/amd64, windows/amd64, windows/arm64
make install    # build + copy to ~/.local/bin/
make clean      # remove build artifacts

Contributing

This project welcomes contributions from the community. Before submitting a pull request, please review our contribution guide.

Security

Please consult the security guide for our responsible security vulnerability disclosure process.

License

Copyright (c) 2025, 2026 The aipack Authors.

Released under the Universal Permissive License v1.0. See LICENSE.txt.