Agent Presence

Agent Presence Skill

Shared protocol for answering: "who is working on this repository right now, what are they doing, and when may another agent take over?"

This skill is deliberately tool-agnostic. Claude Code, Codex CLI, Gemini CLI, and future workers use this as the common contract. Each CLI still needs a thin adapter (see dispatch-watcher-claude, dispatch-watcher-gemini, dispatch-watcher) for loading the skill, posting Slack messages, and wiring shutdown hooks.

Contract

• Input: AGENT_ID, access to the project's dispatch channel

(`), and GitHub access through gh` (read for pre-flight, write for claims/updates).

• Output: a pre-flight status decision before starting work, plus optional

presence/claim updates.

• Durable source of truth: GitHub issue comments, open PRs, branches,

commits, and labels.

• Cache / operator view: pinned Slack roster message. The roster is never a

lock and may be stale.

• Scope: coding agents only. PM automation may reuse the same protocol but

has additional heartbeat/leader-election rules — out of scope here.

Identity

Every agent session must set:

AGENT_ID="---"
# examples:
# codex-lenovo-wsl-1
# claude-mbp-macos-1
# gemini-hpm01-ubuntu-1

environment is one of wsl|windows|ubuntu|macos|cloud. Pick the most specific that uniquely describes the runtime — wsl is preferred over ubuntu when the agent runs inside WSL2.

Treat AGENT_ID as an opaque registry key. Do not infer authorization from the string. If tooling needs display parsing, use:

• first token = model
• last token = sequence number
• second-last token = environment
• all middle tokens joined with - = machine

Required Pre-Flight

Run this before the first dispatch, claim, or substantive work action in a coding task, including before proposing a PR or claiming an issue. Minimal local status reads required by this pre-flight are allowed.

1. Verify local state:

``bash git branch --show-current git status --short `` Do not overwrite unrelated user or peer-agent changes.

1. Read the pinned roster message from ``, if present.

It is a fast cache only.

1. Bind GitHub CLI to the current agent's bot token before every canonical

presence query. Adapters may export GH_TOKEN once or prefix each command, but the shared pre-flight must never depend on the operator's ambient gh auth session: ``bash : "${GH_TOKEN:?Set GH_TOKEN to this agent's bot token before GitHub presence queries}" ``

1. Cross-check GitHub, which is the truth layer. The list commands below are

quick discovery helpers only; ownership decisions must not depend on their capped result set. ```bash GHTOKEN="${GHTOKEN:?}" gh issue list -R / \ --state open \ --limit 200 \ --json number,title,labels,assignees,updatedAt

GHTOKEN="${GHTOKEN:?}" gh pr list -R / \ --state open \ --limit 200 \ --json number,title,headRefName,headRefOid,author,updatedAt,isDraft ```

1. For a concrete dispatch target, always fetch that issue's comments directly

even when labels are missing. For general pre-flight/takeover reconciliation, prefer a GitHub Search path that returns only open issues whose comments contain ` Taking #N - (branch: , PR: )

`task` is one of:

- `quick`: `lease_until = now + 30min` (default for ad-hoc fixes, doc edits)
- `standard`: `lease_until = now + 2h` (typical feature work)
- `long`: `lease_until = now + 4h` (declared upfront with a short reason in
  the visible comment text — for merge supervisor, content batch, large
  refactor)

`branch` and `pr` are the canonical mapping keys for fresh GitHub activity.
Use `none` before branch/PR creation, then PATCH the marker before the first
push or immediately after opening the PR.

Renewal cadence: every `min(TTL/2, 15min)` while executing — refreshes the
GitHub claim AND the roster entry so a healthy agent does not look stale.

**Backwards compatibility (Phase 1 markers):** legacy claim comments without
`lease_until`/`renewed_at`/`task`/`branch`/`pr` are treated as `task: quick`
with synthetic `lease_until = created_at + 4h`, preserving the legacy manual
takeover window, and unknown branch/PR mapping. Adapters that touch a legacy
marker during a renewal MUST upgrade it in place to the full format.

Renew by editing the original comment, not by adding a second claim:

```bash
GH_TOKEN="${GH_TOKEN:?}" gh api -X PATCH \
  "repos///issues/comments/" \
  -f body="$UPDATED_CLAIM_BODY"

Claim race:

1. Post the claim comment.
2. Wait 3 seconds.
3. Re-read all `

Taking over #N from - (branch: , PR: )

Active lease selector:

- Parse both `claim` and `takeover` markers.
- If one or more unexpired takeover markers exist, the first valid takeover
  by `(created_at, id)` is the current owner and supersedes the stale claim
  named via `after:`.
- If no unexpired takeover exists, the first valid active claim by
  `(created_at, id)` is the current owner.
- Expired takeover markers do not block a fresh claim unless there is fresh
  GitHub activity or presence from their holder.

## Adapter Responsibilities

Each CLI adapter must define:

- how the skill is loaded at session start
- how Slack channel and pinned roster are found
- how `start`, `busy`, `ready`, `pause`, `standby`, and `end` are emitted
- whether a shell `trap` / launcher wrapper exists for best-effort `end`
- which GitHub token env var to use (`GH_TOKEN_CODEX_BOT`,
  `GH_TOKEN_CLAUDE_BOT`, `GH_TOKEN_GEMINI_BOT`, etc.)
- how to renew leases during long-running operations
- how to use a launcher wrapper without `exec` when emitting best-effort `end`

Shutdown hooks are best-effort only. They do not catch hard kill, runtime
crash, host power loss, or network loss. Lease expiry plus GitHub activity
checks are the recovery mechanism.

## Stop Conditions

Stop and ask the human or PM agent when:

- two active agents are editing the same non-generated file set
- another active agent is using the same local checkout and your next step
  would switch branches, merge, rebase, commit, regenerate tracked files, or
  clean files
- a lease is expired but there is fresh PR/branch/commit activity
- the task requires overwriting uncommitted changes you did not make
- the roster and GitHub disagree in a way that changes ownership
- secrets, tokens, or private Slack/GitHub identities would need to be exposed

## Shared Library

The shared shell library lives at `scripts/agent-presence-helpers.sh`. Adapters
source it once at startup and delegate all shared logic (`pre_flight_check`,
`claim_issue`, `renew_lease`, `emit_presence`, `update_roster_chat_update`).
Required env vars and defaults are documented in the script header.

## Placeholders

This skill references these placeholders (defined in
`.agent/context/project-ids.md`):

- `/` — GitHub repository
- `` — Slack channel name (e.g. `#agent-dispatch`)
- `` — Slack channel ID (e.g. `C0B25SWSUKS`)
- `` — pinned roster message timestamp

## References

- Per-CLI adapters: `dispatch-watcher-claude`, `dispatch-watcher-gemini`,
  `dispatch-watcher` (Codex)
- Shared library: `scripts/agent-presence-helpers.sh`

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ZroZoom](https://github.com/ZroZoom)
- **Source:** [ZroZoom/agent-skills-core](https://github.com/ZroZoom/agent-skills-core)
- **License:** MIT

Install and usage instructions live in the source repository linked above.