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
codex   ~/.codex/hooks.json      UserPromptSubmit / PostToolUse
gemini  ~/.gemini/settings.json  BeforeAgent / AfterTool
hermes  ~/.hermes/config.yaml    pre_llm_call / post_tool_call

Every config is USER-level, written once per machine. Platforms read hook config only from the directory a session starts in — never a parent, never a subfolder — so a per-project file would fire only for sessions that happen to start there, and (living inside a mount) would sync to the whole team. One user-level registration covers every session in every folder; the guard below makes it a no-op outside BearDrive projects. Install migrates away any project-level hooks earlier versions wrote.

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(_ string, agent string) string
• func Detect(folder string) []string
• func Registered(folder, agent string) bool
• type Result
  • func Install(folder string, agents []string) ([]Result, error)
  • func Uninstall(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(_ string, agent string) string

ConfigPath returns where an agent's hooks are (or would be) registered: always the platform's USER-level config. The folder argument is ignored and kept only so callers read naturally; see the package doc for why hooks are no longer written per project.

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
	// Migrated names a project-level config an earlier version wrote, whose
	// hooks this run removed. Empty when there was nothing to clean up.
	Migrated string
}

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.

func Uninstall

func Uninstall(agents []string) ([]Result, error)

Uninstall removes BearDrive's hooks from each agent's user config, leaving every other hook in the file untouched.