@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
• 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, Codex commands and MCP are global-only, and GitHub Copilot 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).

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.

See docs/primitives for detailed formats and examples.

Development

npm install
npm run build
npm run typecheck
npm run lint
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