Hooks & Setup

Hooks are how Metateam integrates with hook-enabled clients so sessions can be captured and context can be injected automatically. In current docs, hooks are for Claude Code and Gemini CLI. Codex uses monitor/start flows (metateam monitor, metateam start).

Check Hook Status

$ metateam hook status

Enable Hooks

$ metateam hook enable

Installs and enables hook integration for Claude Code and Gemini CLI. After this, agent sessions 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

$ metateam hook disable

Removes hook integration. Sessions will no longer be automatically captured or receive context injection.

First-Time Setup

$ metateam setup [--username USERNAME] [--password PASSWORD]

Runs first-time setup (including login/config) in one step. See Account for details on account register, account login, and related account commands.

How SessionStart Works

When a hooked client (Claude Code or Gemini CLI) 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 .nometateam 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 .metateam.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 metateam session show <session_id>.

How SessionEnd Works

When a hooked 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 .nometateam file in any directory to disable hooks for that directory and all subdirectories:

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

A .yesmetateam file in a subdirectory overrides a parent .nometateam.

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