Experimental: the plugin works and is tested, but may change and gets less hardening than the stable core. The same hooks wired by
tracekit init --dev --v2are stable.
Adds Tracekit's v2 Claude Code hooks through the plugin system, plus /tracekit-status, /tracekit-verify and
/tracekit-pending.
/plugin marketplace add Cygnux-Labs/Tracekit
/plugin install tracekit@tracekit
The plugin only carries the hooks. The signer and the verifier are the tracekit Python package:
pip install tracekit-ai==1.5.3
tracekit init --dev --v2 --no-hooks # same-user dev signer (starts on the first hook); hooks come from the plugin
# or, for tamper resistance against the agent's own user (Linux):
sudo /usr/bin/python3 -m tracekit init --v2 --user <agent-user> --no-hooksWhat is recorded: every tool call (the command, file path or URL in clear, file contents and outputs as hashes), the
policy's decision on it, and your prompts as hashes. In dev mode the signer also keeps each call's redacted arguments
and the result it was sent, encrypted, for 7 days, so tracekit view --dev can show them; TRACEKIT_DEV_CONTENT=0,
set before the dev signer starts, keeps none. Exported bundles hold only the hashes. Everything stays with the local
signer (dev mode: a store under your own user; system mode: the signer's own user); the plugin sends nothing off the
machine. Field by field: privacy.
tracekit init --dev --v2 writes the same hooks into ~/.claude/settings.json. With both, every call is decided
twice, and every call you approve is blocked anyway: one hook uses the approval and the other is refused. So while the
plugin is enabled, tracekit init --dev --v2 installs no hooks and says so, and tracekit doctor counts the
plugin's hooks (D-HOOKS-PRESENT) and warns when both run. In system mode, run init with --no-hooks.
Each hook runs Tracekit's v2 Claude Code hook (tracekit.integrations.claude_code) for its event. The signer
decides: deny blocks the call, and ask blocks it with the approval's id and the command that approves it; once someone
has approved it (in the session with ! tracekit approvals approve <id>, or from another terminal without the !),
Claude's retry of the same call runs.
- A tool call whose hook starts but can't finish is blocked.
- Any other event (a prompt, Stop, a tool's result, a session or subagent event) is never blocked. Its error shows in the transcript as a hook error, and the event isn't recorded. Blocking there would erase your prompt, or send Claude back to work at every Stop.
- System mode (
/etc/tracekit/client.jsonexists): the hook runs only the root-owned runtime,/opt/tracekit/bin/python;TRACEKIT_PYTHON,PATHand user site-packages are ignored. If that runtime can't run the hook, tool calls are blocked (withfail_mode: openin that file they run, unrecorded, with an error shown). Re-run system init from a root-owned clone:sudo /usr/bin/python3 -m tracekit init --v2 --user <agent-user> --no-hooks. - Dev mode: the hook runs in the first of
TRACEKIT_PYTHON,python3andpythonthat has thetracekitpackage, user site-packages included. A tracekit older than 1.2, or one whose hook won't import, blocks tool calls and says how to upgrade. With no tracekit at all, tool calls are blocked once Tracekit is set up for your user: the dev signer's data directory exists (tracekit init --dev --v2creates it), orTRACEKIT_PYTHONorTRACEKIT_SIGNERis set. Before that, every event shows a notice and runs, unrecorded.
The hooks tracekit init --dev --v2 writes treat events the same way, but run the interpreter init ran with
(python -I -m tracekit.integrations.claude_code <event>) instead of searching for one.
Plugin versions before 1.3 ran the v1 hook against tracekitd. This one runs the v2 hook, and updating the plugin
switches you over:
- v1 dev mode (
tracekit init --dev --no-hooks): the next hook starts the v2 dev signer. Your v1 policy no longer applies (the v2 coding pack does),tracekit pendingandtracekit approveno longer see held calls (usetracekit approvals), and once the v2 signer has recorded something, the v1 ledger can't be bridged into it. - v1 system mode (
tracekit init --no-hooksas root): every tool call is blocked until v2 system mode is set up. The hook's error says so.
Before the next Claude Code session after the update:
tracekit export --last -o last-v1-run.tkb # each v1 run you need (--run ID)
tracekit uninstall # stops tracekitd
tracekit signer bridge --v1-home ~/.tracekit-signer --dev # only before the v2 signer records anything
tracekit init --dev --v2 --no-hooks
# system mode instead: sudo /usr/bin/python3 -m tracekit init --v2 --user <agent-user> --no-hooksIf the v2 signer has already recorded something, the bridge refuses and the two logs stay separate; both keep verifying. Details: migrating.
The hook script is POSIX shell: macOS, Linux and WSL. On native Windows, Claude Code runs it in Git Bash when Git for
Windows is installed (untested). Without Git Bash it runs it in PowerShell, which can't, so Claude Code blocks every
tool call: there, don't install the plugin, and use tracekit init --dev --v2.
See the main README for what Tracekit proves and what it does not.