BackendStack21 · hamednourhani · Jun 23, 2026 · Jul 19, 2026 · Jul 19, 2026 · Jul 19, 2026
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -31,10 +31,20 @@ jobs:
           echo "Contents of kai-${{ steps.version.outputs.tag }}.zip:"
           unzip -l kai-${{ steps.version.outputs.tag }}.zip
 
+      - name: Create claude zip
+        run: |
+          zip -r kai-claude-${{ steps.version.outputs.tag }}.zip claude
+
+          # Verify zip contents
+          echo "Contents of kai-claude-${{ steps.version.outputs.tag }}.zip:"
+          unzip -l kai-claude-${{ steps.version.outputs.tag }}.zip
+
       - name: Create Release
         uses: softprops/action-gh-release@v1
         with:
-          files: kai-${{ steps.version.outputs.tag }}.zip
+          files: |
+            kai-${{ steps.version.outputs.tag }}.zip
+            kai-claude-${{ steps.version.outputs.tag }}.zip
           generate_release_notes: true
           draft: false
           prerelease: false

diff --git a/Makefile b/Makefile
@@ -23,6 +23,7 @@ test-preflight: lint-agents
 lint-agents:
 	@echo "Linting agent definitions..."
 	@bash -lc 'bash tests/check_agents.sh'
+	@bash -lc 'bash tests/check_claude_agents.sh'
 
 test-all: test-main
 	@echo ""

diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@
 
 ## 1. Overview & Vision
 
-Kai is a **Universal Brain** within the OpenCode agent's ecosystem — a single entry point for intelligent orchestration.
+Kai is a **Universal Brain** for AI coding agent ecosystems — a single entry point for intelligent orchestration, portable across [OpenCode](https://opencode.ai) and [Claude Code](https://claude.com/claude-code).
 
 In this architecture, Kai is the **sole primary agent** and decision-maker. All other agents act as specialized subagents that execute Kai's directives. Users interact _only_ with Kai. Kai analyzes requests, plans execution, routes to specialists, and ensures quality.
 
@@ -21,13 +21,15 @@ In this architecture, Kai is the **sole primary agent** and decision-maker. All
 
 ### Prerequisites
 
-- [OpenCode](https://opencode.ai) installed and configured
+- [OpenCode](https://opencode.ai) or [Claude Code](https://claude.com/claude-code) installed and configured
 - A terminal with bash or zsh
 - Git (optional, for cloning)
 
 ### Installation
 
-#### Quick Install (Recommended)
+#### OpenCode
+
+##### Quick Install (Recommended)
 
 Use the installer script to automatically download a specific Kai release and configure OpenCode:
 
@@ -69,7 +71,7 @@ curl -fsSL https://kai.21no.de/scripts/installer.sh | bash -s -- --help
 --repo OWNER/REPO    # Use custom GitHub repository (default: BackendStack21/kai)
 ```
 
-#### Manual Installation
+##### Manual Installation
 
 Alternatively, you can manually copy the `agents/` folder into your OpenCode configuration directory:
 
@@ -84,6 +86,52 @@ ln -s $(pwd)/kai-agents/agents ~/.config/opencode/agents
 
 The `agents/` folder is fully self-contained. Kai's agent definition (`agents/kai.md`) includes all behavioral instructions needed to operate — no external files required.
 
+#### Claude Code
+
+> **Note:** Unlike OpenCode (where installing sets Kai as the default agent), Kai runs as an explicitly-invoked subagent on Claude Code — install just adds it to your available agents, nothing changes until you summon it with `--agent kai` or `@agent-kai`.
+
+##### Quick Install (Recommended)
+
+Use the installer script to automatically download a specific Kai release and configure Claude Code:
+
+```bash
+# Download and run the installer
+curl -fsSL https://kai.21no.de/scripts/installer-claude.sh | bash -s -- latest --yes
+```
+
+```bash
+# Download and run the installer (replace latest with desired version)
+curl -fsSL https://kai.21no.de/scripts/installer-claude.sh | bash -s -- v1.2.2 --yes
+```
+
+> **Note:** Replace `v1.2.2` with the desired [release version](https://github.com/BackendStack21/kai/releases). The version can be specified with or without the `v` prefix (e.g., `v1.2.2` or `1.0.0`).
+
+**Installer Options:**
+
+```bash
+# See all available options
+curl -fsSL https://kai.21no.de/scripts/installer-claude.sh | bash -s -- --help
+
+# Common options:
+--yes, -y            # Skip confirmation prompts
+--backup             # Create backup before installing
+--verbose            # Show detailed progress
+--dry-run            # Preview changes without installing
+--config-dir PATH    # Use custom Claude Code config directory (default: ~/.claude)
+--output-dir PATH    # Use custom temporary directory
+--repo OWNER/REPO    # Use custom GitHub repository (default: BackendStack21/kai)
+```
+
+##### Manual Installation
+
+Alternatively, copy the `claude/agents/` folder into your Claude Code configuration directory:
+
+```bash
+cp claude/agents/*.md ~/.claude/agents/
+```
+
+Restart Claude Code or start a new session to load the new agents. See [claude/README.md](claude/README.md) for architecture details.
+
 ### How to Use Kai
 
 Simply address your request to Kai naturally. You do not need to know which subagent handles what.
@@ -94,6 +142,20 @@ Simply address your request to Kai naturally. You do not need to know which suba
 - **Research**: "Compare Redis vs. Memcached for session storage." -> _Kai routes to `@research`_
 - **Engineering**: "Add Google OAuth login to the user service." -> _Kai orchestrates the `@engineering-team` pipeline_
 
+### How to Use Kai on Claude Code
+
+Kai also runs natively as a [Claude Code](https://claude.com/claude-code) subagent (see [`claude/README.md`](claude/README.md) for setup).
+
+```bash
+# Session-wide: Claude IS Kai
+claude --agent kai
+
+# Per-task: summon Kai via @-mention, without switching the whole session
+@agent-kai build an auth system
+```
+
+Once summoned, it works exactly the same way — address requests naturally, Kai classifies and routes to the right subagent.
+
 ### Response Times
 
 | Request Type                         | Estimated Time |

diff --git a/claude/README.md b/claude/README.md
@@ -0,0 +1,51 @@
+# Kai on Claude Code
+
+To use Kai as your orchestrator on Claude Code:
+
+## Quick Start
+
+```bash
+# Session-wide: Claude IS Kai
+claude --agent kai
+
+# Per-task: summon Kai via @-mention
+@agent-kai build an auth system
+```
+
+See [Installation](#installation) below for the one-time agent setup.
+
+## Architecture
+
+Kai runs as a **subagent** on Claude Code. When invoked (via `--agent kai` or `@agent-kai`), Kai orchestrates a team of 21 specialized subagents:
+
+| Tier | Agents |
+|------|--------|
+| **Pipeline** | engineering-team, architect, developer, reviewer, tester, docs, devops |
+| **Quality** | security-auditor, performance-optimizer, integration-specialist, accessibility-expert |
+| **Research** | research, fact-check |
+| **Fast-Track** | explorer, doc-fixer, quick-reviewer, dependency-manager |
+| **Learning** | postmortem, refactor-advisor |
+| **Utility** | executive-summarizer, jira-writer |
+
+Kai uses Claude Code's `Agent` tool to spawn subagents, with full support for nested orchestration (subagents can spawn subagents in Claude Code v2.1.172+).
+
+## Installation
+
+See the root [README.md](../README.md#claude-code) "Claude Code" install section for the quick-install script and manual steps.
+
+## Agent File Format
+
+Each agent is a Markdown file with YAML frontmatter following Claude Code's subagent specification:
+
+```yaml
+---
+name: agent-name
+description: What the agent does and when to use it
+tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch
+model: inherit
+permissionMode: default
+color: cyan
+---
+```
+
+Kai agents don't use Claude Code's native `memory:` frontmatter field — project memory is handled entirely through the cross-platform `.kai/` directory convention (see root `README.md` §14), so the same memory is visible whether Kai runs under OpenCode, Claude Code, or another host.