AI Assistant Support

ArcKit works with multiple AI assistant platforms, each offering different levels of integration and capabilities. Choose the platform that best matches your workflow and requirements.

Platform Comparison

Claude Code is the primary development platform for ArcKit and provides capabilities not available in other formats.

Feature	Claude Code Plugin	Gemini CLI Extension	Codex CLI	OpenCode CLI
54 slash commands	✅	✅	✅	✅
Templates & scripts	✅	✅	✅	✅
Bundled MCP servers	✅ (4 servers)	✅ (3 servers)	❌ Manual setup	❌ Manual setup
Autonomous research agents	✅ (5 agents)	❌	❌	❌
SessionStart hook	✅	❌	❌	❌
UserPromptSubmit hook	✅	❌	❌	❌
PreToolUse hook	✅	❌	❌	❌
PermissionRequest hook	✅	❌	❌	❌
Per-command Stop hooks	✅	❌	❌	❌
Wardley Mapping skill	✅ (Pinecone MCP)	❌	❌	❌
Mermaid Syntax Reference	✅	✅	✅	✅
Automatic marketplace updates	✅	✅	❌ Manual	❌ Manual
Zero-config installation	✅	✅	❌ `arckit init`	❌ `arckit init`

Claude Code Plugin (Premier Experience)

Recommended for: Teams wanting the most complete ArcKit experience with autonomous agents and automated governance hooks.

Installation

/plugin marketplace add tractorjuice/arc-kit

Then install from the Discover tab in Claude Code.

Requirements

Claude Code v2.1.63+ (required for memory leak fixes, MCP cache fixes, skill caching fixes)

Key Features

Autonomous Research Agents (5 agents)

Research-heavy commands run in isolated context windows, keeping the main conversation clean:

research - Technology market research with web search
datascout - External data source discovery (APIs, datasets, portals)
azure-research - Azure service research via Microsoft Learn MCP
aws-research - AWS service research via AWS Knowledge MCP
gcp-research - Google Cloud research via Developer Knowledge MCP

Benefits:

Dozens of WebSearch/WebFetch/MCP calls without context bloat
Parallel research execution
Clean main conversation history

Automation Hooks (4 hooks)

SessionStart Hook:

Auto-detects ArcKit version and all projects
Displays project inventory at session start
Recommends next commands based on artifacts

UserPromptSubmit Hook:

Injects project context into every prompt
Commands automatically know what artifacts exist
No need to manually specify project IDs

PreToolUse Hook:

Auto-corrects filenames to ArcKit conventions
Enforces ARC-{PID}-{TYPE}-v{VERSION}.md pattern
Prevents accidental filename typos

PermissionRequest Hook:

Auto-allows MCP documentation tools (fetch_resource, list_resources)
One-time approval for all subsequent MCP queries
Seamless research workflow

Bundled MCP Servers (4 servers)

Pre-configured and ready to use:

AWS Knowledge (https://knowledge-mcp.global.api.aws/sse)
Microsoft Learn (https://learn.microsoft.com/api/mcp/sse)
Google Developer Knowledge (https://developerknowledge.googleapis.com/mcp/sse) - requires GOOGLE_API_KEY
Pinecone Data Commons - For Wardley Mapping skill (book corpus)

No configuration required - works out of the box.

Per-Command Stop Hooks

Output validation for specific commands:Wardley Map Math Checks (/arckit.wardley):

Validates evolution axis values (0.0-1.0)
Ensures visibility axis consistency
Checks for overlapping components
Warns about unrealistic value chain dependencies

Future: More validation hooks for diagrams, traceability, compliance

Updates

Automatic via Claude Code marketplace - no action needed.

Usage

# No initialization needed - plugin provides everything
# Just use commands directly

/arckit.principles Create principles for a financial services company
/arckit.requirements Build a payment processing system...
/arckit.wardley Analyze build vs buy for authentication

Gemini CLI Extension (Full Support)

Recommended for: Teams using Gemini as their primary AI assistant.

Installation

gemini extensions install https://github.com/tractorjuice/arckit-gemini

Key Features

Zero-config: All 54 commands, templates, scripts, bundled MCP servers
MCP Servers: AWS Knowledge, Microsoft Learn, Google Developer Knowledge (3 servers)
Commands: Full command set with templates
Scripts: Automation helpers for filename generation, project detection

Updates

gemini extensions update arckit

Usage

# No initialization needed - extension provides everything
# Commands work out of the box

/arckit.principles Create principles for financial services
/arckit.requirements Build payment processing system

Limitations compared to Claude Code:

❌ No autonomous research agents (research runs in main context)
❌ No automation hooks (manual project ID specification)
❌ No Wardley Mapping skill with Pinecone MCP

Codex CLI (Core Support)

Recommended for: Teams using OpenAI Codex CLI or ChatGPT Plus/Pro/Enterprise.

Installation

# Install with pip
pip install git+https://github.com/tractorjuice/arc-kit.git

# Or with uv
uv tool install arckit-cli --from git+https://github.com/tractorjuice/arc-kit.git

# Or run without installing
uvx --from git+https://github.com/tractorjuice/arc-kit.git arckit init my-project

Project Initialization

# Create a new architecture governance project
arckit init payment-modernization --ai codex

# Minimal install (skip docs and guides)
arckit init payment-modernization --ai codex --minimal

# Or initialize in current directory
arckit init . --ai codex

Environment Setup

Recommended: Use direnv for automatic environment variables:

cd payment-modernization
direnv allow  # Automatically sets CODEX_HOME="$PWD/.codex"

Alternative: Export manually:

export CODEX_HOME="$PWD/.codex"

Usage

cd payment-modernization
codex

# Inside Codex, use ArcKit commands with /prompts: prefix
/prompts:arckit.principles Create principles for financial services
/prompts:arckit.requirements Build a payment processing system...
/prompts:arckit.sow Generate RFP for vendor selection

Updates

# Step 1: Upgrade the CLI tool
pip install --upgrade git+https://github.com/tractorjuice/arc-kit.git
# Or with uv:
uv tool upgrade arckit-cli --from git+https://github.com/tractorjuice/arc-kit.git

# Step 2: Update your existing project (re-run init in place)
cd /path/to/your-existing-project
arckit init --here --ai codex

This updates commands, templates, scripts while preserving your project data (projects/) and custom templates (.arckit/templates-custom/). Limitations compared to Claude Code:

❌ No autonomous research agents
❌ No automation hooks
❌ Manual MCP server setup required
❌ Manual updates (no marketplace)
⚙️ Requires arckit init project scaffolding

OpenCode CLI (Core Support)

Recommended for: Teams using OpenCode as their primary AI assistant.

Installation

# Install the ArcKit CLI
pip install git+https://github.com/tractorjuice/arc-kit.git

# Or with uv
uv tool install arckit-cli --from git+https://github.com/tractorjuice/arc-kit.git

Project Initialization

# Create a new architecture governance project
arckit init payment-modernization --ai opencode

# Or initialize in current directory
arckit init . --ai opencode

Environment Setup

Recommended: Use direnv:

cd payment-modernization
direnv allow  # Automatically sets OPENCODE_HOME="$PWD/.opencode"

Alternative: Export manually:

export OPENCODE_HOME="$PWD/.opencode"

MCP Server Configuration

ArcKit creates .opencode/opencode.json with MCP servers:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "aws-knowledge": {
      "type": "remote",
      "url": "https://knowledge-mcp.global.api.aws/sse",
      "enabled": true
    },
    "microsoft-learn": {
      "type": "remote",
      "url": "https://learn.microsoft.com/api/mcp/sse",
      "enabled": true
    },
    "google-developer-knowledge": {
      "type": "remote",
      "url": "https://developerknowledge.googleapis.com/mcp/sse",
      "headers": {
        "X-Goog-Api-Key": "${GOOGLE_API_KEY}"
      },
      "enabled": false
    }
  }
}

To enable Google Cloud research: Set GOOGLE_API_KEY environment variable and change "enabled": true.

Usage

cd payment-modernization
opencode

# Inside OpenCode, use ArcKit commands
/arckit.principles Create principles for financial services
/arckit.requirements Build a payment processing system...
/arckit.azure-research Research Azure Kubernetes Service

Updates

Same as Codex CLI:

# Step 1: Upgrade the CLI tool
pip install --upgrade git+https://github.com/tractorjuice/arc-kit.git

# Step 2: Update your existing project
cd /path/to/your-existing-project
arckit init --here --ai opencode

Limitations compared to Claude Code:

❌ No autonomous research agents
❌ No automation hooks
❌ Manual updates (no marketplace)
⚙️ Requires arckit init project scaffolding

Platform Support Matrix

Operating Systems

Platform	Claude Code Plugin	Gemini CLI Extension	Codex / OpenCode CLI
macOS	✅ Full support	✅ Full support	✅ Full support
Linux	✅ Full support	✅ Full support	✅ Full support
Windows (WSL2)	✅ Full support	✅ Full support	✅ Full support
Windows (native)	✅ Full support	✅ Full support	⚠️ Partial (see note)

Windows native users: The Claude Code plugin and Gemini CLI extension work natively on all platforms (all hooks and scripts are Python-based).For Codex CLI / OpenCode CLI on native Windows (without WSL), some commands containing inline bash snippets may require Git Bash or WSL2.Recommended: Use WSL2 for the best CLI experience on Windows.

Why Commands, Not Skills?

Claude Code automatically exposes ArcKit commands as skills (they appear in the skills list and can be matched by natural language). ArcKit intentionally uses slash commands rather than standalone skills because:

Deliberate Invocation

Every command generates heavyweight governance documents (requirements spec, risk register, DPIA). Auto-triggering from conversational intent would waste time and tokens.

Dependency Ordering

Commands follow a deliberate sequence (principles → stakeholders → requirements → data-model). Skills that auto-trigger could run out of order.

User Input via $ARGUMENTS

Most commands accept context from the user (project name, scope, constraints). The command system handles this with $ARGUMENTS substitution.

Best of Both Worlds

Claude Code exposes commands as skills automatically, so users get explicit /arckit.requirements invocation AND natural language matching when Claude recognizes intent.

Choosing Your Platform

Claude Code

Choose if:

You want the most complete ArcKit experience
You need autonomous research agents for complex projects
You want automated governance (hooks for filename enforcement, project context injection)
You want automatic updates via marketplace
You’re using Claude Code v2.1.63+

Installation: /plugin marketplace add tractorjuice/arc-kit

Gemini CLI

Choose if:

You’re already using Gemini as your primary AI assistant
You want zero-config installation
You want MCP servers bundled out of the box
You don’t need autonomous agents

Installation: gemini extensions install https://github.com/tractorjuice/arckit-gemini

Codex CLI

Choose if:

You’re using OpenAI Codex CLI or ChatGPT Plus/Pro/Enterprise
You’re comfortable with manual project initialization
You don’t need autonomous agents or hooks

Installation: pip install git+https://github.com/tractorjuice/arc-kit.git

OpenCode CLI

Choose if:

You’re using OpenCode as your primary AI assistant
You want MCP server support (AWS, Azure, Google Cloud)
You’re comfortable with manual project initialization

Installation: pip install git+https://github.com/tractorjuice/arc-kit.git

Migration Between Platforms

From CLI to Plugin/Extension

If you started with Codex/OpenCode CLI and want to switch to Claude Code plugin or Gemini CLI extension:

# Your existing projects/ directory is platform-agnostic
# Just install the plugin/extension and continue working

# For Claude Code:
/plugin marketplace add tractorjuice/arc-kit
# Commands now work without /prompts: prefix

# For Gemini CLI:
gemini extensions install https://github.com/tractorjuice/arckit-gemini
# Commands work immediately

Your architecture artifacts (projects/) work across all platforms - only the command invocation changes.

From Plugin/Extension to CLI

If you want to move from Claude Code/Gemini to Codex/OpenCode:

# Install the CLI
pip install git+https://github.com/tractorjuice/arc-kit.git

# Run init in your existing project directory
cd your-existing-project
arckit init --here --ai codex  # or --ai opencode

# This adds .codex/ or .opencode/ directories
# Your existing projects/ directory remains unchanged

Next Steps

Workflow

Understand the 16-phase ArcKit workflow

Project Structure

Learn about ArcKit’s directory structure

Templates

Customize ArcKit templates for your organization

Get Started

Initialize your first ArcKit project

Get Started

Core Concepts

Governance Workflow

Vendor Procurement

Design & Review

UK Government Compliance

Guides

​AI Assistant Support

​Platform Comparison

​Claude Code Plugin (Premier Experience)

​Installation

​Requirements

​Key Features

​Updates

​Usage

​Gemini CLI Extension (Full Support)

​Installation

​Key Features

​Updates

​Usage

​Codex CLI (Core Support)

​Installation

​Project Initialization

​Environment Setup

​Usage

​Updates

​OpenCode CLI (Core Support)

​Installation

​Project Initialization

​Environment Setup

​MCP Server Configuration

​Usage

​Updates

​Platform Support Matrix

​Operating Systems

​Why Commands, Not Skills?

Deliberate Invocation

Dependency Ordering

User Input via $ARGUMENTS

Best of Both Worlds

​Choosing Your Platform

​Migration Between Platforms

​From CLI to Plugin/Extension

​From Plugin/Extension to CLI

​Next Steps

Workflow

Project Structure

Templates

Get Started

Build docs developers (and LLMs) love

AI Assistant Support

Platform Comparison

Claude Code Plugin (Premier Experience)

Installation

Requirements

Key Features

Updates

Usage

Gemini CLI Extension (Full Support)

Installation

Key Features

Updates

Usage

Codex CLI (Core Support)

Installation

Project Initialization

Environment Setup

Usage

Updates

OpenCode CLI (Core Support)

Installation

Project Initialization

Environment Setup

MCP Server Configuration

Usage

Updates

Platform Support Matrix

Operating Systems

Why Commands, Not Skills?

Choosing Your Platform

Migration Between Platforms

From CLI to Plugin/Extension

From Plugin/Extension to CLI

Next Steps