PortalLocal development

developer docs

Build and run Isonapse Dev.

overview

What is Isonapse Hook.

Isonapse hook is a local control plane that sits between Claude Code and your machine. It gates tool calls, detects PII, logs a cryptographic witness chain, and injects secrets — all running locally with no data leaving your machine.

install

Get started.

Prerequisites

prerequisite

Claude Code

The Anthropic CLI — required to receive hook events.

1. Download the binary

Binary downloads coming soon. Check back here for platform-specific installers.

2. Install and initialize the hook

setup

1isonapse hook install2isonapse hook init

install registers the plugin with Claude Code. init creates your local configuration and policy files.

3. Download intelligence models

models

1isonapse hook intel download

Downloads ONNX models from HuggingFace for on-device PII detection and prompt injection analysis. All inference runs locally — no data is sent externally.

4. Restart Claude Code after hook install and hook init so the plugin loads on startup. Then start the sidecar in a dedicated terminal with isonapse hook serve.

hook

Hook modes.

The hook runs in one of two modes. Start in profile to build a behavioral baseline, then switch to enforce once you've generated enough observations.

profile mode

Observe and learn

The default. Every tool call is witnessed and recorded but nothing is blocked. Use this to build a behavioral baseline before switching to enforce.

isonapse hook mode profile

enforce mode

Gate and block

Actions that violate the active policy are denied before they run. Graduate to this after reviewing the suggested policy with hook suggest --diff.

isonapse hook mode enforce

policy

Policy workflow.

Start in profile mode to accumulate observations, then let the control plane generate a policy from what it saw. Review the diff, apply it, and graduate to enforce mode — or jump straight to a built-in template that matches your workflow.

Learn and enforce

After gathering observations in profile mode, preview the auto-generated policy as a diff against the live policy file, then apply it and switch to enforce in one step.

learn → enforce

1isonapse hook report2isonapse hook suggest --diff3isonapse hook apply

Built-in templates

web-dev

Web development — Node.js, git, docker, npm. Blocks production DB access, rate-limits npm install.

data-science

Data science — Python, Jupyter, SQL. Blocks destructive SQL, restricts network to known hosts.

infra

Infrastructure — kubectl, terraform, aws, docker. Blocks production destructive ops, enforces dry-run.

security-audit

Security audit — restrictive mode. Read-only filesystem, no network, no destructive commands.

hardened

Hardened minimum baseline — blocks writes to Isonapse's own runtime files. Pair with another template for full coverage.

Apply with: isonapse hook policy apply <name>

Inspect and audit

Inspect your behavioral history at any time, check what the gate would decide for a specific command, and verify the witness chain for audit purposes.

inspect

1isonapse hook observations --capability tool:Bash:git2isonapse hook explain "git push --force"3isonapse hook witness stats4isonapse hook witness verify

reference

Command reference.

All subcommands live under isonapse hook. Run any command with --help for the full option list.

Lifecycle

hook serve

Start the control plane server in the foreground (keeps terminal attached).

hook start

Start the control plane server in the background (daemonized).

hook stop

Stop the running control plane server.

hook status

Check whether the control plane is running and print the socket path.

Gate

hook mode

Show the current gate mode (profile or enforce).

hook mode profile

Switch to profile mode — observe and record every action, never block.

hook mode enforce

Switch to enforce mode — deny actions that violate the active policy.

hook report

Show the behavioral profile: tool calls witnessed, PII detections, injection events, top capabilities.

hook observations [--capability <prefix>] [--limit <n>]

List raw observations in the learned gate store. Filter by capability prefix, e.g. tool:Bash:git.

hook explain <command>

Show what the learned gate would decide for an action, e.g. "git rebase -i HEAD~3".

Policy

hook suggest

Generate a policy from observed behavior and print the Lua inspection artifact.

hook suggest --diff

Preview the generated policy as a diff against the live policy file — use before applying.

hook apply

Apply the derived policy and switch to enforce mode in one step.

hook policy list

List built-in policy templates: web-dev, data-science, infra, security-audit, hardened.

hook policy apply <name>

Apply a built-in template. Backs up the existing policy before overwriting.

hook policy import <path|url>

Import a policy from a local file path or HTTPS URL. Validates JSON before writing.

hook policy export <path>

Export the active policy to a destination file.

hook policy show [--summary]

Print the active policy JSON. Pass --summary for a counts-only view.

Cost

hook cost

Show cumulative spend and active budget limits for the current session.

hook cost budget

Set per-session and per-hour USD budget limits written to config.toml.

Witness

hook witness stats

Show witness chain statistics: total receipts, permit/defer/deny counts, oldest and newest entries.

hook witness verify

Verify the cryptographic integrity of the witness chain.

hook witness query

Query recent witness receipts.

hook witness monitor

Live-stream witness entries as they arrive.

Skills

hook skill list

List all skills currently tracked in the manifest.

hook skill check

Report which skill files match their stored hash, which were modified, and which are unknown.

hook skill trust <file>

Trust a specific skill file by recording its current hash in the manifest.

hook skill verify

Rebuild the manifest by rescanning the skills directory, dropping stale entries.

Secrets

hook secret set <name>

Store a secret for {{ secret.NAME }} placeholder injection in prompts and config.

hook secret list

List stored secret names. Values are never shown.

hook secret delete <name>

Remove a stored secret from the local store.

Vault

hook vault stats

Show per-session PII vault stats: row count, cache hit ratio, database path.

hook vault reveal <token>

Reveal the plaintext behind a [PII_<hex>] token.

hook vault gc [--ttl]

Drop vault rows whose last_seen_at is older than the given TTL.

hook vault export

Export every (token, entity_type, plaintext) row in the session vault as JSON.

Intelligence

hook intel download

Download ONNX intelligence models from HuggingFace for local PII and injection detection.

hook intel status

Show model availability and readiness (requires a running control plane).

Config

hook config show

Print the full control plane configuration: socket path, data dir, gate mode, witness settings.

hook config get <key>

Get a single configuration value by key.

hook config set <key> <value>

Set a configuration value in the live config.

Manage

hook disable

Remove the Claude Code plugin while keeping all data and configuration.

hook enable

Re-create the Claude Code plugin from the existing configuration.

hook danger

Destructive operations (reset, purge). Requires explicit confirmation.

hook uninstall

Remove everything: plugin, configuration, and all data.