Back to ArcKit

This quick start is the official ArcKit AI harness setup path for new projects. Pick your AI platform, install the core plugin or extension, then run the first command to create traceable architecture governance artifacts.

Choose your AI platform

1

Install Claude Code

macOS, Linux & WSL:

curl -fsSL https://claude.ai/install.sh | bash

Windows (PowerShell):

irm https://claude.ai/install.ps1 | iex

Already have claude on your PATH? Make sure you're on the latest:

claude install latest
ArcKit requires Claude Code v2.1.156 or later. claude install accepts stable, latest, or a specific version. The plugin warns at session start if you're below the supported floor. See setup docs for Homebrew and WinGet alternatives.
2

Install ArcKit Plugins

/plugin marketplace add tractorjuice/arckit-claude

Install the core Claude Code plugin from Discover, or via CLI:

# Core (UK Government civilian + generic enterprise)
claude plugin install arckit@arckit-claude

The same marketplace also contains regional, sector, and tooling overlays. Install only the plugins you need:

# Core + UAE overlay
claude plugin install arckit arckit-uae

# Broad overlay set
claude plugin install arckit arckit-{uae,fr,ca,eu,at,au,us,uk-nhs,uk-gcloud}

The community overlay plugins auto-install the arckit core plugin as a declared dependency. The arckit-uk-gcloud overlay is public for installation and inspection, but remains proprietary and is not MIT licensed. Updates are automatic via the marketplace.

3

Open Your Project

cd my-project
claude
4

Get Oriented

/arckit:start

Shows project status, connected tools, command decision tree, and recommended next steps.

5

Initialize Project Structure

/arckit:init

Creates the projects/ directory structure for architecture artifacts.

1

Install Gemini CLI

npm (requires Node.js 20+):

npm install -g @google/gemini-cli

Homebrew (macOS & Linux):

brew install gemini-cli
2

Install ArcKit Extension

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

Zero-config: ArcKit commands, templates, scripts, and bundled MCP servers. Update with gemini extensions update arckit.

3

Open Your Project

cd my-project
gemini
4

Get Oriented

/arckit:start

Shows project status, connected tools, command decision tree, and recommended next steps.

5

Initialize Project Structure

/arckit:init

Creates the projects/ directory structure for architecture artifacts.

1

Install Codex CLI

npm (requires Node.js 22+):

npm install -g @openai/codex

Homebrew:

brew install codex
2

Install ArcKit Plugin

Add the ArcKit Codex marketplace:

codex plugin marketplace add tractorjuice/arckit-codex

Enable lifecycle hooks in your user or project Codex config:

# ~/.codex/config.toml or .codex/config.toml
[features]
hooks = true
plugin_hooks = true

Restart Codex, run /plugins, choose ArcKit Plugins, then install and enable ArcKit. The plugin bundles ArcKit command skills, reference skills, agent configs, MCP config, templates, schemas, scripts, and hooks/hooks.json.

Prefer a project-scoped copy instead? Use arckit init my-project --ai codex from the ArcKit CLI.

3

Open Your Project

cd my-project
codex
4

Get Oriented

$arckit-start

Shows project status, connected tools, command decision tree, and recommended next steps.

5

Initialize Project Structure

$arckit-init

Creates the projects/ directory structure for architecture artifacts.

1

Install OpenCode CLI

Install script (recommended):

curl -fsSL https://opencode.ai/install | bash

npm:

npm install -g opencode-ai

Homebrew (macOS & Linux):

brew install anomalyco/tap/opencode
2

Install ArcKit CLI & Initialize Project

Install the ArcKit CLI, then initialize your project:

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

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

# Initialize project
arckit init my-project --ai opencode

This copies ArcKit commands, templates, and scripts into your project.

3

Open Your Project

cd my-project
opencode
4

Get Oriented

/arckit:start

Shows project status, connected tools, command decision tree, and recommended next steps.

5

Initialize Project Structure

/arckit:init

Creates the projects/ directory structure for architecture artifacts.

1

Install VS Code & GitHub Copilot

Install VS Code and the GitHub Copilot extension.

Requires a GitHub Copilot subscription (Individual, Business, or Enterprise).
2

Install ArcKit CLI & Initialize Project

Install the ArcKit CLI, then initialize your project:

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

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

# Initialize project
arckit init my-project --ai copilot

This scaffolds ArcKit prompt files, research agents, templates, and scripts into your project.

3

Open Your Project in VS Code

code my-project
4

Use Commands in Copilot Chat

Open Copilot Chat (Ctrl+Shift+I / Cmd+Shift+I) and type / to see all arckit-* commands in autocomplete.

/arckit-start

Shows project status, command decision tree, and recommended next steps.

5

Initialize Project Structure

/arckit-init

Creates the projects/ directory structure for architecture artifacts.

1

Install Mistral Vibe

Install Mistral Vibe CLI using Mistral's current installer, then confirm the CLI is available:

vibe --version
ArcKit for Vibe is a local extension. The Vibe CLI must already be installed and authenticated before you link the ArcKit extension.
2

Install ArcKit Extension

Clone the generated ArcKit Vibe extension and link it into your Vibe extensions directory:

git clone https://github.com/tractorjuice/arckit-vibe.git
cd arckit-vibe
mkdir -p ~/.vibe/extensions/
ln -s "$(pwd)" ~/.vibe/extensions/arckit

The extension bundles ArcKit skills, Vibe agent TOML files, templates, schemas, scripts, reference materials, and MCP configuration. Update it later with git pull from the cloned extension repository.

3

Open Your Project

cd my-project
vibe
4

Get Oriented

/arckit-start

Shows project status, connected tools, command decision tree, and recommended next steps.

5

Initialize Project Structure

/arckit-init

Creates the projects/ directory structure for architecture artifacts.

Fast path

Vibe Start — the 3-prompt super prompt

Skip the decision tree. Three prompts take you from empty repo to a fully-populated project. ArcKit chains commands via the handoffs: metadata in each command's frontmatter.

Use your platform syntax: Claude Code, Gemini CLI, and OpenCode use /arckit:command; Codex CLI uses $arckit-command; GitHub Copilot and Mistral Vibe use /arckit-command.

Claude Code / Gemini CLI / OpenCode example:

/arckit:init This is a project for {one-line description of what you're building}.
/arckit:principles

Codex CLI example:

$arckit-init This is a project for {one-line description of what you're building}.
$arckit-principles

GitHub Copilot / Mistral Vibe example:

/arckit-init This is a project for {one-line description of what you're building}.
/arckit-principles
Now create all the artifacts. Take your time. Do not stop until complete.

When to use it: greenfield projects, demos, proofs of concept, vibe-coding sessions where you want a complete first-pass set of artifacts to react to.

When not to use it: heavily regulated work (Secure by Design, MOD, EU AI Act) where each artifact needs reviewer sign-off; existing projects with artifacts already on disk (run /arckit:navigator first); token-constrained sessions.

If the run stalls: resume with "Continue from where you stopped. Do not stop until complete." Then run your platform's health command (/arckit:health, $arckit-health, or /arckit-health) to spot anything skipped. Full guide: Getting Started with ArcKit.

Faster path (Claude Code only)

The GDS Harness — /arckit:build

New in v4.13.0. Run one command and the whole architecture builds itself: requirements, stakeholder analysis, ADRs, risk register, business case, designs, Secure-by-Design assessment, DPIA, diagrams, traceability matrix, plus the post-build health check. Reads a YAML recipe, dispatches subagents in parallel waves, commits each wave atomically.

/arckit:build 001 --plan
/arckit:build 001
/arckit:build 002 --recipe uk-mod-sovereign
/arckit:build 003 --recipe uae-federal-ai
/arckit:build 004 --recipe ca-federal-fitaa

Four built-in recipes: uk-saas (38 targets, UK civilian SaaS), uk-mod-sovereign (38 targets, MOD / air-gapped with JSP 936 and MOD Secure by Design), uae-federal-ai (48 targets, UAE Cabinet agentic AI decree compliance with all 12 UAE community commands), and ca-federal-fitaa (Canada Federal FITAA-class compliance suite — all 12 ca-* commands plus core architecture governance).

Every recipe ships a research wave by default. An upstream ORG_RESEARCH target researches the target organisation once per repo (output to projects/000-global/research/), then per-project technology research runs in parallel (general market, AWS, Azure, GCP, plus GOV_REUSE for UK projects). Skip what you don't need with --exclude AZURE_RESEARCH etc.

Customize: copy a recipe to .arckit/recipes/{name}.yaml and edit. The harness reads project overrides first, falling back to the plugin defaults — your customisations survive plugin updates.

Resumable: state persists to projects/{P}/.arckit/state.json. If a wave fails, fix the underlying issue and run /arckit:build 001 --resume to pick up exactly where it stopped.

Other platforms note: this command is not generated for Codex, Gemini, OpenCode, GitHub Copilot, or Mistral Vibe. The build harness depends on Claude Code's parallel agent dispatch and plugin hook behaviour, so there is no supported non-Claude build-harness command.

When to use it: end-to-end governance builds where you want a full template-driven artefact set committed in atomic, reviewable waves. Full guide: Build Harness Guide.

6

Follow GDS Phases

Commands shown use Claude Code / Gemini CLI / OpenCode syntax (/arckit:command). For Codex CLI use $arckit-command. For GitHub Copilot and Mistral Vibe use /arckit-command.

Discovery

/arckit:stakeholders Analyze stakeholders for appointment system
/arckit:risk Create risk register
/arckit:sobc Generate Strategic Outline Business Case

Alpha

/arckit:requirements Define requirements
/arckit:principles Establish architecture principles
/arckit:wardley Create Wardley Map for build vs buy decisions

Beta

/arckit:hld-review Review High-Level Design
/arckit:diagram Create C4 architecture diagrams
/arckit:analyze Comprehensive gap analysis
Warning AI generates first drafts following templates. Always review, validate, and refine AI output with human expertise.

Next Steps

Command Reference

Browse the ArcKit command set with filters and dependency matrix.

Command Guides

Step-by-step guides with prerequisites and real-world examples.

DDaT Role Guides

Find commands tailored to your UK Government DDaT role.

Example Projects

See AI-generated architecture documentation from real-world scenarios.