ProjectDeveloper tooling / 2026
TraeX-Herdr-Agent-State
A lifecycle-hook bridge that makes TraeX visible as a live custom agent in Herdr TUI, with status updates and notifications.
An agent that belongs in the sidebar
Herdr is part of my daily terminal workflow. I wanted TraeX to appear in its agent sidebar as a live session, rather than just another terminal process whose state I had to check manually.
I built a small add-on that tells Herdr when TraeX is busy, needs approval, or has finished. The sidebar updates automatically.
In plain English
A plugin is a small add-on. This one connects TraeX’s activity to Herdr’s sidebar.
A hook is an automatic trigger: “When this happens, run this little program.” For example, when TraeX asks for permission, a hook tells Herdr that it is waiting for approval.
A state is just the agent’s current status:
working: Busy on a task.blocked: Waiting for your approval before continuing.idle: Not currently working, usually waiting for your next prompt.done: A turn finished and you have not checked that pane yet. Herdr figures out this indicator from the other updates; the plugin does not send a separatedonestate.
When TraeX exits, the plugin removes it from the sidebar. Lifecycle means that whole journey: starting a session, working, waiting, finishing, and exiting.
From a hook to a visible state
The flow is deliberately small: a TraeX hook passes its JSON payload to a shell wrapper, a Python bridge maps the event, and the bridge calls Herdr’s pane API.
The wrapper first checks that it is running inside a Herdr-managed pane. Outside that environment, it exits quietly. Reporting errors are swallowed so a status-update failure does not turn into a failed agent task.
The lifecycle mapping covers the useful transitions:
- A prompt or tool activity reports
working. - A permission request reports
blocked, with an awaiting-approval message. - A finished turn reports
idlewith a completion message. - An interruption reports
idlewith an interrupted message. - Session exit releases the custom agent, removing it from the sidebar.
done is not a state the bridge reports directly. Herdr derives it from an unseen transition from working to idle. That distinction keeps the integration aligned with Herdr’s reporting contract.
Small details that matter with several sessions
Each TraeX session has its own source authority, and reports carry nanosecond sequence numbers. Session identities distinguish reporters; ordered updates let Herdr reject stale events.
The bridge also forwards completion and permission-request notifications. The aim is simple: make it clear when the agent is working and when it needs me to come back.
Try it
The public repository is a TraeX plugin marketplace:
traecli plugin marketplace add \
https://github.com/ryamgoh/traex-herdr-agent-state.git --auto-update
traecli plugin install herdr-agent-state
Restart TraeX after installation so its hooks load. Some builds name the executable traex instead of traecli. The integration requires command hooks, Python 3.9 or later, and the Herdr CLI on the path; the repository documents the supported setup.
What I verified, and the limits
The repository includes a fake-Herdr CLI test harness. It replays lifecycle events across two sessions and checks the reported states, source identities, sequence arguments, notifications, and release on exit. The mapping was also checked against a real TraeX build.
On the tested TraeX builds, startup hooks fire with the first turn. A newly opened session therefore appears after its first prompt, not immediately at idle launch. Hook behavior is build-dependent, and Herdr may add its own TraeX support in a later version.
This bridge targets Herdr TUI’s pane CLI. The newer native Herdr app uses a different status-reporting protocol; it is not covered by this integration.
The workflow article shows how this fits alongside Lazygit, Neovim, and the rest of my terminal workspace.