claudectl-hooks

Officially verified hooks for claudectl — the TUI for monitoring and managing Claude Code sessions.

Verified Hooks

Hook	Event	Description	Dependencies
notify-macos	on_needs_input	macOS native notification when Claude needs input	None
notify-sound	on_needs_input	Play a sound when Claude needs input	say (macOS)
session-log	on_session_start, on_finished	Log all sessions to CSV	None
auto-commit	on_finished	Git commit changes when Claude finishes	git
slack-notify	on_needs_input, on_finished	Post session updates to Slack	curl

---

notify-macos

macOS notification when a session needs input.

[hooks.on_needs_input]
run = "osascript -e 'display notification \"{project} needs input\" with title \"claudectl\"'"

notify-sound

Speak a notification using macOS text-to-speech.

[hooks.on_needs_input]
run = "say 'Claude needs your attention in {project}'"

session-log

Log session starts and completions to a CSV file for tracking.

[hooks.on_session_start]
run = "echo \"$(date -Iseconds),start,{pid},{project},{model}\" >> ~/.local/share/claudectl/session-log.csv"

[hooks.on_finished]
run = "echo \"$(date -Iseconds),finished,{pid},{project},{cost},{tokens_in},{tokens_out},{elapsed}\" >> ~/.local/share/claudectl/session-log.csv"

auto-commit

Automatically commit all changes when a Claude session finishes. Useful for solo dev workflows.

[hooks.on_finished]
run = "cd {cwd} && git add -A && git diff --cached --quiet || git commit -m 'ai({project}): session completed (${cost}, {elapsed})'"

Note: Only commits if there are staged changes. Review the diff before pushing.

slack-notify

Post session updates to a Slack channel via incoming webhook.

[hooks.on_needs_input]
run = "curl -s -X POST -H 'Content-Type: application/json' -d '{\"text\":\"claudectl: *{project}* needs input (${cost})\"}' https://hooks.slack.com/services/YOUR/WEBHOOK/URL"

[hooks.on_finished]
run = "curl -s -X POST -H 'Content-Type: application/json' -d '{\"text\":\"claudectl: *{project}* finished — ${cost}, {elapsed}\"}' https://hooks.slack.com/services/YOUR/WEBHOOK/URL"

Replace the webhook URL with your own from Slack Incoming Webhooks.

---

Template Variables

Available in all hook run commands:

Variable	Description	Example
{pid}	Process ID	12345
{project}	Project name	my-app
{status}	Current status	Needs Input
{cost}	Session cost in USD	3.45
{model}	Model name	opus-4.6
{cwd}	Working directory	/Users/me/projects/my-app
{tokens_in}	Input tokens	500000
{tokens_out}	Output tokens	50000
{elapsed}	Elapsed time	01:23:45
{session_id}	Session UUID	abc-def-123
{old_status}	Previous status (status_change only)	Processing
{new_status}	New status (status_change only)	Needs Input

Submitting a Hook

We accept hook submissions that are useful, secure, and reliable.

To submit a hook for verification:

1. Open an issue with:

   • Hook name and one-line description
   • The config snippet ([hooks.on_*] section)
   • What problem it solves — describe the use case
   • Dependencies — any external tools required
   • Security considerations — does it send data externally?

2. We review for:

   • Security — no credential leaks, no untrusted code execution
   • Reliability — handles edge cases (spaces in paths, special characters)
   • Usefulness — solves a real problem for claudectl users

3. Approved hooks are added to this repository with attribution.

Guidelines:

• Hooks must work with a standard shell (sh or bash)
• No root/sudo required
• External service hooks (Slack, Discord) must document the setup clearly
• Hooks should fail silently — never block claudectl's TUI

License

MIT