Claude Code quickstart

From install to enforcement in four steps

Install the Agent Hook, initialise its local state, work in Profile while it learns, then switch to Enforce when the suggested policy looks right.

Step 1
Install
Install the public formula.
brew install isonapse/tap/isonapse
Step 2
Initialise and start
Create local state and start the decision process.
isonapse hook init && isonapse hook start
Step 3
Run in Profile
Work normally, then review what Isonapse observed.
isonapse hook report
Step 4
Switch to Enforce
Generate the proposed policy and stop to review it.
isonapse hook suggest --diff
Review the complete no-new-choice baseline diff before continuing.
isonapse hook apply

Download before you begin: initialisation automatically fetches about 91 MB for the required local embedding model. The separate, user-started isonapse hook intel download command fetches about 1.9 GB of additional on-device detection models; from an empty model directory the maximum is about 2.0 GB.

Before you start

macOS 11 Big Sur or later (Apple silicon) or Linux x86_64 with glibc 2.35+ — full system requirements below
Homebrew for the recommended formula path; it is not required for the standalone verified installer
Claude Code with an active Claude account — the agent the hook governs today
The beta license covers personal testing, research, and internal, non-production evaluation — the plain-language summary is on the beta terms page
No GitHub token or Isonapse account for the public main channel

1 · Install

brew install isonapse/tap/isonapse

Public main is the primary channel and needs no GitHub token. You can alternatively run the verified public installer:

curl -fsSL https://github.com/Isonapse/isonapse-public/releases/latest/download/install.sh | sh

The script installs under ~/.isonapse/bin and does not edit your shell profile. Before step 2, add it to this shell's path (and put the same export in your shell profile for future sessions):

export PATH="$HOME/.isonapse/bin:$PATH"

Release channels and package verification

The isonapse formula pins immutable releases and updates through Homebrew like everything else you run. Its archive digest comes from the same checksummed build identity used by the installer and updater, binding the exact source commit, channel, version, and platform rather than a publication repository's branch name. Release CI audits, clean-installs, and tests that exact formula on native macOS Apple Silicon and Linuxbrew x86_64 before the required tap publication can advance. This step installs the three command-line binaries, license, and attribution texts — nothing starts running until you initialise.

Private beta and alpha remain secondary rings for invited testers and Isonapse engineers. They use isonapse-beta or isonapse-alpha plus the GitHub personal access token supplied in the invitation:

export HOMEBREW_GITHUB_API_TOKEN="YOUR_PRIVATE_BETA_TOKEN"
brew install isonapse/tap/isonapse-beta

Replace YOUR_PRIVATE_BETA_TOKEN with the token from your invitation, use it only in the shell where you install the private ring, and unset it when the install finishes.

Every installed build has one exact identity: 0.2.0-beta+<channel>.<short_sha>. The CLI, generated Claude Code plugin, GitHub Release title, and Homebrew formula all report the same value.

2 · Initialise — once

isonapse hook init

Initialisation creates Isonapse's local state, installs the Claude Code hook, and automatically downloads the required about 91 MB model. Then start the small local decision process and confirm its status.

What initialisation creates and changes

This creates ~/.isonapse/, generates your machine's signing key, fingerprints the configured personal-skill root and resolved installed-plugin prompt content plus any package routing manifests, writes a starter policy, registers Isonapse as a Claude Code plugin, and automatically downloads the required 90.9 MB (86.7 MiB) embedding model from Hugging Face that the control plane needs to run. By default that means ~/.claude/skills and installed prompt components under ~/.claude/plugins, not project, managed, legacy-command, or additional-directory skills outside those configured roots. Package and marketplace metadata can select default/custom skill and command paths or, for a single-skill package with no other skill component, a root SKILL.md. Configured roots are authoritative: repointing skills_dir leaves the generated ~/.claude/skills/isonapse-hook transport outside the trust manifest. The generated plugin manifest contains hooks only; the hook itself provides a narrow, always-on best-effort guard for direct Edit/Write and rm/chmod attempts against Isonapse data and its active plugin. Managed setup additionally places current Claude Code deny rules in OS managed settings and enables allowManagedHooksOnly. This is defense in depth, not an OS sandbox. Initialisation installs the pieces but does not start the control plane. Start that small local decision process explicitly in the background:

Already installed an earlier beta? After upgrading, rerun the same setup form you use now — isonapse hook init or isonapse hook init --managed — to replace stale generated plugin or managed-host configuration. Your Isonapse state and trust decisions are preserved. Then start a fresh Claude Code session so the host reloads the generated 55-second handlers; a session that was already open can retain its old timeout.

isonapse hook start

isonapse hook status

Start, stop, and daemon-unavailable behaviour

The status command should report the control plane running and the Claude Code plugin installed. If you skip the explicit start, the next Claude Code session can start the control plane on demand. isonapse hook stop stops it and disables that automatic restart until you run isonapse hook start again. From your next session on, covered actions flow through the checkpoint. If the daemon is unavailable, an ordinary PreToolUse action asks before running; a direct self-protection match is denied locally first. Neither daemon-down result has a witness receipt.

Optional, skippable local intelligence: this is not part of the required first-run sequence. The user-started command downloads about 1.9 GB of additional on-device detection models, or at most about 2.0 GB from an empty model directory.

isonapse hook intel download

Exact model downloads, fallbacks, and explain behaviour

This user-started command fetches the extra on-device ML models for personal-data and prompt-injection detection, PII NER, and the NLI cross-encoder — a one-time additional download of 1.877 GB (1.748 GiB) after required provisioning succeeds. If the required embedding model is missing, this command repairs that too, so its maximum all-model transfer is 1.968 GB (1.833 GiB). Files go into ~/.isonapse/. It runs entirely locally and is skippable: when its local session can load, the required embedding powers the learned similarity gate; PII and injection retain local fallbacks, while optional NLI entailment is unavailable.

To inspect a point-in-time candidate without running or authorizing a command, use isonapse hook explain "ls -la". It evaluates the exact hypothetical input in a fresh isolated synthetic session without changing gate state or attempting a receipt. If the captured live path would invoke stateful Lua policy or require a cache-mutating intelligence-model load, the result is indeterminate; live authorization can still differ as state changes or fail closed while storing its receipt.

3 · Run in Profile — it learns

A fresh install starts in Profile mode: ordinary behavioral actions are allowed after their authorization is recorded, with static or draft advice shown when applicable. Fixed structural and resource limits plus the narrow self-protection guard can still block even now. Don't linger here — a day or two of normal work is plenty before you promote. Check in on what it's learning:

isonapse hook report      # last-24h summary
isonapse hook suggest     # the rules it would write
isonapse hook explain "ls -la"    # inspect an uncommitted candidate

Profile's exact data-protection boundary

Profile is an observe-and-learn on-ramp, not a general data-masking mode: raw Bash input is PII-scanned for typed audit evidence but the PII action does not block, mask, or rewrite it; selected successful tool output is scanned for warnings but not rewritten by the PII action, and secret placeholders are not resolved. If a local vault token was restored, exact private-release replacement still applies to a supported PostToolUse data carrier under a trusted hook set; an unsupported carrier stops, and a matching failure error can only stop immediate continuation, not erase the host record. Submitted prompts also cannot be rewritten; only deny_on_ingress can block them.

4 · Switch to Enforce

When the picture looks right, review the exact point-in-time baseline policy it would write if the profile and live policy stay unchanged and you make no new catastrophic PERMIT/DEFER choices, then flip the switch:

1 · Generate the proposal

isonapse hook suggest --diff

Stop here and review the complete no-new-choice baseline diff. Apply only when every proposed rule reflects the access you intend to grant across this machine. Re-run suggest if the profile or live policy changes before apply. Any new catastrophic PERMIT/DEFER choice you make during apply changes those bytes.

2 · Apply after review

isonapse hook apply

From now on your rules plus the learned baseline decide. Changed your mind? isonapse hook mode profile switches back to watching at any time. Prefer the non-Profile policy and filter pipeline without learned lookup? isonapse hook mode normal runs that pipeline without Enforce's learned lookup — similarity to past approved work never changes a decision; the remaining policy and filter layers may permit, ask, or deny from their own evidence. Watch decisions stream live with isonapse hook witness monitor.

Enforce's exact data-protection boundary

Outside Profile (in Normal and Enforce), the configured PII action can tokenise, hold for review, or block selected tool output before model delivery. For raw Bash it can mask, ask, or block; any permitted masking composes with allowed-secret resolution, local-trust detokenisation, and safe dry-run injection before the exact effective command is authorized once. External WebFetch and MCP arguments keep existing vault tokens opaque, but raw plaintext arguments are not generically scanned. The full surface-by-surface matrix is on the What it does page.

Technical reference

The quickstart above is enough for a first run. Expand these sections when you need exact platform, lifecycle, or package behaviour.

Data location, pausing, and uninstalling

Everything is local: your rules, the signed decision history, and what the system has learned live under ~/.isonapse/. There is no cloud service, no account, and no telemetry.

In plugin mode, pause without losing Isonapse data: isonapse hook disable removes the generated Claude Code plugin and enable creates it again only when the plugin path is absent and refuses to replace an occupied path. These commands do not pause a managed install: its OS managed policy remains active. To remove the installation: isonapse hook uninstall --yes first freezes each install-owned local target's filesystem identity and authenticates any custom socket against the daemon health PID and trusted installation PID file. It then proves that any active OS managed policy exactly matches a current or published Isonapse-generated schema and removes it with administrator approval. Unrelated organization policy is preserved; duplicate, malformed, ambiguous, detected path/identity replacement, or unexpected local state requires manual resolution. It then publishes a checked stop sentinel, stops the control plane, waits for its exact process to exit, revalidates the frozen targets, and deletes the plugin and bootstrap-owned data. Valid macOS sockets at the platform path-length limit remain removable, and deleting the owned data tree may intentionally remove the stopped socket's parent. A configured data_dir that resolves outside the bootstrap installation is refused before managed-policy mutation. External witness, policy, vault, or other file overrides are preserved for deliberate manual cleanup rather than inferred to be install-owned. If policy removal, ownership, shutdown, or target identity fails, the remaining cleanup does not run and the command does not claim completion. Timestamped managed-policy backups remain for manual administrator or MDM restoration; uninstall does not choose and restore one automatically. This is not a filesystem transaction or OS sandbox against a hostile process already running as the same account (or root) and deliberately targeting lifecycle or private quarantine entries between syscalls; stop that process before retrying or resolve the retained state manually. (Run it without --yes first to preview what it will remove.) Then brew uninstall isonapse removes the binaries.

System requirements

macOS 11 Big Sur or later — Apple Silicon native; Intel macOS is not supported in Wave 1. Rosetta translates Intel applications on Apple Silicon, not ARM applications on Intel Macs.
Linux x86_64 with glibc 2.35 or newer — e.g. Ubuntu 22.04+ or Debian 12+. RHEL/Rocky/Alma 9 and Amazon Linux 2023 remain too old at glibc 2.34; older releases and musl distros are also unsupported. The binary won't start there, and the installer stops before downloading rather than leave you with one that can't run. There is no Linux ARM build yet.
Model namespace monitoring: every verified-file open requires macOS kqueue or Linux inotify. Linux arms its watcher through /proc/self/fd. If the required embedding cannot arm that watcher during startup validation, the daemon refuses to start; restore the facility and start it again.
Linux lazy model sessions: after required validation succeeds, session construction additionally requires memfd_create with file sealing and /proc/self/fd. If only that later construction is blocked, the daemon stays up, but PII/injection use regex/structural fallbacks, NLI is unavailable, and an Enforce learned check without an explicit policy permit asks for confirmation. Restart the daemon after enabling the primitives.
Windows native is out of beta scope. No Windows build is tested or released in Wave 1.
Homebrew (the brew path) or curl (the script path), plus Claude Code and an active Claude account.
An internet connection at setup — the required embedding model is fetched from Hugging Face during isonapse hook init. After that, enforcement runs fully offline.
Disk: the four model downloads alone are 1.968 GB (1.833 GiB): 90.9 MB required at setup plus 1.877 GB optional. Reserve at least 2.1 GB for a full-model install, plus additional room for binaries and locally growing receipts, logs, and learned state.
Linux model first-use memory: the temporary sealed snapshot can equal one complete model footprint — up to 837.1 MB (798.3 MiB) for PII — in addition to ONNX Runtime session memory. The snapshot is released after session construction, and only one cold model is admitted at a time; another caller does not queue.
No Docker required for the Agent Hook.

What gets installed

Three binaries in Homebrew's managed prefix (for the Brew install) or ~/.isonapse/bin/ (for the script install): isonapse (the CLI), isonapse-hook (the thin per-event client Claude Code spawns), and isonapse-controlplane (the local decision engine that runs as a daemon). isonapse hook init validates and records the hook beside the invoked CLI, so Homebrew upgrades keep the pair together. The curl script also drops in isonapse-update for in-place upgrades.
The license and attribution files next to them — LICENSE.md, THIRD_PARTY_NOTICES.md, and THIRD_PARTY_DEPENDENCIES.md.
Script-install archives are a closed, preflighted cohort. Before changing any installed file, the installer verifies the outer SHA-256 plus a versioned manifest that binds the three binaries, updater, EULA, both notice files, and archive README to their exact modes, platform target, byte sizes, and SHA-256 digests. Missing, undeclared, linked, non-executable, wrong-target, or tampered members reject the whole archive and leave the existing install unchanged. The generated archive guide names the exact alpha/beta/main channel, immutable tag, full source commit, authoritative distribution repository, access requirement, and matching install/update commands; private alpha and beta guides never redirect an operator to main. The installer then preflights a complete sibling directory—including its checksummed build identity—under a shared per-install advisory lock and switches it as one cohort with the channel configuration. A pre-commit failure restores every prior byte; after a killed process, the next run resolves the retained identity-bound journal before contacting GitHub. Lock ownership also remains held by a foreground child that outlives a killed installer shell. Every installer/updater request also shares a bounded transport policy: ten seconds to connect, no more than five redirects, transient 408/429/5xx retries, and a 300-second maximum per operation including retries. After resolving any retained recovery journal, exhaustion prepares or commits no new cohort change and reports the channel/tag without exposing credentials. If metadata for the installed immutable release is missing or inaccessible, an ordinary update stops before installation because release order is unknown; only an explicit --force waives that conflict. Authentication, transport, and transient-service failures remain non-overridable.
Your ~/.isonapse/ state directory, a machine signing key, and a starter policy — and Isonapse registered as a Claude Code plugin. Its hooks-only manifest invokes the local guard and controlplane client; managed mode instead adds host permission rules and locks hook loading with allowManagedHooksOnly.
At isonapse hook init: the 90.9 MB embedding model the control plane needs to start. Optionally, 1.877 GB (1.748 GiB) of on-device PII, prompt-injection, and NLI cross-encoder models via isonapse hook intel download — skippable; the required embedding-backed learned gate still enforces without them. That command also repairs the required model if it is missing, making 1.968 GB the maximum transfer from an empty model directory.

License & attribution

Isonapse is governed by the Isonapse Agent Hook Public Beta EULA — the plain-language summary is on the beta terms page. Third-party notices for the bundled models and the open-source dependencies ship with every install (next to the binaries) and are available anytime with isonapse licenses.

Common questions

Does it slow my agent down?

Ordinary RPCs have a 5-second budget. Only methods that can build a model session receive up to 45 seconds; daemon-start and all RPC work share one 50-second Hook deadline ahead of Claude Code's generated 55-second handler timeout. These are fail-closed bounds, not a promise that a cold load finishes within 45 seconds. One cold model is admitted at a time, and another caller uses the local no-model fallback instead of waiting in a queue.

Does my code or data leave my machine?

No user content or telemetry is uploaded by Isonapse: that includes code, prompts, decision history, and personal data. Model provisioning makes the required setup GET and the optional user-started GETs to Hugging Face. Separately, an opt-in hook start update check reads GitHub release metadata only; notify_on_update defaults off, and the check sends no user content. Your agents may make their own policy-governed network calls.

What does the optional model download fetch?

The extra on-device ML models for smarter detection — recognising personal data and injected instructions. (The small embedding model that compares actions to what you've approved before is fetched automatically at hook init.) It's a one-time 1.877 GB (1.748 GiB) download covering PII NER, prompt-injection detection, and the NLI cross-encoder. The models run entirely locally; skip them and the required embedding-backed learned gate still enforces, while the PII/injection detectors use local fallbacks and NLI entailment is unavailable.

Is this per project, or for the whole machine?

The whole machine: the rules you promote and everything the gate learns apply to all your work here, whichever repository you're in. Per-repository rules that travel with the repo arrive with the Community Edition release — see the roadmap.

What happens to my existing Claude Code setup?

Plugin mode registers Isonapse alongside your existing configuration. isonapse hook init --managed writes the active OS managed policy and first backs up any policy already at that path. A full uninstall removes the active Isonapse policy before local cleanup, but it leaves those backups for deliberate administrator or MDM restoration rather than guessing which prior policy to restore.

What it does Something broke? Tell us