How ainb-hooks, ainb-notifyd, and the Inbox screen work in agents-in-a-box

Architecture in one picture

Two host agents fire hooks at distinct lifecycle moments. The same script absorbs both shapes, hands off to a daemon that owns the SQLite file, and the TUI polls that SQLite for live display. Every box below is a real file on disk; arrows are the actual transport.

The seven components

Every box in the diagram is a real artifact in the repo. Each card below is one file (or one tight module) and what it owns.

The event path, step by step

From hook fire to a visible row in the TUI — five steps, end to end in single-digit milliseconds when the daemon is up. Each step's file:line citation is on the right.

Wire format & install

One envelope shape, three install surfaces. The placeholders below are exactly what's on the wire and on disk after a clean ainb-notifyd install --all.

// one JSON line per envelope on the socket / in fallback.jsonl
{
  "protocol_version": 1,
  "agent":            "claude",        // or "codex"
  "raw_event":        "Notification:idle_prompt",
  "session_id":       "7f2a-...",
  "cwd":              "/Users/stevie/d/git/ai-coder-rules",
  "project":          "ai-coder-rules",  // basename(cwd)
  "ts":               1717000000000,
  "payload":          { /* verbatim original hook JSON */ }
}

// ~/.claude/plugins/ainb-hooks/.claude-plugin/plugin.json
{
  "name":    "ainb-hooks",
  "version": "0.1.0",
  "hooks": {
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type":    "command",
        "command": "AINB_AGENT=claude ${CLAUDE_PLUGIN_ROOT}/hooks/notify.sh",
        "timeout": 5
      }]
    }]
    // + SessionStart, UserPromptSubmit, PostToolUse,
    //   Notification, PreCompact — same shape
  }
}

// ~/.codex/hooks.json — managed block merged in-place
{
  "hooks": {
    "Stop": [
      { /* user's pre-existing hook — untouched */ },
      {
        "_ainb_managed": true,        // uninstall strips only these
        "matcher": "",
        "hooks": [{
          "type":    "command",
          "command": "AINB_AGENT=codex /Users/stevie/.agents-in-a-box/hooks/notify.sh",
          "timeout": 5
        }]
      }
    ]
  }
}

// ~/.agents-in-a-box/install.json — written by install verb
{
  "agents": ["claude", "codex"],
  "hook_script":       "/Users/stevie/.agents-in-a-box/hooks/notify.sh",
  "claude_plugin_dir": "/Users/stevie/.claude/plugins/ainb-hooks",
  "codex_hooks_json":  "/Users/stevie/.codex/hooks.json"
}

cwd-based correlation — bridging two ID spaces

ainb internally identifies a session by a Uuid it generates when spawning a worktree. The host agents' hooks emit their own session_id strings — Claude's session ID, Codex's session ID — which sit in a different namespace. There's no shared key.

The workaround is cwd: every envelope already carries the agent's working directory at hook-fire time, and every ainb Session already carries a workspace_path (the repo root). Match the two and the bridge is done:

Lifecycle, retention & gotchas

• Lazy daemon spawn. Hook scripts don't require the daemon to be running — if the socket is missing, the envelope is appended to notify.fallback.jsonl, and the next daemon startup ingests + clears the file. Zero loss on cold systems.
• PID file + SIGTERM. The daemon writes ~/.agents-in-a-box/notify.pid at startup. ainb-notifyd stop sends SIGTERM; the listener drops the socket file + PID file before exiting. A stale PID is cleaned up on the next startup via kill(pid, 0) liveness check.
• Retention on every insert. Defaults: 7 days, 10 000 rows. Tuned in ~/.agents-in-a-box/config.toml [notifyd]. The sweep runs in the same SQLite transaction as the insert.
• OS-notify debounce. Per-(session_id, raw_event), 60-second window. Telemetry events (SessionStart, UserPromptSubmit, PostToolUse) never fire native notifications even if the debounce would allow them — they're stored for the inbox but never disturb you.
• Hook script always exits 0. A delivery failure must never block the host agent. If the socket is broken AND the fallback write fails, the envelope is dropped — deliberately, because the alternative is freezing claude/codex.
• Reversible install. install.json records the exact paths used. uninstall reads it back and removes the Claude plugin dir + strips _ainb_managed entries from Codex's hooks.json while leaving user-authored hooks intact.

How it was validated

Five test layers in order of cost-to-confidence. CI runs the bottom three on every push across macOS + Linux.

// crates/ainb-plugin-notifyd/src/{envelope,store,fallback,pid,osnotify}.rs
// crates/ainb-core/src/components/{inbox,sidebar}.rs
$ cargo test -p ainb-plugin-notifyd --lib
test result: ok. 44 passed; 0 failed
$ cargo test -p ainb --lib components::{inbox,sidebar}
test result: ok. 15 passed; 0 failed

// crates/ainb-plugin-notifyd/tests/end_to_end.rs
// real bash → real socket → real notifyd → real SQLite
$ cargo test -p ainb-plugin-notifyd --test end_to_end
hook_script_into_real_daemon_persists_both_agents .. ok
hook_falls_back_when_daemon_down_then_daemon_replays .. ok

// crates/ainb-core/tests/tripwire_inbox_opens_and_renders.rs
// real ainb binary in a tmux pane · capture-pane assertions
$ cargo test -p ainb --test tripwire_inbox_opens_and_renders
inbox_opens_and_renders_seeded_notifications .. ok
  ✓ HomeScreen sidebar shows 📥 Inbox [I]    (discoverability)
  ✓ Shift+I opens 📥 Inbox screen
  ✓ Both seeded events render with detail pane
  ✓ Help bar visible

# Driven by hand against an isolated $HOME via tmux capture
$ HOME=/tmp/ainb-test ./target/debug/ainb tui
→ HomeScreen sidebar shows 📥 Inbox tile between Sessions and Recovery
→ Shift+I opens Inbox with both seeded events
→ Detail pane shows event, agent, session, cwd, payload JSON
→ Menu-bar shows "I inbox" hint always; "● N · I inbox" when unread

# THE one unproven seam — requires real Claude or Codex CLI session
$ scripts/live-validate-ainb-hooks.sh --real-session
==> install + daemon + pause for real session ...
# requires Stevie's machine: a real claude/codex CLI process
# firing its own hook with its real payload shape
==> rows that landed:
   agent  raw_event                 session_id  project
   ?????  ???????????               ??????????  ???????

FAQ

Where is the SQLite file? Can I poke around with sqlite3?

~/.agents-in-a-box/notifications.db. Yes — WAL means the daemon can keep writing while you read. sqlite3 -header -column ~/.agents-in-a-box/notifications.db "SELECT agent, raw_event, session_id, project FROM notifications ORDER BY ts DESC LIMIT 20".

Why Shift+I for the Inbox? Why not n?

n already opens NewSession; lowercase i already opens Stats. Shift+I was the next free letter that still mnemonically ties to "inbox". The home-screen sidebar tile and the menu-bar hint both advertise it as [I]. On Linux tmux Shift+i may arrive as KeyCode::Char('i') + SHIFT rather than Char('I'); the handler accepts both forms (PR #165).

Why not just identify sessions by session_id?

The host agent's session_id and ainb's Session.id live in different namespaces — Claude generates its own UUID, Codex generates its own, ainb generates its own. There is no shared key. The cheapest correlation that already exists at both ends is the working directory: every envelope has cwd, every ainb session has workspace_path. Exact match or prefix-with-trailing-slash for worktree subdirs.

What happens if I install once, run, then install again?

Idempotent. install writes/overwrites the canonical hook script, re-creates the Claude plugin dir, re-merges the Codex managed block (replacing any prior _ainb_managed entries — never duplicating). Running twice produces the same on-disk state as running once.

How do I confirm it works on my real Claude Code or Codex sessions?

cd ainb-tui && cargo install --path crates/ainb-core --force (your existing ~/.cargo/bin/ainb is the pre-merge build), then scripts/live-validate-ainb-hooks.sh --real-session. The script pauses after starting the daemon — launch a real claude or codex session, do something, then come back. It prints the rows that actually landed.

Why does the discoverability test exist if the keystroke test already passes?

Because the original tripwire only proved pressing I opens the inbox. It never asserted there was a visible cue that I was a shortcut. The follow-up regression: an undiscoverable feature can pass green CI. The new pre-assertion checks for 📥, Inbox, and [I] in the home-screen capture before firing the keystroke.