agenthooks

Documentation

Overview

Package agenthooks detects which AI agent platforms a user works with and registers BearDrive's sync hooks in each platform's own hook config, so files sync at turn boundaries no matter which agent edits them.

Every supported platform runs command hooks the same way — spawn a shell command, pipe event JSON (with a session_id) on stdin — so one hook command works everywhere; only the config file format and event names differ:

claude  .claude/settings.json    UserPromptSubmit / PostToolUse   (project)
codex   .codex/hooks.json        UserPromptSubmit / PostToolUse   (project)
gemini  .gemini/settings.json    BeforeAgent / AfterTool          (project)
hermes  ~/.hermes/config.yaml    pre_llm_call / post_tool_call    (user)

The hook syncs the project and stamps changes with "<agent> session <id>" (see `bdrive sync --note`), so hub history links every change to the agent session that made it. A third hook runs `bdrive read-log` on each platform's read-shaped tools — native file reads, grep-style searches (the files the matches came from), and shell commands (the existing files they name) — queueing agent file reads for the hub's read heatmap (drained on the next sync — the hook itself never touches the network). Listing tools (glob, ls) are deliberately unmatched: seeing a file's name is not reading it. Hooks are fast no-ops outside bdrive projects, and reinstalling upgrades a registered hook's matcher in place when coverage grows.

Index

• Variables
• func ConfigPath(folder, agent string) string
• func Detect(folder string) []string
• func Registered(folder, agent string) bool
• type Result
  • func Install(folder string, agents []string) ([]Result, error)

Variables

var Agents = []string{"claude", "codex", "gemini", "hermes"}

Agent names, in the order they are reported.

Functions

func ConfigPath

func ConfigPath(folder, agent string) string

ConfigPath returns where an agent's hooks are (or would be) registered.

func Detect

func Detect(folder string) []string

Detect reports which agent platforms are in use, judged by their config dirs existing in the project or the home directory.

func Registered

func Registered(folder, agent string) bool

Registered reports whether an agent's config already carries our hooks.

Types

type Result

type Result struct {
	Agent   string
	Path    string // config file the hooks live in
	Changed bool   // false = already registered
	Note    string // extra step the user must take, if any
}

Result reports what Install did for one agent platform.

func Install

func Install(folder string, agents []string) ([]Result, error)

Install registers the sync hooks for the given agents ("auto"/empty = every detected platform). Merging is idempotent and preserves whatever hooks the config already has.