Monitor & Start

All three supported clients (Claude Code, Gemini CLI, Codex CLI) support hooks for automatic session capture. The monitor and start commands serve as supplementary tools: the monitor provides background session detection, and start allows manual context injection when hooks are unavailable.

Monitor

$ recalletta monitor [AGENTS]

Runs a background process that watches for AI agent sessions and uploads their transcripts when they finish.

Argument Default Purpose
codex yes Monitor Codex sessions
gemini Monitor Gemini sessions
claude Monitor Claude sessions (usually handled by hooks instead)

Examples:

$ recalletta monitor                # Monitor Codex (default)
$ recalletta monitor codex gemini   # Monitor both Codex and Gemini

How It Works

The monitor:

  1. Polls for running agent processes at regular intervals
  2. When an agent process is detected, opens a time window
  3. When the process exits, scans the agent's transcript directory for files modified during that window
  4. Uploads any new transcripts in the background

This is best-effort. It depends on:

  • Being able to detect the agent process (process name/PID matching)
  • Finding transcript files in the expected location
  • The transcript being complete when the process exits

For Codex, the monitor starts automatically when hooks are installed via recalletta init -- no manual action is needed. For reliable session capture with all clients, ensure hooks are installed via recalletta init.

Start

$ recalletta start [PROMPT]

Manually triggers context injection for sessions where hooks are not available. Outputs the same context that SessionStart hooks produce. This is rarely needed -- hooks handle context injection automatically for all supported clients.

An agent (or user in rare cases) can invoke this to retrieve relevant past sessions and KB entries as injectable context.

Example workflow:

$ recalletta start "fix the auth module" > context.txt

If no prompt is provided, it uses an empty string and returns context based on the working directory and git metadata alone.