> ## Documentation Index
> Fetch the complete documentation index at: https://kasava.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code Plugin

> Install the Kasava plugin for Claude Code to get product intelligence in your coding workflow

The [Kasava web app](https://app.kasava.dev) is where you create plans, generate documents, manage settings, and view analytics dashboards. **The Claude Code plugin gives you those plans plus product intelligence while you code** — without context-switching back to the web.

The plugin bundles MCP tools, 6 auto-trigger Agent Skills, 8 slash commands, and 4 subagents into a single installable package.

## Installation

### From the official marketplace

Anthropic auto-registers `claude-plugins-official`. Once Kasava is listed there, this is the simplest path:

```
/plugin install kasava@claude-plugins-official
```

### From our marketplace (today)

```
/plugin marketplace add kasava-dev/claude-code-plugin
/plugin install kasava@kasava-dev
```

### Test locally

```bash theme={null}
git clone https://github.com/kasava-dev/claude-code-plugin
claude --plugin-dir ./claude-code-plugin
```

## Setup

<Steps>
  <Step title="Create an API key">
    Go to [**Settings → API Keys**](https://app.kasava.dev/settings/api-keys) in Kasava and click **Create API Key**. Copy the key immediately — it's only shown once. Format: `kasava_live_…` or `kasava_test_…`.
  </Step>

  <Step title="Enter the key in Claude Code">
    When Claude Code prompts for your API key, paste it. The key is stored securely in your system keychain.

    **Already running the [Kasava CLI](/docs/developer/cli)?** The same API key works in both. Just paste it again, or `eval "$(kasava env)"` in your shell to share it via `KASAVA_TOKEN`.
  </Step>

  <Step title="Optional: install the CLI alongside">
    The plugin auto-discovers a local `.kasava/` artifact if you've run `kasava install` + `kasava sync` in the repo. That gives the plugin zero-token-cost access to plans, graph, and symbols.

    ```bash theme={null}
    npm i -g @kasava/cli
    cd /path/to/your/repo
    kasava install   # binds the repo to a product
    kasava sync      # pulls plans, graph, symbols, work items
    ```
  </Step>

  <Step title="Start coding">
    Claude automatically uses Kasava tools and skills when relevant. You can also invoke slash commands explicitly with `/kasava:<command>`.
  </Step>
</Steps>

## What's Included

### MCP connection (8 tools)

The plugin connects to Kasava's MCP server at `api.kasava.dev/v1/mcp/sse`, exposing:

| Tool                   | Purpose                                                                |
| ---------------------- | ---------------------------------------------------------------------- |
| `code-tool`            | Symbol search, definitions, usages, dependencies, semantic code search |
| `commit-tool`          | Commit history with semantic analysis, hotspots, changelog             |
| `search-tool`          | Unified search across code/issues/plans/docs/competitors               |
| `document-search-tool` | Customer signals + plans + product docs                                |
| `competitor-tool`      | Live competitor intel and content scrapings                            |
| `entity-analysis-tool` | Graph traversal of features, layers, symbols                           |
| `spec-export-tool`     | Plan spec in agent-prompt format                                       |
| `record-decision-tool` | Write decision against the bound product                               |

Plus 3 Mastra agents (`ask_codeIntelligenceAgent`, `ask_productInsightsAgent`, `ask_architectureInvestigationAgent`) and 2 workflows (`run_bugAnalysisWorkflow`, `run_deepResearchWorkflow`).

The toolset is intentionally small (cut from 23 in May 2026 — see ADR-0015). Cacheable data — product graph, work breakdowns, ownership, rationale — lives in your local `.kasava/` artifact instead, refreshed by `kasava sync`. The plugin's skills prefer the artifact over MCP for that data, then fall through to MCP for live queries.

### 6 auto-trigger skills

These activate when Claude detects matching user intent.

| Skill            | Triggers when you ask…                                      |
| ---------------- | ----------------------------------------------------------- |
| `kasava-context` | Anything in a `.kasava/`-bound repo (paths-scoped)          |
| `kasava-product` | "what's the architecture / features / tech stack"           |
| `kasava-code`    | "where is X defined", "what depends on Y"                   |
| `kasava-bug`     | Pasting a stack trace, "debug this", "investigate this bug" |
| `kasava-plan`    | "implement the plan for X", "what does the spec say"        |
| `kasava-signals` | "what are users saying", "any bug reports"                  |

### 8 slash commands

User-invoked only — these don't auto-trigger so you control when they run.

| Command                     | Effect                                              | Cost         |
| --------------------------- | --------------------------------------------------- | ------------ |
| `/kasava:install`           | Bind this repo to a Kasava product                  | Free         |
| `/kasava:sync`              | Refresh `.kasava/` artifact                         | Free         |
| `/kasava:plan <name>`       | Print the agent-spec for a plan                     | Free         |
| `/kasava:ask "<q>"`         | Offline keyword search across `.kasava/`            | Free         |
| `/kasava:ask-ai "<q>"`      | Stream AI-synthesized answer from the Kasava agent  | **Billable** |
| `/kasava:staleness`         | List documents whose code references have changed   | Free         |
| `/kasava:decision "<text>"` | Record a decision on the bound product              | Free         |
| `/kasava:status`            | Show binding info, last sync, next-step suggestions | Free         |

The two billable variants (`/kasava:ask-ai` and `kasava sync --ai`) are deliberately **not** in the allowlist — Claude Code prompts every invocation so credits never get spent without your click.

### 4 subagents

Delegate read-heavy investigations instead of running them in the main thread. They run in isolated context and return a focused summary.

| Subagent                 | When to delegate                                                   | Model                            |
| ------------------------ | ------------------------------------------------------------------ | -------------------------------- |
| `kasava-developer`       | Starting a coding task; want auto-loaded context + project memory  | inherit                          |
| `kasava-bug-triager`     | Bug or stack trace investigation                                   | haiku                            |
| `kasava-spec-loader`     | Starting work from a plan name/slug                                | inherit                          |
| `kasava-impact-assessor` | Before non-trivial edits — walks dependents, owners, related plans | haiku (read-only, no Write/Edit) |

Invoke with `@<agent-name>`:

```
@kasava-bug-triager investigate this stack trace: <paste>
@kasava-spec-loader load the plan "improve-onboarding"
@kasava-impact-assessor what would change if I modify processPayment
```

### UserPromptSubmit hook

The plugin installs a hook at `${CLAUDE_PLUGIN_ROOT}/scripts/inject-context.sh` that fires on every prompt. When you're inside a `.kasava/`-bound repo, it injects:

* A reminder to read `.kasava/PRODUCT_MAP.md`, `plans/*.md`, and the local artifact first
* The CLI commands available (`kasava plan`, `kasava ask`, `kasava ownership`, etc.)
* A "View in Kasava → app.kasava.dev/products/…" deep link
* A staleness hint if `.kasava/config.json` is more than 7 days old

Outside a bound repo it exits silently. Always exits 0 (fail-open).

## Usage Examples

**Load product context before coding:**

```
What's the architecture of our product?
```

The `kasava-context` and `kasava-product` skills activate, read `.kasava/PRODUCT_MAP.md` and `graph.json`, and surface feature areas, architecture layers, and tech stack.

**Search code with the symbol graph:**

```
Find where AuthService.validateToken is defined and what depends on it
```

The `kasava-code` skill activates, calls `code-tool` action `search_symbols` then `find_dependencies`, and returns the definition with its dependents.

**Investigate a bug (delegated):**

```
@kasava-bug-triager investigate why /api/billing returns 403 for some users
```

The subagent runs the 3-way investigation (code + commits + customer signals) in isolation and returns a one-page triage summary with hypothesis, recent risky commits, and customer impact.

**Implement from a plan:**

```
@kasava-spec-loader load the plan for payment-retry-logic
```

The subagent pulls the spec from `.kasava/plans/`, resolves named symbols to current implementations, and returns a starter brief with acceptance criteria and a suggested first step.

**Record a decision:**

```
/kasava:decision "Use Drizzle for ORM" --type technology --rationale "Better PG support than Prisma"
```

Direct shell-out to the CLI's `kasava decisions add`. Returns the new decision ID and a deep link to the product timeline.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Plugin not loading">
    Run `/plugin validate .` from the plugin directory. Confirm Claude Code is on a recent version.
  </Accordion>

  <Accordion title="MCP connection failing">
    Verify your API key at [Settings → API Keys](https://app.kasava.dev/settings/api-keys). Test connectivity with:

    ```bash theme={null}
    curl -H "Authorization: Bearer $KASAVA_TOKEN" https://api.kasava.dev/v1/mcp/sse
    ```
  </Accordion>

  <Accordion title="Skills not triggering automatically">
    Try invoking directly: `/kasava:kasava-product`. If that works, the skill description may not match your phrasing — try rephrasing or just use the slash command. Skill descriptions are tuned for natural phrasing like "what's the architecture" rather than abstract terms like "structural overview".
  </Accordion>

  <Accordion title="Tools returning empty results">
    Ensure you have at least one indexed repository in Kasava. Check the repository's index status in the Kasava dashboard at [app.kasava.dev](https://app.kasava.dev).
  </Accordion>

  <Accordion title="`.kasava/` not found in this repo">
    The plugin works without the local artifact (it falls back to MCP for everything), but you'll get more value with it. Run `kasava install` then `kasava sync` in the repo root. See the [CLI guide](/docs/developer/cli) for setup.
  </Accordion>

  <Accordion title="Claude trying to run `--ai` variants without asking">
    The plugin's permission allowlist deliberately excludes `kasava sync --ai` and `kasava ask --ai`. Claude Code should always prompt before running them. If it doesn't, your `~/.claude/settings.json` may have an overly broad allowlist — check for a `Bash(kasava *)` rule that bypasses the per-command exact-match.
  </Accordion>
</AccordionGroup>