TaskCollab Runner

External runner CLI for TaskCollab.

See ../TODO.md for shared work tracking. See ../CHANGELOG.md for shared release notes.

Install

From source while the package is unpublished:

cd TaskCollabRunner
bun install
bun link

After publishing, install globally:

npm install -g @timtekno/tc-runner

Short alias: tcr

Setup on another machine

1. Ensure the machine can reach the TaskCollab server URL.
2. Install Bun and, for pi agents, install Pi.
3. In TaskCollab web, create/open an agent and copy the runner setup token.
4. Run:

tc-runner setup --server <url> --token <setup-token> --workdir /path/to/project
tc-runner status
tc-runner start

--workdir is optional and defaults to the current directory during setup. Use a stable project directory for Pi agents so web chat runs with the expected coding context.

setup prompts for missing server/token when run in a terminal.

Commands

• tc-runner setup --server <url> --token <setup-token> [--workdir <path>]
• tc-runner start [--interval <ms>] [--heartbeat-interval <ms>] [--chat-interval <ms>]
• tc-runner status
• tc-runner service <install|start|stop|uninstall|status>
• tc-runner logs [--follow] [--errors]
• tc-runner -p "hello"

start sends heartbeats in a loop and polls chat work separately. Default heartbeat interval is 30 seconds. Default chat poll interval is 2 seconds. --interval is kept as an alias for --heartbeat-interval. For pi agents, chat polling claims pending web chat messages, runs pi --mode json, and posts replies back to the server.

Prompt mode uses the saved agent type from setup. For now, only pi is supported and it runs pi -p <prompt>.

Service/autostart

Install service after setup:

tc-runner service install
tc-runner service start
tc-runner service status

Supported best-effort service targets:

• Linux: user-level systemd service.
• macOS: user LaunchAgent.
• Windows: user Scheduled Task at logon.

Service install captures the current PATH so commands installed in user locations, such as pi or bun, are available when the service starts. Re-run tc-runner service install after changing PATH or moving the runner.

If service setup fails, use foreground mode:

tc-runner start

Logs are written to the runner config directory:

tc-runner logs
tc-runner logs --errors
tc-runner logs --follow

Notes

This scaffold stores local config in the user app data directory and talks to the TaskCollab runner API.

Web chat uses Pi's own session storage. Each TaskCollab chat thread stores the Pi session ID returned by pi --mode json and is pinned to the runner that first processes it. Keep --workdir pointed at a stable project directory so Pi loads the intended project context and can resume sessions reliably.