Installation — PactKit Docs

PactKit supports multiple AI coding tools and installation methods.

Option A: Claude Code Plugin (Recommended for Claude Code)

The simplest way to install for Claude Code users. No Python required.

# In Claude Code:
/plugin marketplace add pactkit/claude-code-plugin
/plugin install pactkit

Restart Claude Code. All 9 agents, 11 commands, 10 skills, and 8 rules are immediately available.


Update	Automatic via marketplace, or `/plugin update pactkit`
Uninstall	`/plugin uninstall pactkit`
Isolation	Plugin lives in its own cache directory, separate from `~/.claude/`
Team sharing	Add to `.claude/settings.json` — teammates get prompted to install

The plugin deploys all components. For selective deployment (e.g., disable certain agents or commands), use the pip method with pactkit.yaml.

Add the following to your project's .claude/settings.json to auto-prompt teammates:

{
  "extraKnownMarketplaces": {
    "pactkit": {
      "source": { "source": "github", "repo": "pactkit/claude-code-plugin" }
    }
  },
  "enabledPlugins": {
    "pactkit@pactkit": true
  }
}

Option B: pip Install (All IDEs)

Since v2.9.0, a single pip install pactkit includes all IDE adapters (Claude Code, OpenCode, Codex CLI). No separate adapter packages needed.

Requirements

Python 3.10+
One or more supported AI coding tools installed

Install & Deploy (All IDEs)

pip install pactkit
pactkit init

This deploys to all three IDEs in one step:

IDE	Deploy Path	Key Files
Claude Code	`~/.claude/`	`CLAUDE.md`, `rules/`, `agents/`, `commands/`, `skills/`
OpenCode	`~/.config/opencode/`	`AGENTS.md`, `rules/`, `agents/`, `commands/`, `skills/`, `opencode.json`
Codex CLI	`~/.codex/`	`AGENTS.md`, `prompts/`, `config.toml`

Single-IDE Deployment (Optional)

Use --format to target a specific IDE:

pactkit init --format claude    # Claude Code only
pactkit init --format opencode  # OpenCode only
pactkit init --format codex     # Codex CLI only

Update & Upgrade

pip install --upgrade pactkit
pactkit update                    # Re-deploy all IDEs
pactkit upgrade --format opencode # Re-deploy single IDE

Other Commands

# Check version
pactkit version

# Preview to custom directory
pactkit init -t /tmp/preview
pactkit init --format opencode -t /tmp/oc-preview

IDE Format Details

The following sections describe format-specific differences. You don't need to read these unless you want to understand how PactKit adapts to each IDE.

Claude Code

Path	Contents
`CLAUDE.md`	Constitution root (references 8 rule modules via `@import`)
`rules/`	7 modular rule files
`agents/`	9 agent definitions
`commands/`	11 command playbooks
`skills/`	10 skills (3 scripted + 7 prompt-only)

OpenCode

Path	Contents
`AGENTS.md`	Slim header (rules loaded via `opencode.json` instructions)
`rules/`	8 rule files (3 core always-load via `instructions` + 6 on-demand via `@reference`)
`agents/`	9 agent definitions (`mode: subagent`, tools as record format)
`commands/`	11 command playbooks (`agent: build` + `model:` routing)
`skills/`	10 skills (with `SKILL.md` frontmatter for auto-discovery)
`opencode.json`	Global config (instructions, preserves user `provider` config)

Key Differences from Claude Code:

Feature	Claude Code	OpenCode
Rules loading	`@import` in CLAUDE.md (all 8 rules)	Lazy split: 3 core in `instructions` + 6 on-demand via `@reference` in AGENTS.md
Agent format	`name:`, `permissionMode:`, string tools	`mode: subagent`, no `name`, record tools
Command frontmatter	`allowed-tools: [...]`	`agent: build` + `model: provider/model-id`
Config file	`.claude/pactkit.yaml`	`.opencode/pactkit.yaml`
Model routing	Prompt-level suggestion	Config-level enforcement via `model:` frontmatter

Lazy Rule Loading: OpenCode v2.1.1 introduced lazy rule loading to reduce token consumption by ~62% per turn. Core rules (3 files) load every turn via opencode.json instructions; on-demand rules (6 files) are read only when needed.

Model Routing: OpenCode commands automatically route to appropriate models:

Commands	Model	Reason
`/project-plan`, `/project-clarify`, `/project-design`	Inherit main model	Deep reasoning tasks
`/project-act`, `/project-done`, `/project-check`, etc.	Sonnet	Implementation tasks
Background (title, compression)	Haiku (`small_model`)	Lightweight tasks

Configure in pactkit.yaml:

command_models:
  project-act: sonnet
  project-done: sonnet
  project-check: sonnet

Codex CLI

Path	Contents
`AGENTS.md`	Single-agent file with 10KB budget + truncation
`prompts/`	Playbook-style command files with prerequisite injection
`config.toml`	Codex configuration (MCP, sandbox, hooks)

Key Differences from Claude Code:

Feature	Claude Code	Codex CLI
Agent model	Multi-agent (9 roles)	Single-agent (`AGENTS.md`)
Command format	Skills with `SKILL.md` frontmatter	Playbooks with description frontmatter
Config format	`.claude/pactkit.yaml`	`.codex/pactkit.yaml` + `config.toml`
Brand references	Claude-native	Auto-replaced (Claude → Codex)
Sprint command	Full multi-agent orchestration	Not available (single-agent limitation)

Option E: Trae (Coming Soon)

Trae integration is under active development.

Trae support is planned for a future release. The adapter will follow the same thin-adapter pattern as OpenCode and Codex — install pactkit-trae and run pactkit init --format trae. Stay tuned for updates.

Project Initialization

After installing PactKit (via any method), initialize each project you work on:

/project-init

This creates the governance structure (docs/specs/, docs/product/sprint_board.md, docs/architecture/graphs/, etc.) and environment-appropriate project instructions:

Claude Code: .claude/CLAUDE.md with architecture overview, dev commands, and @ references
OpenCode: ./AGENTS.md + opencode.json with permission, mcp template, and instructions
Codex CLI: .codex/AGENTS.md + config.toml with sandbox and hooks configuration

Forgot to initialize? No problem — /project-plan and /project-doctor automatically detect uninitialized projects and handle it for you.

Multi-Developer Collaboration

For teams, set the developer field in pactkit.yaml to avoid Story ID conflicts:

developer: alice

Story IDs become STORY-alice-001, preventing merge conflicts when multiple developers work on separate branches. See Configuration for details.

On this page