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 Gemini 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 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; managed summons prepare START.md before the client launches.
  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

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 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.