# Arth AI Plugins — Canary

**arthai** turns Claude Code into a full engineering team. Instead of one assistant doing everything at premium cost, you get 38 specialized agents (QA, SRE, frontend, backend, planning…), 60 slash-command workflows (`/planning`, `/qa`, `/pr`, `/fix`…), and 29 automatic hooks (guardrails, routing, telemetry) — installed as Claude Code plugins and adapted to your codebase by `/calibrate`.

Built for teams that ship with Claude Code daily and want battle-tested workflows, cheaper model routing, and an audit trail of what the AI actually did. Pairs with **[Arth Intelligence](docs/arth-intelligence.md)** — a local dashboard showing every session, tool call, agent spawn, and dollar spent.

New here? Read [What is arthai?](docs/what-is-arthai.md) (2 minutes), then follow the Quick Start below.

> **Canary channel.** This repo tracks every toolkit change as it lands — new versions ship many times a day and may occasionally break.
> For day-to-day use, install the manually-promoted **stable** release instead (your Arth AI contact will point you to it).

## Prerequisites

- [Claude Code](https://claude.ai/code) installed and working
- **Node.js 22+** (for `npx arthai-activate`)
- **Git**
- **macOS or Linux**
- An Arth AI license key (`ARTH-XXXX-XXXX-XXXX-XXXX`)

## Quick Start

> **Already installed?** You don't need these steps again — see [Updating](#updating) to get the latest version, or [Troubleshooting](#troubleshooting) if something's off.

**Step 1: Get a license key** — email **productive@getarth.ai** with your **GitHub username**. You'll receive a license key AND a collaborator invite to the private plugin repo — **accept the GitHub invite before Step 3**, or the marketplace add will fail.

**Step 2: Activate your key** (in terminal, not Claude Code)
```bash
npx arthai-activate ARTH-XXXX-XXXX-XXXX-XXXX
```
This stores your key at `~/.arthai/license`. All future sessions use it automatically.

**Step 3: Add the plugin repo** (in Claude Code)
```
/plugin marketplace add ArthTech-AI/arthai-marketplace
```

**Step 4: Install a bundle** (in Claude Code)
```
/plugin install prime@arthai
```
`prime` is the everything bundle — all agents, skills, and hooks. To pick a focused bundle instead, see [Bundles](#bundles) below.

**Step 5: Reload and enable auto-updates** (in Claude Code)
```
/reload-plugins
```
Then run `/plugin`, open the **Marketplaces** tab, select `arthai`, and choose **Enable auto-update** — new versions land automatically.

**Step 6: Enable observability — _Optional_** ⚠️ *experimental, limited preview*

> **You can skip this step and jump to Step 7 (Calibrate).** The toolkit works without observability. Come back whenever you want a dashboard view of what Claude Code is doing — sessions, tool calls, agent spawns, cost.

See every session, tool call, agent spawn, and dollar spent in a local dashboard ([what is Arth Intelligence?](docs/arth-intelligence.md)):

```
/otel-setup    # telemetry-only: pick "Local" — if you didn't install prime, run /plugin install sentinel@arthai first
/cloud-setup   # optional: enable "Explain this session" + the experimental Cloud Orchestrator
```

Then **restart Claude Code** and open **http://localhost:3100**. Full setup, verification, dashboard tour, and troubleshooting: **[Arth Intelligence guide](docs/arth-intelligence.md)**.

**Step 7: Calibrate your project** (in Claude Code)
```
/calibrate                  # auto-configure for your codebase (first time)
```

`/calibrate` deep-learns your project's architecture, patterns, and domain, and seeds a knowledge base. The knowledge graph is built from it automatically at the start of your next session, and workflows like `/fix` and `/qa` query it for relevant context.

**Step 8: Start a new Claude Code session**

Restart your Claude Code session so the knowledge graph gets built and the OTEL env block is picked up. Then:

```
/onboard                    # prioritized briefing on what to work on
/planning my-feature        # start building with the toolkit
```

## What do you want to do?

| I want to... | Run |
|---|---|
| Think through a vague idea or question (grounded in your repo) | `/brainstorm <thought>` |
| Get a briefing on my project | `/onboard` |
| Plan a feature (PRD + design spec) | `/planning my-feature` |
| Build a feature from a plan | `/implement my-feature` |
| Fix a bug properly (root cause + regression tests) | `/fix #42` |
| Run QA on my changes | `/qa` |
| Ship a PR | `/precheck` then `/pr` |
| Repair a failing CI pipeline | `/ci-fix` |
| Check service health / triage an incident | `/sre status`, `/incident` |
| Work autonomously through my issue backlog | `/autopilot` |
| See every command available, by category | `/skills` |
| Decide which command fits a task | `/routing <task>` |
| See what the AI did — traces, agents, cost | [Arth Intelligence](docs/arth-intelligence.md) |

Every skill, with usage: [Skills reference](docs/skills-reference.md).

## Bundles

Pick what you need. Each bundle is a self-contained set of agents, skills, and hooks.
### Development

| Bundle | Install | What you get |
|--------|---------|-------------|
| **forge** | `/plugin install forge@arthai` | Full development workflow — plan, build, test, ship |
| **scalpel** | `/plugin install scalpel@arthai` | Surgical bug fixing — targeted fixes, CI repair, issue triage |
| **spark** | `/plugin install spark@arthai` | Project setup and onboarding — calibrate, scan, bootstrap |

### Operations

| Bundle | Install | What you get |
|--------|---------|-------------|
| **prism** | `/plugin install prism@arthai` | Deep QA — multi-agent testing, baseline tracking, incident analysis |
| **sentinel** | `/plugin install sentinel@arthai` | Operations and reliability — SRE, incidents, deploy monitoring |
| **shield** | `/plugin install shield@arthai` | Safety guardrails — bash guards, edit protection, session bootstrap, opt-in compliance extensions |

### Strategy

| Bundle | Install | What you get |
|--------|---------|-------------|
| **atlas** | `/plugin install atlas@arthai` | Research + knowledge — topic wikis, deep explore, codebase search |
| **canvas** | `/plugin install canvas@arthai` | Design-driven development — adversarial design critique + frontend |
| **compass** | `/plugin install compass@arthai` | Product strategy — PM, GTM, user research, content strategy |
| **counsel** | `/plugin install counsel@arthai` | AI consulting toolkit — client discovery, proposals, deliverables |

### Power

| Bundle | Install | What you get |
|--------|---------|-------------|
| **cruise** | `/plugin install cruise@arthai` | Autonomous orchestration — /goal (single objective, fast) and /autopilot (backlog, rigorous). Requires forge+scalpel+sentinel. |
| **prime** | `/plugin install prime@arthai` | Everything — all agents, skills, and hooks in one plugin |

## Workflows

After installing, use skills in Claude Code:

**Start a new project:**
```
/onboard                    # get project briefing
/calibrate                  # auto-configure toolkit for your codebase
/planning my-feature        # design the feature with architect + PM agents
/implement my-feature       # build with parallel agent team
```

**Fix a bug:**
```
/fix #42                    # root cause analysis + fix + regression tests
/ci-fix                     # auto-repair CI failures
```

**Quality assurance:**
```
/qa                         # targeted QA on changed files (4-layer strategy)
/qa full                    # comprehensive check across all files
/qa e2e-gen                 # generate Playwright tests for UI changes (opt-in)
/qa visual                  # visual regression with computer-use (opt-in)
/qa staging                 # validate staging deployment
```

**Ship code:**
```
/precheck                   # local CI in 30s
/qa commit                  # targeted QA on changed files
/pr                         # create PR with QA results
```

**Autonomous mode:**
```
/autopilot                  # picks up issues, implements, QAs, creates PRs
```

**Operations:**
```
/sre status                 # health check all services
/incident                   # triage + parallel diagnosis
/restart                    # restart local dev servers
```

## Browseable Project Wiki

Every skill output — plans, specs, QA reports, goals, knowledge-base entries, project profile, topic wikis — is automatically mirrored to a sibling `.html` file the moment it's written, and rolled up into `.claude/html-index.html`. Open that one file in your browser and you have a searchable, cross-linked wiki of everything the toolkit has produced.

```bash
open .claude/html-index.html        # macOS
xdg-open .claude/html-index.html    # Linux
```

**Three tabs** — Overview (card grid grouped by kind), Recent (flat chronological list, newest first), Tree (collapsible folder hierarchy). A search bar filters all three at once.

**What triggers a render:** any `.md` written under `.claude/{plans,specs,qa,reports,.goals,knowledge/shared,wikis}` or `.claude/project-profile.md`. The `post-html-render` hook fires after the tool call, never blocks it, and is idempotent.

**Disable:** `CLAUDE_AGENTS_DISABLE_HTML=1`.

Currently shipped in the `prime` bundle.

## Observability — Experimental, Limited Preview

> ⚠️ **Experimental — limited preview.** Observability is in active development. Expect rough edges, breaking changes between releases, and gaps in coverage. Feedback welcome at productive@getarth.ai.

**[Arth Intelligence](docs/arth-intelligence.md)** is the toolkit's local observability stack. The toolkit's OTEL hook emits a span for every prompt, tool call, agent spawn, skill invocation, and stop event; Claude Code's native OTEL adds per-call cost and token data. Both streams flow into a local Docker container with a dashboard at `http://localhost:3100`. Everything stays on your machine.

### Prerequisites

- **Docker Desktop** installed and running ([download](https://www.docker.com/products/docker-desktop/))
- **Ports 4319, 3100, 5432 available** on `localhost` (engine, dashboard, postgres)
- The **sentinel** plugin installed (or **prime**, which includes sentinel)

### Setup (one time)

```
/plugin install sentinel@arthai    # otel-telemetry hook + /otel-setup skill
/otel-setup                          # interactive: pick "Local", then restart Claude Code
```

Everything else — what the dashboard shows, step-by-step verification, baseline vs. toolkit A/B comparison, what survives a reboot, updating, disabling, and troubleshooting — lives in the **[Arth Intelligence guide](docs/arth-intelligence.md)**.

## Updating

**The toolkit.** Turn on auto-updates once and new agents, skills, and fixes land automatically: run `/plugin`, open the **Marketplaces** tab, select `arthai`, choose **Enable auto-update**.

Or update manually at any time:

```
/plugin marketplace update arthai              # refresh the catalog
/plugin uninstall prime@arthai                 # then reinstall your bundle
/plugin install prime@arthai
/reload-plugins
```

**What changed / what version am I on?** Run `/plugin` in Claude Code — installed bundles show their version. Release notes: [CHANGELOG](https://github.com/ArthTech-AI/arthai-marketplace/blob/main/CHANGELOG.md).

If an update doesn't seem to take, use the full reset in [Troubleshooting](#troubleshooting).

**Arth Intelligence** (if you enabled observability) updates itself — a Watchtower sidecar pulls the latest image daily and your trace data is preserved. Manual update and details: [Arth Intelligence guide](docs/arth-intelligence.md#operations).

## Uninstall

**Step 1 — Remove the plugins (in Claude Code):**

```
/plugin uninstall prime@arthai        # repeat for each bundle you installed
/plugin marketplace remove arthai
```

This removes the skills, agents, and hooks that live inside the plugin directory.

**Step 2 — Fully quit and reopen Claude Code.** This is the step that prevents
hook errors: it drops the plugin's hooks from the running session. Don't just
`/clear` — quit the app/CLI completely, clean up, then reopen.

**Step 3 — Full clean removal** (managed `CLAUDE.md`/`.gitignore` blocks, toolkit
state files, global cache, and Arth Intelligence/Docker teardown): follow the
complete step-by-step in the **[Uninstall guide](docs/uninstall.md)**.

**What's preserved on purpose:** content the toolkit *generated* for you —
`.claude/knowledge/`, `.claude/plans/`, `.claude/specs/`, `.claude/qa-knowledge/`,
`.claude/wikis/`, `.claude/project-profile.md` — is never deleted by uninstall.
It's yours (the guide shows how to remove it too if you want a bare project).

## Troubleshooting

| Problem | Fix |
|---------|-----|
| Skills not showing after install | `/reload-plugins` then restart Claude Code |
| "LICENSE REQUIRED" on every prompt | Run `npx arthai-activate ARTH-XXXX-...` in terminal |
| "LICENSE INVALID" | Check your key: `cat ~/.arthai/license` — contact productive@getarth.ai if wrong |
| Old version stuck | `rm -rf ~/.claude/plugins/cache/*arthai*` then reinstall |
| Marketplace not loading | `/plugin marketplace remove arthai` then re-add |
| `marketplace add` fails (auth / not found) | Accept the GitHub collaborator invite from Step 1 first — the plugin repo is private |
| CLAUDE.md not created after install | Restart Claude Code — setup hook fires on session start |

**Full reset:**
```
/plugin marketplace remove arthai
rm -rf ~/.claude/plugins/cache/*arthai*
/plugin marketplace add ArthTech-AI/arthai-marketplace
/plugin install prime@arthai
/reload-plugins
```

## Links

- [What is arthai?](docs/what-is-arthai.md)
- [Getting started guide](docs/getting-started.md)
- [Tutorials](docs/tutorials/ship-your-first-pr.md) — ship your first PR, calibrate a project, plan-and-implement a feature
- [Guides](docs/guides/fix-a-production-incident.md) — task-by-task how-tos (incidents, CI recovery, autonomous work, cost measurement…)
- [Concepts](docs/concepts/architecture.md) — how the architecture, knowledge system, and release channels work
- [Arth Intelligence — observability](docs/arth-intelligence.md)
- [Arth Platform — usage guide](docs/platform-usage-guide.md) — Memory + Router + Intelligence API reference
- [Skills reference](docs/skills-reference.md)
- [Agents reference](docs/agents-reference.md)
- [Hooks reference](docs/hooks-reference.md)
- [Plugin catalog](docs/plugin-catalog.md)
- [QA guide](docs/qa-guide.md)
- [Configuration](docs/configuration.md)
- [FAQ](docs/faq.md)

_Auto-generated on 2026-07-16 — v1.0.205_