# Agent Presence

> Shared multi-agent presence and claim protocol. Use before any coding agent starts work in this repo, when coordinating Claude/Codex/Gemini sessions, or when checking who is already working on the repository. Triggers: agent session start, check agent presence, agent coordination, who's working on repo.

- **Type:** Skill
- **Install:** `agentstack add skill-zrozoom-agent-skills-core-agent-presence`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ZroZoom](https://agentstack.voostack.com/s/zrozoom)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ZroZoom](https://github.com/ZroZoom)
- **Source:** https://github.com/ZroZoom/agent-skills-core/tree/main/.agent/skills/agent-presence

## Install

```sh
agentstack add skill-zrozoom-agent-skills-core-agent-presence
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```bash
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.

2. Read the pinned roster message from ``, if present.
   It is a fast cache only.

3. 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}"
   ```

4. 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
   GH_TOKEN="${GH_TOKEN:?}" gh issue list -R / \
     --state open \
     --limit 200 \
     --json number,title,labels,assignees,updatedAt

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

5. 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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-zrozoom-agent-skills-core-agent-presence
- Seller: https://agentstack.voostack.com/s/zrozoom
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.