bark-agent-hook 0.1.3

Bark notification hooks for Codex, Claude Code, and OpenClaw agents.

bark-agent-hook

Standalone Bark notification hooks for Codex, Claude Code, and OpenClaw.

Overview

bark-agent-hook is a Python 3.10+ Typer CLI that installs companion hook assets for local coding agents and sends concise Bark notifications when agent lifecycle events need attention or have completed. The package keeps runtime behavior focused on hook execution, plugin installation, and safe notification delivery.

The project includes:

• bark_agent_hook/: the typed Python package and CLI entry point.
• plugins/: runtime plugin assets for Codex, Claude Code, and OpenClaw.
• tests/: CLI and plugin manifest coverage.
• .github/: issue templates, PR template, CI, Dependabot, and expected repository governance settings.

Install

Install the CLI from PyPI:

pip install bark-agent-hook
bark-agent-hook --help

If you prefer uv-managed command-line tools:

uv tool install bark-agent-hook
bark-agent-hook --help

You can also run the CLI without installing it first:

uvx bark-agent-hook --help
uvx bark-agent-hook hook --runtime codex --event completion --dry-run

For real agent hooks, keep bark-agent-hook installed in PATH. The installed Codex, Claude Code, and OpenClaw plugins invoke bark-agent-hook hook ... when the agent emits lifecycle events.

Plugin Setup

Install all locally available agent plugins after installing the CLI:

bark-agent-hook install

Install one or more specific agents:

bark-agent-hook install --agent codex
bark-agent-hook install --agent claude --agent openclaw

uvx works for plugin setup too, but the hook runtime still needs an installed bark-agent-hook command later:

uvx bark-agent-hook install --agent codex

Uninstall plugin hooks without removing marketplace sources, environment variables, or historical audit logs:

bark-agent-hook uninstall
bark-agent-hook uninstall --agent codex

Upgrade the CLI with your package manager, then run install again to refresh companion plugins:

pip install --upgrade bark-agent-hook
bark-agent-hook install

Runtime Configuration

BARK_DEVICE_KEY is required for real delivery. Missing or empty values skip notification delivery and exit successfully.

Common optional settings:

BARK_SERVER=https://api.day.app
BARK_GROUP=
AGENT_BARK_NOTIFY_GROUP_MODE=agent
AGENT_BARK_NOTIFY_HOOK_URL=
AGENT_BARK_NOTIFY_TITLE_TEMPLATE=
AGENT_BARK_NOTIFY_AUDIT_LOG=1
AGENT_BARK_NOTIFY_AUDIT_LOG_FILE=~/.bark-agent-hook/bark-agent-hook.log

The AGENT_BARK_NOTIFY_* variable names are intentionally preserved for compatibility with existing hook configuration.

Notifications are sent with Bark's Markdown field by default. The short body summary is still produced for dry-run output, duplicate detection, audit metadata, and future compatibility fallbacks, but real Bark requests send markdown when available.

The default title is intentionally compact:

{event} - {project}

Use AGENT_BARK_NOTIFY_TITLE_TEMPLATE to override it. Available title values include {agent}, {event}, {project}, {runtime}, {cwd_basename}, {branch}, and {session}.

Hook Commands

These are the commands installed into the companion plugins:

bark-agent-hook hook --runtime codex --event approval_needed --summary-mode extract
bark-agent-hook hook --runtime codex --event completion --summary-mode extract
bark-agent-hook hook --runtime claude --event approval_needed --summary-mode extract
bark-agent-hook hook --runtime claude --event completion --summary-mode extract
bark-agent-hook hook --runtime openclaw --event completion --summary-mode extract

Local dry-run check:

printf '%s' '{"session_id":"demo","cwd":"/tmp/demo-project"}' \
  | BARK_DEVICE_KEY=device-key bark-agent-hook hook --runtime codex --event completion --dry-run

Development

This project uses uv, Ruff, mypy, pytest, tox, and pre-commit.

uv sync --group dev
uv run pytest -q
uv run pre-commit run --all-files
uv build

This repository does not maintain generated command docs; bark-agent-hook --help is the command reference.

Testing And Build

Run the focused test suite during normal development:

uv run pytest -q

Run the compatibility matrix before release-sensitive changes:

uv run tox

Build local distributions with:

uv build

Release

The CI workflow validates pull requests and main pushes. Merges to main can create a GitHub release for the current project.version when one does not already exist. Publishing to PyPI uses trusted publishing through the protected pypi GitHub environment.

Manual PyPI publishing is available through the workflow_dispatch path by providing an existing stable x.y.z release tag. The workflow verifies required CI checks for the release commit before publishing.

Branch And Review Policy

The repository uses GitHub Flow:

• Open or pick an issue before starting work.
• Branch from main using a scoped branch name such as chore/13-governance-audit-remediation.
• Keep changes scoped to the issue.
• Open a PR against main and fill in the repository PR template.
• Required CI checks and review gates are declared in .github/settings.yml and should be verified on GitHub.

Documentation

Project documentation lives under docs/:

• docs/decisions/: architecture and governance decisions.
• docs/design/: user-facing behavior and design notes.
• docs/tech/: implementation notes and technical references.
• docs/release/: release and publishing notes.
• docs/postmortems/: incident and regression write-ups.

Ownership

CODEOWNERS assigns repository-wide ownership to @qsoyq. Security reporting instructions live in SECURITY.md, and contribution workflow details live in CONTRIBUTING.md.