OpenBackpack

OpenBackpack is a local capability manager for AI agent workflows. The first milestone is intentionally small: sync local skill folders into Codex while keeping the capability store and install model agent-neutral.

MVP Commands

openbp is the short alias for the full openbackpack command.

openbp init
openbp add <local-path>
openbp link --global <skill>
openbp copy --project <repo> <skill>
openbp list
openbp unlink <skill>
openbp --version

The MVP stores capabilities under ~/.openbackpack/capabilities, tracks source paths and content hashes in ~/.openbackpack/lock.json, and refuses to overwrite existing targets unless --force is provided.

Development

Requires Node.js 24 LTS and pnpm 10. The exact Node.js version used by the repository is recorded in .nvmrc.

nvm install
corepack enable
pnpm install
pnpm build
pnpm dev -- --help

This repository is a pnpm/Turborepo monorepo with:

• @openbackpack/core for filesystem sync operations
• openbackpack for the openbackpack command and its openbp alias
• @openbackpack/ai for the AI SDK tool adapter

Architecture

OpenBackpack keeps capability storage separate from agent installation:

• Capability store: validates local source folders, stores supported files, hashes content, and tracks lockfile metadata.
• Agent target adapters: resolve where a capability should be installed for a specific agent and scope. Codex is the only adapter in the MVP.
• Interfaces: CLI and AI SDK tools translate user/tool inputs into the shared command layer.

Interfaces

OpenBackpack has two interfaces over the same shared command layer:

• Human CLI: openbackpack or its short alias openbp.
• AI tool call: an AI SDK tool(...) adapter from @openbackpack/ai.

The CLI parses human argv into a shared command object, previews any target path, executes the command, and renders text. AI tools skip the human parser and call the same command executor through the AI SDK adapter, so validation, Effect runtime, filesystem behavior, lockfile updates, and error handling stay in one place.

import { openBackpackTool } from "@openbackpack/ai";

export const tools = {
  openbackpack: openBackpackTool,
};

For agents that need custom runtime paths, create a configured tool:

import { createOpenBackpackTool } from "@openbackpack/ai";

export const openbackpack = createOpenBackpackTool({
  storeDir: "/tmp/openbackpack-home",
  codexGlobalSkillsDir: "/tmp/codex-skills",
});

The AI tool uses Zod schemas for both input and output. It returns structured system information to the calling agent:

{
  ok: true,
  result: {
    type: "add",
    name: "pr-review",
    sourcePath: "/path/to/pr-review",
    storePath: "/tmp/openbackpack-home/capabilities/pr-review",
    hash: "..."
  }
}

Agents can use the neutral install command shape:

{
  type: "install",
  skill: "pr-review",
  target: {
    agent: "codex",
    scope: "global",
    mode: "link"
  }
}

Domain errors are returned as tool results instead of being hidden from the agent:

{
  ok: false,
  error: {
    message: "Capability already exists: pr-review. Use --force to replace it."
  }
}

Supported structured command types are version, init, add, install, uninstall, linkGlobal, copyProject, list, and unlinkGlobal. linkGlobal, copyProject, and unlinkGlobal are Codex-friendly compatibility commands over the neutral install model. Agents like Codex should call the AI SDK tool when they need structured results, and humans should use the CLI.

Quality Gates

pnpm format
pnpm lint
pnpm knip
pnpm typecheck
pnpm check

Husky runs pnpm precommit before commits. That formats and lints staged source files with lint-staged, then runs the workspace typecheck.