Hooks & Setup

Hooks are how Metateam integrates with hook-enabled clients so sessions can be captured at end and the crew agent can be re-registered after /clear. In current docs, hooks are for Claude Code and Gemini CLI. Codex uses the same monitor/start flow that all clients use to load context (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: Signal client readiness for summon, re-register the crew agent after /clear, and emit a session_start log event. The hook does not inject context; agents load context themselves by running metateam start (every persona's startup sequence already calls it).
  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 at end. (Context loading is unaffected — it has always been driven by metateam start, not the hook.)

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. Signals client readiness via METATEAM_CREW_READY_FILE (used by summon to detect when the agent is up)
  4. Re-registers the crew agent if the persona/crew env is set (handles /clear, which fires SessionEnd → SessionStart without a fresh summon)
  5. Emits a session_start log event for observability

Context loading is not the hook's job. Each persona's startup sequence calls metateam start [--as <station:crew:persona>], which produces the formatted context block the agent should include in its prompt. See metateam start for details.

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)
  • Heavier git context is gathered on-demand by metateam start, not at SessionEnd

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.