Harlan GitHub Agent

Use the installed CLI to inspect and control the durable Service. Keep scheduling in the Service.

Connect

Context sync installs the CLI for noninteractive shells on both hosts. Run pnpm sync:context locally and pnpm sync:context:hogwild for Hogwild. Service updates also install it.

Desktop:

harlan-github-agent control status

Hogwild from desktop:

hw run agent 'harlan-github-agent control status'

The launcher resolves the Service checkout and its pinned Node runtime. It uses ~/.config/harlan-github-agent/config.yml by default. It reads dashboard-password beside that file. Desktop reads ~/.config/harlan-github-agent/control-url. Context sync creates it with the Hogwild URL if missing. It preserves an existing target. Hogwild uses http://127.0.0.1:3210. Explicit --config, --url, and --password-file arguments win. A desktop --config override reads that file's Service URL unless --url is also set. Use HARLAN_GITHUB_AGENT_URL to override the installed desktop target. Never print credentials or place their values in saved commands.

If the launcher is missing, use this source command once:

ssh hogwild 'cd ~/.local/share/harlan-github-agent/service && ~/.local/lib/harlan-github-agent/node --experimental-strip-types packages/harlan-github-agent/src/cli.ts control status --config ~/.config/harlan-github-agent/config.yml --url http://127.0.0.1:3210'

Then restore the launcher through context sync. Do not guess a built CLI path inside dist/. Installed Plugin caches contain Skills, rather than the Service package. The Service checkout lives at ~/.local/share/harlan-github-agent/service. Use HARLAN_GITHUB_AGENT_CHECKOUT for an explicit checkout override.

Read Service state

harlan-github-agent control tasks
harlan-github-agent control incidents
harlan-github-agent control activity --task TASK_ID
harlan-github-agent control events --limit 50
harlan-github-agent control reviews --repository OWNER/REPOSITORY --number NUMBER
harlan-github-agent control reviews --repository OWNER/REPOSITORY --number NUMBER --head FULL_HEAD_SHA

Commands print one JSON value. Tagged errors exit with status 1. status returns { health, state }. tasks, incidents, and activity use focused Service reads. activity returns redacted live activity for a Running or Publishing Task. Other known Task states return TaskActivityUnavailable, including the current state. Only an unknown Task returns TaskNotFound. Use reviews for stored Review findings after a Task completes. reviews returns { runs }, preserving findings and gates. The head filter requires all 40 characters. An empty runs array means no stored Review matches that query. It does not mean Review passed.

Use watch-pr to wait through authenticated Service events.

harlan-github-agent control watch-pr --repository OWNER/REPOSITORY --number NUMBER --until review --timeout-seconds 600

Use --until merged to wait through actionable findings. The default stops for attention after Service Tasks stop owning the head. Changed states go to stderr. Terminal state goes to stdout. Reconnect with the same command after a Service restart. Follow pull request watching for submission completion.

Control the Service

Use pause, resume, restart, update, or cancel --task TASK_ID for the matching durable control. Use routine-run --routine OWNER/REPOSITORY:NAME to open a run ahead of its cron. Use stop-review --repository OWNER/REPOSITORY --number NUMBER --head HEAD_SHA to stop that exact Review.

After configuration changes, use a durable Restart request. It lets active Agents and controller writes finish before systemd starts the next process. Never use Pause or raw unit restart to coordinate a routine restart. For paired Service updates, run pnpm service:hogwild:update. The helper holds one local lock through the desktop update. Another update or restart on that host fails before it reaches the Service. During drain, the helper reports active Tasks, occupied Agent slots, and elapsed seconds. It names each active Task, its repository, issue or pull request, state, and available progress label. It reports changed counts and a heartbeat every 30 seconds. It also reports changed Task details when counts stay equal. After desktop restart, it requires a fresh report with the current protocol. If that check fails, inspect the desktop unit and Service connection. Its durable Update blocks new Tasks before file sync. The helper marks preparation Ready after sync, then waits for existing work. Failed preparation releases its hold without changing manual Pause. If the Service lacks preparation support, use its installed desktop helper first: bash ~/.local/share/harlan-github-agent/service/scripts/hogwild-service.sh update. After that upgrade, use the current repository helper. Use reload-external-watches only for external watches and their issue cutoff. Other configuration changes require Restart.

Call the Control API directly only when no matching CLI subcommand exists. Its Basic-auth username is agent. Read API response contracts before extracting fields. For the Review endpoint, the array lives at .runs.

Share NuxtSEO credentials with Routines

SEO and vitals workers need a NuxtSEO token inside their sandbox. This includes Issue work whose Published Routine provenance identifies seo-review or vitals-review. Host CLI login alone does not authenticate workers. Repository environment files remain supported.

To share an existing read-only token, configure each worker host separately. Write ~/.config/harlan-github-agent/nuxtseo-worker.json with an explicit repository list:

{
  "environmentFile": "/absolute/path/to/existing/private.env",
  "repositories": ["owner/site"]
}

The existing environment file must contain NUXTSEO_TOKEN. Use a viewer token with read scopes and optional feedback:write. Keep the token in its existing private file. Never copy its value into commands, reports, or repository files. Both files must belong to the worker account and use mode 600. Use canonical paths without symbolic links.

Only listed repositories receive the token for seo-review, vitals-review, or Issue work with their verified Published provenance. The controller derives routineContext from its Published issue records, never issue text or labels. The context repository must match the Worktree origin. Review Tasks, other Routines, unrelated Issue work, and attached OpenCode clients receive no shared token. Workers receive only NUXTSEO_TOKEN, rather than either source file or other environment values. Missing configuration preserves repository credentials. Invalid configuration stops the matching Routine with an error.

Authority and deeper contracts

Read Hogwild before host work. For daily check-ins, use daily-checkin. For Codex or OpenCode session audits, use agent-retro.

Read the controller contract before changing Service policy, dispatch, configuration, or publication. It owns repository eligibility, Approval, Review, Repair, releases, and conflict resolution.

Workers may edit only their assigned worktrees when authorized. Workers never change GitHub state or Service-owned SQLite data. The Controller owns credentials and every GitHub write. Never approve a pull request. Keep primary checkouts read only.

Report Service state, active subjects, active Tasks, and exact blockers. Claim work started only when the Journal records it.

/harlan-github-agent

SKILL.md