Hooks & Setup

Hooks are how Metateam integrates with hook-enabled clients for readiness and crew-agent re-registration after client-side resets. In current docs, hooks are for Claude Code and Antigravity CLI. Transcript capture for crew sessions is communicator-driven, and all managed summons receive startup context through START.md prepared before launch.

Check Hook Status

$ metateam hook status

Enable Hooks

$ metateam hook enable

Installs and enables hook integration for Claude Code and Antigravity CLI. After this, agent sessions will:

  1. On SessionStart: Re-register the crew agent after /clear and emit a session_start log event. Claude also uses this event for launch readiness. agy creates its conversation on the first prompt, so Metateam supplies that prompt with -i and does not wait for this hook before delivery. The hook does not inject context.
  2. On SessionEnd: Nothing active in current builds. Upload is communicator-driven; stale installed SessionEnd hooks are kept harmless by a no-op compatibility shim.

Disable Hooks

$ metateam hook disable

Removes hook integration. SessionStart readiness/re-register behavior stops for hook-enabled clients. Transcript upload is communicator-driven in current builds, and context loading is unaffected because it is driven by summon-time START.md generation or manual 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

Claude Code sends:

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

Antigravity (agy) uses ~/.gemini/config/hooks.json. Metateam owns only the top-level metateam hook set and installs flat SessionStart and PreInvocation command arrays. Other hook sets are preserved. PreInvocation updates the model for the exact admitted conversation. It does not re-register the agent or replace transcript counters. agy sends conversationId, workspacePaths, transcriptPath, and modelName. The workspace path is used because the hook process runs from the hooks directory. The hook returns {} to agy. agy has no SessionEnd or UserPromptSubmit event.

Resuming an existing agy conversation with --conversation does not fire SessionStart. Managed resume registers the saved source before launch, and PreInvocation still updates the model on the next prompt. The installer uses global hooks, which do not depend on workspace-local hook trust.

The hook:

  1. Checks for .nometateam markers (opt-out)
  2. Skips blocked paths (node_modules, .git, vendor, etc.)
  3. Writes METATEAM_CREW_READY_FILE when supplied. agy launch does not wait for this file before the first prompt.
  4. Re-registers the crew agent if the persona/crew env is set (handles client-side resets that start a fresh session without a fresh summon)
  5. Emits a session_start log event for observability

Context loading is not the hook's job. Managed summon calls the context loader before launch and writes START.md beside the generated instruction file; the persona reads that file. See metateam start for the equivalent manual/debug command.

How Session Upload Works

Current builds treat the SessionEnd internal command as a no-op compatibility shim for stale installed configs. Crew transcript upload is driven by the communicator/session tailer. Explicit catch-up is available through metateam session upload.

Uploaded session context is intentionally minimal compared with startup context:

  • Session body (markdown)
  • Minimal context (working directory, agent type, KB context if pinned)
  • Heavier git context is gathered on-demand by summon-time START.md generation or manual metateam start, not at upload time

Duplicate uploads (e.g., from forked sessions) are prevented by the upload path's locking and session identity logic.

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.