Agent integrations

berth works with the tools around it in both directions: tools drive berth through its CLI, and berth drives tools through hooks. Every event records the tool it came from, so a change never bounces back and forth between two tools.

Agent tools → berthCopy Anchor Link

Claude Code, Cursor, CodexCopy Anchor Link

berth integrations install claude     # on a laptop
berthd integrations install claude    # on a box, where agents usually run
berth integrations install all

• Claude Code: installs berth's skills in ~/.claude/skills/ and Stop / Notification / SessionStart / UserPromptSubmit hooks in ~/.claude/settings.json.
• Cursor: appends a stop hook to ~/.cursor/hooks.json, after any hooks already there (Orca's are kept).
• Codex: installs berth's skills in ~/.agents/skills/, where Codex reads user skills (a copy an older berth left in ~/.codex/skills/ is removed), and prints the notify line to add to ~/.codex/config.toml, which berth does not edit because it holds a single value you may already use.

Installs are idempotent, keep every existing setting, back up the previous file to *.berth-backup, and refuse to touch a file that is not valid JSON.

The hooks run berth hook TOOL EVENT, which turns the tool's payload into an event (agent.finished, agent.waiting, agent.started, agent.ready). Only identifiers and the working directory are kept: prompts, messages, and transcripts never leave the tool. A hook never fails or blocks the tool that called it.

SkillsCopy Anchor Link

berth ships four skills, embedded in the binary:

Install them for the box's user, or inside one repository for just that project, for Claude Code, Codex, or both:

berthd skills                                         # what is installed where
berthd skills install                                 # all, for both agents, for this user
berthd skills install berth-preview --agent claude --target project --location cal
berthd skills install --target project --location cal --commit   # visible to git, to share
berthd skills uninstall berth-hooks
berth skills devl install                             # the same from a laptop

Project skills are listed in the repository's .git/info/exclude so they are not committed, unless installed with --commit. berthd skills reports each copy as installed, outdated (berth has a newer version: install again) or missing; the app shows the same in Settings → Agents and in a project's settings. Removing only deletes a folder whose SKILL.md is berth's skill of that name.

The API is GET /v1/skills[?location=L], and POST /v1/skills/install and POST /v1/skills/uninstall with {skills, agent, target, location, commit}. Changes announce skills.installed and skills.removed, and before:skills.install and before:skills.uninstall gates can refuse them.

The skills tell agents never to share a port publicly unless a person asked, and never to answer an agent's question on the user's behalf.

Anything elseCopy Anchor Link

Any script can announce an event:

berth emit agent.finished path="$PWD" --origin=mytool     # on a laptop
berthd emit deploy.done url=https://… --origin mytool      # on a box

Worktrees from any toolCopy Anchor Link

berthd watches its locations. A worktree created by another app, an agent, or plain git worktree add shows up in berth and produces a worktree.created event with origin detected. Nothing needs configuring in those tools.

berth → toolsCopy Anchor Link

berth drives other tools through hooks and plugins rather than adapters built into it: a hook on worktree.created can register the worktree with any tool that has a CLI, and a plugin can ship those hooks along with its UI. See hooks and plugins.

berth events streams every event from the laptop and all its boxes; the full list is in events and gates.