Hooks

Agent Notifier ships one canonical Python hook runner for AI coding assistants: hooks/agent_notifier_hook.py. The runner turns lifecycle events into POST /v1/messages requests and can turn permission hooks into blocking POST /v1/approvals requests.

For agentic development, this is the core harness: while the agent works, hooks send progress, failures, approvals, links, explicit uploads, and completion states to your phone.

Flow

Agent event → uv run --script hooks/agent_notifier_hook.py → POST /api/v1/messages → APNs push → iOS feed
Permission event → uv run --script hooks/agent_notifier_hook.py → POST /api/v1/approvals → phone decision → rendered allow/deny JSON on stdout

Supported clients

• GitHub Copilot CLI workspace hooks
• Claude Code hooks
• CI/shell automation that invokes hooks/agent_notifier_hook.py with hook JSON
• Direct API callers using POST /api/v1/messages

One-click project install

Create an account API key in https://notifier.aicrew.in/app, choose a project label, then run this from the target repo:

export AGENT_NOTIFIER_API_KEY="an_key_REPLACE_WITH_YOUR_KEY"
export AGENT_NOTIFIER_PROJECT="my-repo"
curl -fsSL https://notifier.aicrew.in/install.sh | bash

The hosted installer downloads hooks/create-hook.sh, hooks/agent_notifier_hook.py, and scripts/lib/url-guard.sh from the public repository, then scaffolds project-local Copilot and Claude hook config. It writes the key and project name to .env.local, creates .env.local.agent-notifier.example, and appends a short Agent Notifier instruction block to CLAUDE.md when one is not already present.

Share https://notifier.aicrew.in/skill.md with an agent when you want the agent to perform the install for you. The skill instructs agents to ask for the API key/project name, keep secrets local, and notify at task start, major milestones, blockers, and completion.

Environment variables

AGENT_NOTIFIER_HOOK_SOURCE should use stable values such as github.copilot, claude.code, or cursor. If it is omitted, the runner infers the source from AGENT_NOTIFIER_HOOK_PATH (.github/..., .claude/..., or .cursor/...) so clients can show a friendly GitHub Copilot, Claude Code, or Cursor chip.

Blocking permission approvals

Set AGENT_NOTIFIER_APPROVAL_MODE=permission on permission-capable hooks (PermissionRequest, permission-style Notification, and Claude/Cursor PreToolUse). The runner sends /v1/approvals with wait=block, default decisions Allow and Deny, and prints the server-rendered response_payload to stdout so the agent can continue or deny the operation.

If the API key is missing, the network is unavailable, or approval mode cannot reach the backend, the runner fails open by printing an allow payload in the selected response format and logging the failure category locally. This keeps tools from deadlocking when a notification service is down.

Direct Python runner usage

printf '%s\n' '{"cwd":"/path/to/repo","tool_name":"Bash","tool_input":{"command":"go test ./..."}}' \
  | AGENT_NOTIFIER_HOOK_EVENT=PreToolUse \
    AGENT_NOTIFIER_HOOK_SOURCE=github.copilot \
    AGENT_NOTIFIER_HOOK_PATH=.github/hooks/hooks.json \
    uv run --script ./hooks/agent_notifier_hook.py >/dev/null || true

Event mapping guidance

Substance fields and structured metadata

Hook notifications send human-readable text for backwards compatibility, but current clients should prefer the top-level substance fields for primary rendering:

metadata remains the safe auxiliary/back-compat contract. The stable schema marker is agent_notifier_schema=hook.v1.

file_paths is metadata-only. The canonical runner never uploads ordinary file_path tool parameters because those often point at source files the agent merely inspected or edited. To attach bytes, use explicit JSON fields (media_file_path, media_file_paths, upload_file_path, attachment_path) or the explicit environment variables above.

Excerpt fields and top-level prompt/command substance exist only when a hook explicitly opts into details. They are bounded, locally redacted, and omitted from local proof logs unless the operator intentionally records redacted detail JSON.

Known hook_event_type values include session_start, session_end, user_prompt, tool_start, tool_success, tool_failure, test_passed, test_failed, file_modified, todo_update, subagent_start, subagent_stop, context_compaction, approval_needed, error, hook_event, and field_validation. Clients should treat unknown values as ordinary notifications instead of hiding or dropping them.

Safe logging

Proof logs should include request status, titles, and notification IDs only. They must not include API keys, bearer tokens, passwords, or raw secret-bearing request headers.