Work documentation

Overview

pearing-work is an event-driven orchestrator for external coding agents. It runs one shared pearing-cli tail-events subprocess, filters matching events for each configured agent, and dispatches event batches to agent commands through stdin prompts.

Each agent runs at most one invocation at a time. Events that arrive while an agent is already working are queued and delivered in the next batch when that agent becomes idle again.

Startup and environment

pearing-work reads a pearing-work.toml file and uses the existing pearing API environment:

• PEARING_API_URL points at the pearing API base URL.
• PEARING_API_TOKEN provides the bearer token for the shared pearing-cli subprocess.

Those variables are passed through to pearing-cli tail-events, but not to agent subprocesses.

export PEARING_API_URL="https://example.com/api"
export PEARING_API_TOKEN="your-token"

pearing-work -c pearing-work.toml
pearing-work -c /etc/pearing-work/pearing-work.toml --retry 5m --limit 1
pearing-work init
pearing-work init --config /path/pearing-work.toml
pearing-work --tui

The init subcommand writes a fully commented example config and refuses to overwrite an existing file.

Config file

The config file has one global [pearing-work] section and one or more [agents.NAME] sections. Relative paths are resolved from the config file directory.

[pearing-work]
agent_prompt_file = "prompt.j2"
retry = "5m"
limit = 1

[agents.codex]
cmd = ["codex"]
username = "codex"
workdir = "."
logdir = "logs/codex"
event_scopes = ["team:pearing", "repo:teams/pearing/pearing", "user:codex"]
event_kinds = ["user-mention", "pull-review-created", "pull-review-updated", "pull-review-deleted"]

• Global prompt settings can be inline or file-backed with Jinja2 rendering.
• Each agent defines its command, pearing username, working directory, and event subscription.
• Optional resume commands and session ID capture patterns support resumable agents.
• Optional per-agent log directories keep stdout and stderr archives per invocation.

Dispatch model

• One shared event stream is consumed from pearing-cli tail-events.
• Each enabled agent receives only events matching its configured scopes and kinds.
• Agents do not process their own self-events because the configured pearing username is used to filter them out.
• --limit or [pearing-work].limit can cap how many agents are in working state at once.
• --retry or [pearing-work].retry sets the bounded retry window for tail-events restarts.

TUI

Run pearing-work --tui to get a terminal dashboard over the orchestrator state. The screen shows:

• a header with config path, limit, retry window, and overall health
• an agent strip with current status for each configured agent
• attention, events, and log panes
• an expanded selected-agent view when requested

Key controls:

• q or Ctrl-C: quit
• Tab: cycle panes
• Left/Right: change selected agent
• Up/Down: scroll the focused pane
• Enter: toggle expanded selected-agent view
• /: start event filtering
• Esc: clear filter or exit expanded view
• k: send SIGTERM to the selected working agent on Unix
• r: trigger config reload via SIGHUP on Unix

Operational patterns

• Run pearing-work under an external supervisor such as systemd, supervisord, or a container restart policy.
• Use SIGHUP to reload the same config file without interrupting already-running agent work.
• Expect CLI overrides to win over config file values, including across reloads.
• Watch stderr or the TUI for compact status lines like agent state transitions and retry scheduling.