Claude Code Installation

Overview

Caret integrates with Claude Code via its native hooks system. Three hooks are installed: UserPromptSubmit, PreToolUse, and PostToolUse. No SDK, no code changes, no Claude Code extensions required.

Prerequisites

• Claude Code CLI installed and working
• Node.js 18+
• An Caret account (caret login)

Installation

# Initialize Caret in your project
npx caret init

# Install hooks for Claude Code
caret supervisor install --agent claude-code

# Start the daemon
caret daemon start

The installer writes hook entries to ~/.claude/hooks.json (global) or .claude/hooks.json (project-level). Each hook points to the Caret daemon's local HTTP endpoint.

How hooks work

Claude Code's hook system calls external processes at three lifecycle points:

• UserPromptSubmit: Fired when you press Enter on a prompt. Caret captures the prompt text, parses it into a structured intent, and begins a new supervision session.
• PreToolUse: Fired before the agent executes a tool call (file read, file edit, bash command). Caret evaluates whether this action aligns with your intent and can optionally block it.
• PostToolUse: Fired after a tool call completes. Caret records the result, updates the session health score, and checks for drift patterns like retry loops.

Hook handlers complete in under 200ms including cold start. Claude Code will not notice the overhead. If the handler fails or times out, Claude Code continues normally — Caret is fail-open by design.

Verify installation

$ caret supervisor status

✓ Supervisor active
  Agent:    claude-code
  Hooks:    UserPromptSubmit, PreToolUse, PostToolUse
  Daemon:   running (pid 48291)
  Config:   caret.config.json (6 detectors enabled)

Global vs project installation

By default, caret supervisor install installs hooks for the current project only. Use --global to install for all projects:

# Project-level (default) — hooks in .claude/hooks.json
caret supervisor install --agent claude-code

# Global — hooks in ~/.claude/hooks.json
caret supervisor install --agent claude-code --global

Project-level hooks take precedence over global hooks. We recommend starting with project-level installation to test, then switching to global once you're comfortable.

Uninstalling

caret supervisor uninstall --agent claude-code

This removes Caret's hook entries from the hooks.json file. Your Claude Code configuration is otherwise untouched.

Troubleshooting

• "Daemon not running" — Run caret daemon start. The daemon must be running for hooks to work.
• "Hooks not firing" — Ensure your Claude Code version supports hooks (v1.0+). Run claude --version to check.
• "Permission denied" — The hook handler needs execute permission. Run caret supervisor install --force to reinstall.
• "Slow hook response" — The daemon cold-starts in under 200ms. If you see delays, check caret daemon status for errors.