Agent Integration

Namu provides hook-based integration with AI coding agents. Rather than embedding an AI chatbot, Namu exposes infrastructure that agents call into: IPC hooks, agent PID tracking, session state, per-workspace port allocation, and outbound alert routing.

Claude Code Hook Integration

Namu supports 10 Claude hook event types for deep integration with Claude Code sessions. A wrapper script intercepts Claude Code invocations and injects session tracking.

Hook Event Types

• SessionStart — Triggered when a Claude session begins
• UserPromptSubmit — Triggered when a prompt is submitted
• PreToolUse — Triggered before a tool call executes
• Notification — Triggered on Claude notification events
• Stop — Triggered when generation stops
• SessionEnd — Triggered when the session ends
• PermissionRequest — Triggered on permission prompts
• SubagentStop — Triggered when a subagent finishes
• TaskCompleted — Triggered on task completion
• TeammateIdle — Triggered when a teammate becomes idle

What the Hooks Do

• Track agent PID per surface (set_agent_pid claude_code <pid>)
• Update sidebar status for Claude Code activity
• Send targeted notifications to the workspace surface
• Store session state at ~/.namu/claude-hook-sessions.json (7-day TTL)

Claude Code Teams

namu claude-teams          # run Claude Code in teammate mode
namu claude-hook session-start
namu claude-hook prompt-submit
namu claude-hook stop

claude-teams creates a fake tmux shim, translates Claude Code's tmux commands to Namu socket operations, and provides workspace context via system.identify RPC.

Disable

export NAMU_CLAUDE_HOOKS_DISABLED=1

Codex Hook Integration

Hook support for OpenAI Codex with session-start, prompt-submit, and stop events.

namu codex install-hooks
namu codex uninstall-hooks
namu codex-hook session-start
namu codex-hook prompt-submit

Agent PID Tracking

Namu tracks running agent processes per surface. This powers status display, process monitoring, and cleanup on workspace close.

# Via socket API
{"method":"system.set_agent_pid","params":{"agent":"claude_code","pid":12345}}
{"method":"system.clear_agent_pid","params":{"agent":"claude_code"}}

Per-Workspace Port Allocation

Each workspace gets a dedicated port range, injected as environment variables into every terminal surface. This lets multiple agent sessions run servers without port conflicts.

NAMU_PORT=3000
NAMU_PORT_END=3099
NAMU_PORT_RANGE=3000-3099

Alerts and Channels

Namu includes a rule-based alert engine with 4 trigger types. Alerts are independent of any AI layer.

EventBus event (process.exit | output.match | port.change | shell.idle)
  --> AlertEngine (4 trigger types)
    --> AlertRouter
      --> Slack / Telegram / Discord / Webhook

Alert Channels

• Slack — Native integration with credential security
• Telegram — Outbound delivery to Telegram bots
• Discord — Discord webhook support
• Webhook — Generic delivery with custom headers and payload formatting

Configure channels in Settings. Credentials are stored in the Keychain.