Waycar hooks for tmux

On tmux, Waycar learns what an agent is doing from small Status Hooks inside the agent. When an agent starts working, stops to ask you something, or finishes, its hook tells tmux, and Waycar reads it. That powers agent status, Blocked and Done notifications, and Live Activities on tmux Hosts. herdr Hosts don’t need them.

Which agents have hooks?

Claude Code, Codex, omp, pi and opencode. Most other agents show Unknown on tmux for now.

Install the hooks

The install command adds the hooks for every supported agent that’s already installed:

curl -fsSL https://waycar.dev/install.sh | sh

Installed an agent later? Run the install command again.

You can also install them from the app. Tap Hosts, open the tmux Host, and look under Status Hooks. Each agent reads Installed or Not installed. Tap Install Status Hooks to add the missing ones.

If the Host page says Waycar’s host tools aren’t installed, tap Copy Install Command and run it on the Host.

Codex asks you to review them once

Codex doesn’t turn on new hooks by itself. Open Codex once on the Host and approve Waycar’s hooks on its /hooks screen. Until then, the Host page reminds you: “Open Codex once and approve Waycar’s hooks in /hooks.”

Manage the hooks from the terminal

The install command puts a waycar command on the Host:

waycar hooks status
waycar hooks install
waycar hooks uninstall

• waycar hooks status shows which agents have current hooks.
• waycar hooks install adds Waycar’s entries to each agent’s config and keeps every other hook you have.
• waycar hooks uninstall removes only Waycar’s entries and files.

If you ran the installer with --no-hooks, it skipped the hooks. Add them later with waycar hooks install. Every subcommand is listed in The waycar command on your Host.

What does waycar hooks status say?

Each agent gets one line ending with its config file:

State	Meaning
installed	Current Waycar hooks are in place.
out of date, run `waycar hooks install`	Waycar’s hooks are there but from an older version or another install folder.
not installed	The agent is on the Host but has no Waycar hooks.
not installed (agent not found)	Waycar didn’t find the agent.
off (`[features] hooks = false`)	Codex’s config turns hooks off. See Codex hooks are turned off.
error: …	Waycar couldn’t read the agent’s config, for example invalid JSON. The file is left unchanged.

For Codex, it can add a line asking you to open Codex and run /hooks.

Which files do the hooks change?

Agent	File
Claude Code	~/.claude/settings.json (or $CLAUDE_CONFIG_DIR/settings.json)
Codex	~/.codex/hooks.json, plus [features] hooks = true in ~/.codex/config.toml (or both under $CODEX_HOME)
omp	~/.omp/agent/extensions/waycar-agent-state.ts
pi	~/.pi/agent/extensions/waycar-agent-state.ts
opencode	waycar-agent-state.js and waycar-chat-prompt.js in ~/.config/opencode/plugins (or under $XDG_CONFIG_HOME)

For Claude Code and Codex, Waycar merges its entries into the file and keeps your other hooks. Codex’s notify setting is never touched. The omp, pi and opencode files carry an installed by waycar line; if a file with the same name exists without it, Waycar leaves it alone. waycar hooks install prints each file it updates.

What do the hooks do on my machine?

Each hook runs waycar-hook, a short shell script that sets a value on the agent’s tmux pane, prints nothing, and starts waycar notify in the background. waycar notify sends the encrypted Blocked and Done notifications and Live Activity updates to Waycar’s push relay. Hooks only act inside tmux, and stay out of the way in a herdr pane, where herdr tracks status itself.

Troubleshooting

• Agent shows Unknown. Check Status Hooks on the Host page, install any missing hooks, and for Codex, approve them in /hooks. See Agent status shows Unknown.
• No Blocked or Done notifications on tmux. These come from the same hooks. See Notifications don’t arrive.