# KarmaDue in Claude Code

Tested: 2026-11-12 with Claude Code 2.1.300 and the hook below (the `karmadue-preinstall.js` file served from this site).

There are two pieces, and you can use either or both:

1. **The MCP server.** Claude can call `ask` before it researches a problem, and `check_install` before it installs something.
2. **The PreToolUse hook.** This is enforcement. Before any Bash command that installs a package, the hook asks KarmaDue and blocks known-malicious versions. Claude cannot skip it.

## 1. MCP server (one command)

    claude mcp add --scope project --transport http karmadue https://ogogoizwsfaduzehkshb.supabase.co/functions/v1/mcp

It writes this to `.mcp.json`. Tested: the file below is exactly what Claude Code 2.1.300 wrote, and `claude mcp list` shows the server.

    {
      "mcpServers": {
        "karmadue": { "type": "http", "url": "https://ogogoizwsfaduzehkshb.supabase.co/functions/v1/mcp" }
      }
    }

The no-account safety profile, with five tools plus `ask`, is at `.../functions/v1/mcp/safety`. Claude Code asks you to approve a project-scoped server the first time it starts.

Optional: add a line to CLAUDE.md so Claude asks first:

    Before researching an error or installing a package, call the karmadue `ask` tool (for a problem) or `check_install` (for a package) and follow `enforce`.

## 2. PreToolUse hook (enforcement)

The install and settings steps are in [claude-code-hook.md](https://karmadue.expo.app/docs/claude-code-hook.md). We tested the hook by feeding it Claude Code's PreToolUse JSON on stdin. Real output, 2026-11-12 ~2:00 AM ET (trimmed):

| Command | Hook result |
|---|---|
| `npm install event-stream@3.3.6` | `permissionDecision: "deny"`. Reason: malicious-package report GHSA-mh6f-8j2x-4483, plus alternatives |
| `pip install requests==2.31.0` | Warns, not blocked. Claude is told: 3 published advisories, fixed in 2.33.0 |
| `npm i left-pad@1.3.0` | Warns: the publisher deprecated it ("use String.prototype.padStart()") |
| `ls -la` | No output, exit 0 (the normal permission flow) |

The hook never auto-approves anything. A warning or an unreachable KarmaDue leaves Claude Code's normal permissions in charge, unless you set `KARMADUE_STRICT=1`.

## Attribution (optional)

To help us see which setups people use, add the `X-KarmaDue-Via: claude-code` header. In `.mcp.json`: `"headers": {"X-KarmaDue-Via": "claude-code"}`. It is a free-text tag, stored as given. See [privacy](https://karmadue.expo.app/docs/privacy.md).