Skip to content

README.md

Latest commit

 

History

History
228 lines (167 loc) · 10.9 KB

README.md

File metadata and controls

228 lines (167 loc) · 10.9 KB

aipack

A CLI tool for authoring, composing, and syncing AI agent configuration across coding assistants.

Write your rules, skills, workflows, and MCP server configs once as portable packs, then sync them to every harness your team uses.

The Problem

AI coding assistants (Claude Code, Cline, Codex, OpenCode) each store agent configuration differently — different file formats, different directory structures, different conventions. Teams using multiple assistants maintain duplicate configs that drift apart. Onboarding a new team member means manually copying dotfiles.

The Solution

aipack introduces packs — portable, versioned bundles of agent configuration — and a sync engine that renders them into each harness's native format.

┌─────────────┐     ┌──────────┐     ┌──────────────┐
│  Pack A     │     │          │     │ Claude Code  │
│  (team ops) │────▶│          │────▶│ .claude/     │
├─────────────┤     │          │     ├──────────────┤
│  Pack B     │────▶│  aipack  │────▶│ Codex        │
│  (personal) │     │   sync   │     │ AGENTS.override.md │
├─────────────┤     │          │     ├──────────────┤
│  Pack C     │────▶│          │────▶│ OpenCode     │
│  (org-wide) │     │          │     │ .opencode/   │
└─────────────┘     └──────────┘     ├──────────────┤
                                     │ Cline        │
                                     │ .clinerules/ │
                                     └──────────────┘

Supported Harnesses

Harness Rules Skills Workflows Agents MCP Servers Settings
Claude Code Individual files Skill directories Command files Subagent files .mcp.json settings.local.json
OpenCode Individual files Skill directories Command files Individual files opencode.json opencode.json
Codex Flattened to AGENTS.override.md Skill directories Promoted to skill dirs Promoted to skill dirs config.toml config.toml
Cline Individual files Skill directories Individual files Promoted to skill dirs Global only N/A

Quick Start

Install

On macOS, install via Homebrew:

brew install dfoster-oracle/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

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 dfoster-oracle/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.24+.

First Use

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

# Install a pack from a local directory, git URL, or registry name
aipack pack install ./my-team-pack
aipack pack install --url https://github.com/org/team-pack.git
aipack pack install my-team-pack    # looks up name in registry

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

# Sync to your harness config
aipack sync

Team Onboarding (Recommended)

When a team publishes a pack in a shared repo, the ideal install path bootstraps everything from the team pack itself — profiles, registry entries, and dependency packs:

# 1. Install the team pack from the shared repo.
#    --seed applies bundled profiles and registry entries from the pack.
#    Auto-creates ~/.config/aipack/ if needed.
aipack pack install --url https://github.com/org/shared-repo.git \
  --path team-pack --ref main --seed

# 2. Activate the team profile and install its dependency packs.
#    --install looks up missing packs in the seeded registry and installs them.
aipack profile set my-team --install

# 3. Sync to your harness.
aipack sync --harness claudecode --scope global

Three commands: install the team pack, activate the profile with dependencies, sync. New team members are fully configured.

Documentation

Key Concepts

A pack is a directory of agent configuration — rules, skills, workflows, agent definitions, MCP server configs, and harness settings — with a pack.json manifest. Content is markdown with YAML frontmatter. Drop files into the conventional directories (rules/, skills/, workflows/, agents/, mcp/) and the sync engine discovers them automatically. Full format reference: Pack Format Specification.

Profiles control which packs to sync and how — content filtering, parameter expansion, MCP server overrides, role-based scoping. Teams bundle profiles with packs so onboarding is pack install --seed + profile set + sync. See Getting Started for worked examples.

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

Feature Description
aipack init Bootstrap config directory, default profile, and registry
aipack sync Render packs into harness-native config
aipack save Capture harness config back into packs
aipack restore Undo the last sync's settings changes
aipack clean Remove all managed files from harness locations
aipack pack create/install/list/show/update/delete Pack lifecycle management
aipack pack rename/enable/disable/validate Pack configuration and validation
aipack profile create/set/show/list/delete Profile management
aipack registry fetch/list/sources/remove Discover and manage pack registries
aipack search Full-text search across all installed packs
aipack query Run raw SQL against the pack index
aipack status Show ecosystem status: profile, packs, and content inventories
aipack trace Trace a resource from pack source to harness destination
aipack render Generate portable pack output
aipack doctor Validate config health and detect drift
aipack manage Interactive terminal UI
aipack prompt list/show/copy Browse prompts from installed packs
aipack version Print the CLI version

Releases and Versioning

  • Public installs are distributed as GitHub Release binaries.
  • macOS installs are also available via brew install dfoster-oracle/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/.
  • 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/aipack 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.