Start
Connect your agents
Widgetful learns the state of each session from a small hook. Connect each agent one time. You see the exact change before Widgetful writes it.
Connect an agent
- Click Widgie in the menu bar, then open Settings › Agents.
- Find the agent in the list. Widgetful shows each agent that it finds on the Mac.
- Click Connect.
- Start a new session of the agent. The session shows in the panel.
If you install an agent after Widgetful, click Find agents again.
Note: Codex needs one more step. Open Codex, type
/hooksand trust the Widgetful hooks. Codex runs a new hook only after you trust it.
What Widgetful changes
Widgetful adds its hooks and keeps all your other settings and hooks. Before each change, it saves a copy of the old file as <file>.widgetful-backup.
| Agent | ID | File |
|---|---|---|
| Claude Code | claude-code | Adds hooks to ~/.claude/settings.json |
| Codex | codex | Adds hooks to ~/.codex/hooks.json |
| OpenCode | opencode | Adds a plugin file, ~/.config/opencode/plugins/widgetful.js |
OpenCode has no hook settings, so Widgetful adds one small plugin file. You can read the file. It sends the same facts as the hooks.
Agents that Widgetful cannot connect yet
Widgetful also lists agents that it finds but cannot connect yet, for example Cursor Agent and Gemini CLI. These show as Not supported yet.
How Widgetful finds an agent
A menu bar app does not get the PATH of your shell. Widgetful looks for the command of each agent in the usual install folders, for example ~/.local/bin, /opt/homebrew/bin, /usr/local/bin and ~/.opencode/bin. If the command is not there, the settings folder of the agent counts as a find.