coding-agent-work-loop

name

coding-agent-work-loop

description

GitHub label-driven workflow that lets a local AI handle issues / PRs; the daemon listens for `pending/agent` and dispatches work. Every issue's design proposal / discussion / code / Claude conversation / tmux history is filed under the issue number, so you can find or resume any of it later just by knowing the issue number. Commands include setup (deploy to a project), status (check daemon state), disable (turn off a project's daemon)

coding-agent-work-loop

English · 中文

Turn GitHub issue / PR comments into the input and output of your local AI. A systemd timer + a few shell scripts + two GitHub labels let you talk to the AI directly through the GitHub web UI (or the iOS gh app).

This skill is agent-agnostic by design. Worker CLI is selected by WORKER_AGENT=<name> in coding-agent.config; the daemon / dispatch scripts go through a thin driver layer that plugs in different agent CLIs. Built-in drivers: claude (default, Claude Code), opencode (sst/opencode), codex (OpenAI Codex CLI), cursor (Cursor Agent CLI). Add your own via scripts/drivers/<name>.sh — see docs/drivers.md.

When to invoke

The user calls this skill from the host agent runtime via /coding-agent-work-loop <command> or a natural-language request. Common forms:

• "Install this daemon on project X" → run the setup flow
• "What's the state of the coding agent?" → run the status flow
• "Disable the coding agent on project X" → run the disable flow

What you (the agent) should do when invoked

setup (deploy to a host project)

The user gives you a host project path (e.g. ~/github/myproject). Steps:

1. Verify the path exists and is a git repo (has .git)
2. Check deps: git, gh (must be logged in via gh auth login), tmux, jq, flock, systemctl, plus the worker CLI selected by WORKER_AGENT (default claude; other built-ins: opencode, codex, cursor). Each must resolve via command -v.
3. Run:

   bash "${CLAUDE_PLUGIN_ROOT:-$HOME/.agents/skills/coding-agent-work-loop}/setup.sh" <host-project-path>
   

   $CLAUDE_PLUGIN_ROOT is the skill-root env Claude Code injects; if absent, fall back to the canonical ~/.agents/skills/coding-agent-work-loop.
4. setup.sh prints next-step guidance when done — relay it to the user verbatim.

status

User wants the state. Steps:

1. systemctl --user list-timers 'coding-agent-poll@*' --no-pager — timer health
2. systemctl --user list-units 'coding-agent-poll@*.service' --no-pager — last execution
3. For each registered ~/.config/coding-agent-work-loop/*.conf:
   • tail -20 $STATE_DIR/poll.log (read STATE_DIR from the conf)
   • gh issue list --repo $REPO --label pending/agent + gh pr list --repo $REPO --label pending/agent
4. Summarize for the user

cleanup (after a PR is accepted / rejected)

User merged a PR or wants to abort work on an issue. Steps:

1. Confirm the issue is finished (PR merged or closed)
2. Run:

   bash "$CLAUDE_PLUGIN_ROOT/scripts/cleanup-issue.sh" <issue-number>
   

   Optional flags: --force (clean even if the worker is busy), --keep-worktree (only kill the session), --delete-branch (also drop the local branch)

What cleanup-issue.sh does:

• Busy check (refuses by default unless --force)
• Runs the project-level CLEANUP_HOOK (configured in coding-agent.config, e.g. tear down tailscale ports, stop dev server)
• Kills the worker's tmux session
• Removes the worktree (default)
• Optionally removes the local branch

disable

User wants to stop one project. Steps:

1. Confirm the instance name (systemctl --user list-timers 'coding-agent-poll@*')
2. systemctl --user disable --now coding-agent-poll@<key>.timer
3. Optional: remove the ~/.config/systemd/user/coding-agent-poll@<key>.{service,timer} instance symlinks (leave the actual template alone)
4. Optional: remove ~/.config/coding-agent-work-loop/<key>.conf
5. Report back

What does NOT land in the host project

After setup, the host project's worktree gains only two things:

1. One .gitignore line (excluding coding-agent.config)
2. A coding-agent.config (gitignored, config)

Scripts, systemd units, state, logs all live outside the host project (skill dir + ~/.config/ + ~/.local/state/).

Full architecture

See sibling README.md.

File listing

• setup.sh — bootstrap a host project
• scripts/ — daemon + dispatch scripts (never copied to host project)
• prompts/ — initial worker prompt templates (override via host project's .agents/skills/coding-agent-work-loop/prompts/)
• systemd/ — coding-agent-poll@.service/.timer template units; setup copies them to ~/.config/systemd/user/
• coding-agent.config.example — config template