@hashicorp/kits

Install AI agent kits into your favorite coding assistants.

Table of Contents

• Overview
• Quick Start
• Supported Harnesses
• Install Scopes (Global vs Project)
• Kits Manifest + Lock
• Backups
• Documentation Index
• CLI Commands (Summary)
• Configuration and Formats
• Development
• Troubleshooting
• License

Overview

The Kit Installer is a CLI that discovers, validates, and installs AI agent kits into supported harnesses (Claude Code, Codex, Gemini CLI, GitHub Copilot, OpenCode). It supports local or remote kit repositories, manifest-driven installs, and scoped installation (global or project).

Quick Start

# Interactive install (prompts for scope + selection)
npx @hashicorp/kits install example-org/kits

# Non-interactive global install
npx @hashicorp/kits install example-org/kits --global -y

# Project-scope install (current repo)
npx @hashicorp/kits install example-org/kits --project -y

# List kits without installing
npx @hashicorp/kits install example-org/kits -l

# Validate a repository
npx @hashicorp/kits validate ./agent-kits

Supported Harnesses

| Harness | Commands | Skills | Subagents | MCP | Hooks | |---------|----------|--------|-----------|-----|-------| | Claude Code | Yes | Yes | Yes | Yes | Yes | | Codex | Yes | Yes | No | Yes | No | | Gemini CLI | Yes | Experimental | Experimental | Yes | Yes | | GitHub Copilot | Project only | Yes | Yes | Yes | Limited (project only) | | OpenCode | Yes | Yes | Yes | Yes | Yes |

Install Scopes (Global vs Project)

Kits can be installed at two scopes:

• Global (--global): user-level installs (e.g., ~/.claude/), available across projects.
• Project (--project): repo-level installs (e.g., .claude/), scoped to the current project.

Scope limitations: Some harnesses limit which primitives are supported at project scope. For example, GitHub Copilot commands and hooks are project-only.

Hook programs are stored in the kit hook store:

• Global scope: ~/.agents/hooks/
• Project scope: .agents/hooks/

Harness configs reference these hook program paths.

Kits Manifest + Lock

Manifest-driven installs use kits.json to declare intent and kits-lock.json to record resolved versions.

| Scope | Manifest | Lockfile | |-------|----------|----------| | Global | ~/.agents/kits.json | ~/.agents/kits-lock.json | | Project | .agents/kits.json | .agents/kits-lock.json |

The lockfile is the source of truth when its hash matches the manifest. It also records shared instance registries (mcpInstances, hookInstances) plus input schema hashes used to detect configuration changes during upgrades.

If an upgraded MCP server or hook program changes its input schema (MCP: env + headers, hooks: env + args), the upgrade flow prompts to reconfigure those inputs. Non-interactive upgrades fail when new required inputs are introduced without defaults.

Backups

The installer creates backups before modifying files:

• Config backups are stored adjacent to harness config files using a .backup suffix.
• File-based primitive backups (upgrade) are stored in the scope backup store so harnesses never ingest them.
• Global backup store: ~/.agents/backups/<harness>/<primitiveType>/<namespaced>.backup-<timestamp>
• Project backup store: .agents/backups/<harness>/<primitiveType>/<namespaced>.backup-<timestamp>
• Backups are preserved until you remove them manually.

Documentation Index

More comprehensive docs live under docs/:

• CLI usage and options: docs/cli
• Manifests + lockfiles: docs/manifests-lockfiles
• Primitives and resolution: docs/primitives
• Hook programs and bindings: docs/hooks
• Harness support + paths: docs/harnesses
• Validation and schemas: docs/validation
• Development + testing: docs/development
• Troubleshooting: docs/troubleshooting

CLI Commands (Summary)

kits install <source> [options]
kits uninstall <kit-name> [options]
kits upgrade [options]
kits validate <path> [--commands|--skills|--subagents|--hooks|--mcp|--kits]
kits list harnesses|kits
kits info <source> [-k kit-name]

Configuration and Formats

• Kit repositories can be single-kit or multi-kit with registries.
• Primitives may be shared or inline; versioned shared primitives live under primitives/.
• Tool templates ({{tool:...}}) and model templates ({{model:...}}) are resolved by adapters. Concrete files include version-pinned $schema and schemaVersion fields for validation; adapters strip these fields during installation.

See docs/primitives for detailed formats and examples.

Development

npm install
npm run build
npm run typecheck
npm run lint
npm run check:schema-versioning
npm test
npm run test:integration

Integration tests require the devcontainer. See docs/development.

Troubleshooting

Common issues and fixes are documented in docs/troubleshooting.

License

MPL-2.0