Hooks & Setup

Hooks are how Recalletta integrates with AI coding agents (Claude Code, Gemini CLI, Codex CLI) so sessions can be captured and context can be injected automatically.

Check Hook Status

$ recalletta hook status
Hook status:
  Enabled: yes
  Claude: installed
  Gemini: installed
  Codex:  installed

Enable Hooks

$ recalletta hook enable

Installs hooks for all detected AI clients (Claude Code, Gemini CLI, Codex CLI). After this, every agent session will:

  1. On SessionStart: Collect the working directory, git metadata, and (optionally) the first prompt. Call the API for relevant context. Inject it into the agent's context.
  2. On SessionEnd: Read the session transcript, convert it to markdown, and upload it in the background.

Disable Hooks

$ recalletta hook disable

Removes hooks from all detected AI clients. Sessions will no longer be automatically captured or receive context injection.

First-Time Setup

$ recalletta init [USERNAME] [PASSWORD]

Logs in, saves the API key, and installs integrations for all detected clients (Claude Code, Gemini CLI, Codex CLI) in one step. See Account for details on init, register, and login.

How SessionStart Works

When an AI client starts a session, the hook receives:

  • session_id — unique session identifier
  • cwd — the current working directory
  • prompt — the first message (optional, may be absent)

The hook:

  1. Checks for .norecalletta markers (opt-out)
  2. Skips blocked paths (node_modules, .git, vendor, etc.)
  3. Collects git context (branch, status, remotes, recent commits)
  4. Detects project via .recalletta.json pin file
  5. Queries the API for relevant context
  6. Injects the response into the agent's context

The API returns a formatted context containing:

  • Summaries of relevant past sessions
  • Recent sessions from the same machine/directory
  • Important KB entries for the detected project

This is not full session transcripts -- it is summaries and curated knowledge. The agent can load full transcripts on demand with recalletta <session_id>.

How SessionEnd Works

When an AI client session ends:

  1. The hook reads the session transcript
  2. Converts it to markdown
  3. If the transcript exceeds 10 MB, applies compaction
  4. Spawns a detached background process to upload
  5. The client exits immediately -- no waiting

The upload includes:

  • Session body (markdown)
  • Minimal context (working directory, agent type, KB context if pinned)
  • The heavier git context was already captured at SessionStart

Duplicate uploads (e.g., from forked sessions) are prevented via atomic file locking.

Opting Out

Place a .norecalletta file in any directory to disable hooks for that directory and all subdirectories:

$ touch /path/to/sensitive-project/.norecalletta

A .yesrecalletta file in a subdirectory overrides a parent .norecalletta.

The following paths are always skipped: node_modules, .git, vendor, and other common dependency directories.