Skip to content
Supaterm
Esc
↑↓navigate↵open⌘Jpreview
On this page

Agent Commands

sp agent manages Supaterm’s coding-agent hook bridge.

Install Skill

Install Supaterm’s bundled agent skill:

sp skills install

The command copies the stable discovery skill bundled with the running Supaterm version to ~/.agents/skills/supaterm. Existing Supaterm skill directories or symlinks are replaced. Detailed instructions remain bundled with sp and are loaded through sp skills get.

Install Hooks

Install Supaterm’s managed hook bridge into an agent configuration:

sp agent install-hooks
sp agent install-hook claude
sp agent install-hook codex

Effects:

  • install-hooks installs every supported Supaterm hook bridge
  • claude installs Supaterm hooks into ~/.claude/settings.json
  • codex requires Codex 0.144.1 or newer, enables hooks, installs Supaterm hooks into ~/.codex/hooks.json, and registers native trust through Codex app-server

Remove Hooks

Remove Supaterm-managed hooks from an agent configuration:

sp agent remove-hook claude
sp agent remove-hook codex

Removing Codex hooks also removes Supaterm hook trust through Codex app-server.

Forward Hook Events

sp agent receive-agent-hook --agent <agent> reads one hook payload from stdin and forwards it to Supaterm.

printf '{"hook_event_name":"Notification","message":"Claude needs your attention"}' \
  | sp agent receive-agent-hook --agent claude

Installed hooks pass the parent process ID:

printf '{"hook_event_name":"PreToolUse","session_id":"session-1","cwd":"/tmp/project"}' \
  | sp agent receive-agent-hook --agent codex --pid 123

Root hook payloads should include the agent’s absolute cwd. Supaterm uses it for the agent panel Workspace row, Git status, and forked session working directory. Child-agent directories do not replace the root workspace.

Use this when wiring an external agent hook system into Supaterm. This is lower-level than install-hook and remove-hook.

Pi integrations use this lower-level forwarding command from the Pi extension:

printf '{"hook_event_name":"session_start","session_id":"session-1","source":"pi-notify-supaterm"}' \
  | sp agent receive-agent-hook --agent pi --pid 123

Output

receive-agent-hook is a forwarding command. skills install, install-hook, and remove-hook report failures through stderr and exit status.