Skip to content

macOS launchd

On a Mac that stays on (a Mac mini in a closet, a build machine), a per-user LaunchAgent keeps agentd running.

tclaude service install writes one like the example below as ~/Library/LaunchAgents/com.tofutools.tclaude.agentd.plist, logging to ~/.tclaude/data/launchd.log, and enables it for your next login. It keeps the serve flags the running agentd was started with and your current PATH, plus the environment of the launchd job it runs under, if any. Variables you only exported in a shell are not carried over. Pass other flags after --, or set a launch profile (see systemd: Launch profile), which works the same here. The plist holds its environment in EnvironmentVariables, inherited secrets included, so tclaude writes it 0600. It does not load the plist next to a running agentd. tclaude service status shows it, and tclaude service uninstall removes it. Both touch only a plist tclaude wrote.

To write it yourself, adapt this example:

~/Library/LaunchAgents/com.example.tclaude-agentd.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.example.tclaude-agentd</string>

  <key>ProgramArguments</key>
  <array>
    <string>/opt/homebrew/bin/tclaude</string>
    <string>agentd</string>
    <string>serve</string>
    <string>--no-tray</string>
    <string>--dashboard-port</string>
    <string>7878</string>
    <string>--persist-operator-token</string>
  </array>

  <key>EnvironmentVariables</key>
  <dict>
    <key>PATH</key>
    <string>/Users/you/.local/bin:/Users/you/.local/share/mise/shims:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
  </dict>

  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <dict>
    <key>SuccessfulExit</key>
    <false/>
  </dict>
  <!-- Leave the tmux server (and every agent) running when agentd exits. -->
  <key>AbandonProcessGroup</key>
  <true/>

  <key>StandardOutPath</key>
  <string>/Users/you/Library/Logs/tclaude-agentd.log</string>
  <key>StandardErrorPath</key>
  <string>/Users/you/Library/Logs/tclaude-agentd.log</string>
</dict>
</plist>

Load it, check it, and restart it after edits:

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.tclaude-agentd.plist
launchctl print gui/$(id -u)/com.example.tclaude-agentd
launchctl kickstart -k gui/$(id -u)/com.example.tclaude-agentd

To remove it, run launchctl bootout gui/$(id -u)/com.example.tclaude-agentd.

Caveats

PATH. launchd gives jobs a minimal PATH (/usr/bin:/bin:/usr/sbin:/sbin) and does not read your shell profile. Set the full PATH in EnvironmentVariables. Include Homebrew, the directories of each harness CLI, npm's global bin, and mise or asdf shims. The plist does not expand ~ or $HOME, so write absolute paths. printf '%s\n' "$PATH" in a login shell shows what you have. Agent panes inherit the environment of whatever started the tmux server, normally agentd, so this PATH is theirs too. tclaude harness ls shows what the daemon finds.

Login shell environment. When launchd starts the job tclaude wrote (label com.tofutools.tclaude.agentd), agentd serve asks your login shell for its environment and restarts itself with it, under the same PID. It runs $SHELL -l -i with no terminal. It waits only until the shell answers, and at most 30 seconds. That brings in what a terminal has: your profile's variables, TMUX_TMPDIR, proxies, and API keys. Without them, the job may run agents in another environment than a terminal-started agentd, or fail to reach their tmux server. The plist's own variables still win, and its PATH is kept after the shell's. When no UTF-8 locale is set anywhere, agentd gets your macOS locale (defaults read -g AppleLocale, for example en_GB.UTF-8), or en_US.UTF-8 when that is not installed. If the shell gives no answer, or fails, agentd still starts, with the plist's environment. output.log has an error line, and a notice in the dashboard's Messages says agents may not start or may show offline, and how to check (time $SHELL -l -i -c true). A plist you wrote yourself, under another label, is left as it is. Every restart tclaude starts (the dashboard's Restart agentd…, an update) asks the login shell again, also when agentd restarts in a new process instead of through launchd, so a toolchain or profile change since agentd started reaches it and the agents it starts next.

Restarts. KeepAlive with SuccessfulExit set to false restarts agentd when it crashes, but not after a clean exit. AbandonProcessGroup keeps launchd from cleaning up the job's processes when agentd stops. That keeps the tmux server, and the agents in it, alive for the next agentd to pick up. Agents lost to a reboot show as offline. Resume them from the dashboard or with tclaude agent resume <agent>.

Logs and the token. agentd writes its own rotated log to ~/.tclaude/data/output.log. The StandardOutPath file only catches startup output. Without a terminal, the startup banner leaves the operator token out. Do not add --print-human-token=always, which would write the bearer token to that log file. With --persist-operator-token the token goes to a 0600 ~/.tclaude/data/operator_token that the CLI reads. The --persist-operator-token-keychain variant is not read by the CLI, so with it you have to export TCLAUDE_HUMAN_TOKEN yourself before tclaude agent commands work.

Tray. A LaunchAgent in your GUI session can show the menu bar icon. Drop --no-tray if you want it. On a Mac you only reach over SSH, keep the flag.

No resource limits. Per-agent cgroups are Linux only. On macOS, a profile that authors resource_limits is refused by default. See Sandboxing.

Harness logins work as described in Running tclaude on a server. Run them in a shell as the same user. On macOS, some harnesses keep their credentials in the login keychain, which must be unlocked for the job to read it.

Then open the dashboard

At the Mac, tclaude agent dashboard opens it. To open it from Spotlight or Launchpad, tclaude service launcher install adds ~/Applications/tclaude.app; see App launcher. From elsewhere, use an SSH tunnel to the fixed port, a private network, or tclaude remote-access. See Reaching the dashboard and Dashboard.