Status Hooks

Status hooks let you run custom commands when a session’s state changes. This is useful for notifications, logging, or triggering automations.

Hook Types

You can configure hooks for each state transition:

Hook	Triggers When
On Idle	Session finishes working and is ready for input
On Busy	Session starts processing a request
On Waiting Input	Session needs your confirmation or input
On Pending Auto-Approval	Session is being evaluated for auto-approval

Configuring Hooks in the WebUI

The WebUI makes it easy to set up status hooks:

1. Click the gear icon in the header to open Settings
2. Select Status Hooks from the sidebar
3. Enter a shell command for each state you want to hook
4. Toggle the hook on with the checkbox
5. Click Save Changes

Screenshot: Settings → Status Hooks panel with notification commands configured

Environment Variables

Your hook commands have access to these variables:

Variable	Description
CACD_WORKTREE_PATH	Path to the session’s worktree
CACD_WORKTREE_BRANCH	Branch name of the worktree
CACD_GIT_ROOT	Root of the Git repository
CACD_SESSION_ID	Unique ID of the session
CACD_OLD_STATE	Previous state (idle, busy, waiting_input)
CACD_NEW_STATE	New state

Examples

Desktop Notification (macOS)

Get notified when a session needs attention:

osascript -e 'display notification "Session needs input" with title "CACD"'

Desktop Notification (Linux)

notify-send "CACD" "Session needs input"

Logging

Log state changes to a file:

echo "$(date): $CACD_SESSION_ID changed from $CACD_OLD_STATE to $CACD_NEW_STATE" >> ~/.cacd-log.txt

Play a Sound

afplay /System/Library/Sounds/Ping.aiff

Slack/Discord Webhook

curl -X POST -H 'Content-type: application/json' \
  --data '{"text":"CACD session waiting for input"}' \
  YOUR_WEBHOOK_URL

Tips

• Keep hooks fast - slow commands will delay state updates
• Hook failures don’t break CACD, but check your commands work standalone first
• Use On Waiting Input for notifications - that’s when you need to act
• Combine with terminal multiplexers or window managers to auto-focus CACD when needed