Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
coding_agent_worker
What it is
Part of agent sessions: macrod, the agent harness daemon operators run on
their own machine — serves a registered harness's agent sessions, bridges
the local ACP process (Claude Code, Codex, ...), and drives native
herdr sessions, all inside one terminal control panel.
Start here
src/main.rs: module list and the composition root's CLI entrypoint.src/config.rs:macrod.toml— the daemon's one input, machine-local only (seeconfig.example.toml,default.macrod.toml). The TUI andmacrod serviceshare~/.macrod/macrod.toml(--configoverrides it), locked by<config>.lockwhile running. Name, ownership, and permission bypass live only on the web (Settings → Agents → Runtimes); a file that still has[identity]or ascopein[credentials]fails to load with an error naming that page. The event stream reads the owner fromGET /harnesses/meon each connect.[macro]is a dev override that defaults to production.src/daemon.rs+src/runtime.rs: the serving core — persistent harness service connection, ACP process bridge, start/stop/restart on re-pair.src/self_knowledge.rs: the<macrod-runtime>section the bridge (src/harness.rs) prefixes to each new session's first prompt — macrod version, workspace, forwarded MCP servers, permission bypass, listing only what the session has. General Macro guidance stays in theSelfKnowledgetool.src/trigger.rs+src/dispatch.rs: agent-trigger broker events → session create/dial/prompt against the live harness service.src/daemon.rswatch_presence: each minute a connection has held, asksGET /harnesses/mewithRUNTIME_CONNECTED_HEADER. A service that reads the harness offline logsharness_presence_disagreement, macrod warns, and the TUI header says "runtime connected, service reports offline" instead of "paired, runtime not dialed in".src/tui.rs(src/tui/): the control panel itself (registration, agents, sessions, config form, logs).src/herdr.rs(src/herdr/): native herdr integration — only compiled#[cfg(unix)].src/herdr/cli.rspicks herdr 0.9 (herdr) or herdr-core (hc) by environment; both stay supported.src/executable.rs:PATHlookup; every spawn of a bare command name goes throughlaunchable, which finds Windows.cmdshims (npm,npx) and never npm's extensionless shell script beside them. The Claude Code adapter gets the program behind an npmclaude.cmd(npm_shim_target_or_self): the Claude SDK spawnsCLAUDE_CODE_EXECUTABLEwithout a shell, and Node refuses.cmdfiles there.install/:install.shandinstall.ps1, the one-line installers the docs serve frommain.install.shadds~/.local/binto the shell's startup file once (--no-modify-pathopts out);install.ps1installs the Windows launcher layout. Both takeMACROD_UPDATE_SOURCE.src/update.rs(src/update/): self-update. The TUI polls the latest GitHub release hourly (or theMACROD_UPDATE_SOURCEmirror:latest.jsonplus the archives beside it), verifies and smoke-tests the new binary, and onceDaemon::is_idle(nosession/promptoutstanding,src/turns.rs) swaps it in andexecves. Spans:macrod.update.check,macrod.update.download,macrod.update.apply,macrod.update.handoff. Off with[update] auto = falseorMACROD_NO_UPDATE=1. Every check, download, apply and TUI startup appends a JSON line to~/.macrod/logs/update.log(src/update/log.rs; 0600, rotated at 1 MB toupdate.log.1); the Logs tab shows the path. Versions and outcomes only.src/handoff.rs: the Unix hot handoff.harness.rsis macrod's own line relay (outbound/acp_process/running.rs), so it can stop at a line boundary and pass the live agent (pid, pipes, unread bytes, running prompts) to the next image through a versioned state file named byMACROD_HANDOFF_FD. State the new image cannot read kills the agent and starts fresh. BumpFORMAT_VERSIONwhenHandoffStatechanges.src/update/versions.rs: the Windows layout.macrod.exeonPATHis a launcher for the newestversions\<tag>\macrod-core.exe; updates install as a new version for the next launch and the footer says so.e2e/: end-to-end update and installer tests (build_releases.sh,update_e2e.py(update, prompt-in-gap, output-in-gap, and the negative cases),installer_test.sh,windows_test.ps1for the launcher layout,windows_update_test.ps1for a running macrod updating itself,windows_claude_code_test.ps1for npm-installed Claude Code served over ACP), run by thetest_macrod_updateworkflow on Linux, macOS and Windows.README.md: native Herdr session behavior (repositories, reconnect, model switching, MCP) — read before changing anything undersrc/herdr/.
Scope
- Owns: the
macrodbinary end to end — config, pairing, the harness bridge, trigger dispatch, native herdr session control, and the TUI. - Not here: the trigger event vocabulary (
agent_trigger), the fold/transcript logic for a given provider (claude_fold,codex_fold), or the harness service itself (services/agent_harness_service).
Recipes
- Add a config field (machine-local only: commands, paths, local launch
defaults; runtime behaviour a Macro user controls belongs on the web harness
row, and never put a launch command on the web):
src/config.rs→config.example.toml→default.macrod.toml→ the TUI config form (src/tui/config_form/). - Handle a new trigger kind:
src/trigger.rs→src/dispatch.rs→ its tests. - Add/change a native herdr control (command, model picker):
src/herdr/controls/→README.md(native controls section) →src/herdr/acp_agent/.
Channel/document trigger prompts retain their source message ID through
TriggerWork and send it as ControlRequest.action_id. Preserve this correlation
for initial mentions, existing-session follow-ups, and conflicted-create retries;
external chat replies depend on it. Direct session controls still mint IDs.
Checks
cargo test -p coding_agent_worker(SQLX_OFFLINEunset).just run(from this directory) to run the daemon with--config <repo root>/macrod.toml, keeping dev off~/.macrod/macrod.toml.- Self-update end to end (Linux/macOS):
e2e/build_releases.sh /tmp/rel v2000.1.1.1 v2000.1.1.2, thenpython3 e2e/update_e2e.py --releases /tmp/rel --v1 v2000.1.1.1 --v2 v2000.1.1.2, ande2e/installer_test.sh /tmp/rel v2000.1.1.1with zsh and fish onPATH.MACROD_UPDATE_CHECK_SECONDSshortens the check interval. OPENSSL_NO_VENDOR=0 just build-staticto build and smoke-test the releasemacrodthe way the tag workflow does (needs the Nix devshell: cargo-zigbuild, zig, cmake). The override enables bundled OpenSSL for the musl target in the devshell.- Windows is built natively on a Namespace Windows runner by
build_agent_daemon_on_tag(MSVC, static CRT). Run that workflow withworkflow_dispatchon your branch to check a Windows-affecting change. cargo tree -p coding_agent_worker -i rdkafka-sys --target x86_64-unknown-linux-muslmust find nothing: librdkafka breaks the static and Windows builds.
Gotchas
src/herdr.rsand its submodule are Unix-only (#[cfg(unix)]); don't add Windows-breaking code there without a cfg gate.- The ACP child is killed with its whole tree: a process group on Unix, a Job
Object on Windows (
src/outbound/acp_process/job.rs). - Every herdr call goes through the
HerdrClifacade; add a capability to bothcli/legacy.rsandcli/hc.rs. herdr-core has no agent registry or worktrees, and status comes only from OSC 7501 (README.md, "Herdr versions"). - macrod never pulls into the operator's working branch — new herdr worktrees
start from a fresh fetch of
origin/main(see README.md). - Only release builds update themselves: the tag workflow compiles the tag in
as
MACROD_RELEASE_TAG, and a build without avYYYY.MM.DD.Ntag never polls.macrod service(the desktop app's bundled copy) never updates; the desktop app updates it. - The update still waits for idle although the agent survives it: the
harness service ends a session's turn when its runtime connection closes,
so a turn in flight would be cut off in Macro. After a handoff the service
re-runs
initializeandsession/resume(orload) on the live agent. - A
macrod herdr-acpharness is a child process, so it is handed off like any agent and keeps running the old binary until it restarts. - Switching native agents clears the previous agent's model/extra-args but keeps storage and focus preferences (README.md, "Setup").
Related
README.mdin this directory is the native herdr behavior contract — update it alongsidesrc/herdr/changes.- MCP server selection is supplied by
agent_harnesswhen the session binds; native launch forwards that list, with credentials refreshed on launch/resume.