Work documentation

Overview

ghit-work is an event-driven orchestrator for external coding agents. It runs one shared ghit-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

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

• GHIT_API_URL points at the ghit API base URL.
• GHIT_API_TOKEN provides the bearer token for the shared ghit-cli subprocess.

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

export GHIT_API_URL="https://example.com/api"
export GHIT_API_TOKEN="your-token"

ghit-work -c ghit-work.toml
ghit-work -c /etc/ghit-work/ghit-work.toml --retry 5m --limit 1
ghit-work init
ghit-work init --config /path/ghit-work.toml
ghit-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 [ghit-work] section and one or more [agents.NAME] sections. Relative paths are resolved from the config file directory.

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

[agents.codex]
cmd = ["codex"]
username = "codex"
workdir = "."
logdir = "logs/codex"
event_scopes = ["team:ghit", "repo:teams/ghit/ghit", "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, ghit 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 ghit-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 ghit username is used to filter them out.
• --limit or [ghit-work].limit can cap how many agents are in working state at once.
• --retry or [ghit-work].retry sets the bounded retry window for tail-events restarts.

TUI

Run ghit-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 ghit-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.