claude-presence

1. Install the package globally

git clone https://github.com/garniergeorges/claude-presence cd claude-presence && npm install && npm run build && npm link

2. Install the slash commands for every Claude Code session

cp commands/*.md ~/.claude/commands/

Install

Install the slash commands (recommended)

cp commands/*.md ~/.claude/commands/

Now in any Claude Code session, you can type /register, /presence, /claim <resource>, /release <resource>, /broadcast <message>, /inbox.

Quick start (60 seconds)

```bash

Example workflow

Session A starts work on feat/login:

/register fixing the login redirect bug

Session A is about to push and trigger CI:

/claim ci pushing feat/login
→ ok: true, held until 10:05

Meanwhile, session B on fix/nav tries the same:

/claim ci pushing fix/nav
→ ok: false — already held by session-a1b2 on feat/login since 09:55
   Want to wait, broadcast, or abort?

Session A finishes CI and releases:

/release ci

Session B can now proceed.

Configure

Add claude-presence to your project's .mcp.json:

{
  "mcpServers": {
    "claude-presence": {
      "type": "stdio",
      "command": "claude-presence-mcp"
    }
  }
}

If you already have other MCP servers, just add this block alongside them — don't replace the whole file. Example with an existing semgrep entry:

{
  "mcpServers": {
    "semgrep": {
      "type": "stdio",
      "command": "semgrep",
      "args": ["mcp"]
    },
    "claude-presence": {
      "type": "stdio",
      "command": "claude-presence-mcp"
    }
  }
}

Hooks (optional)

The slash commands cover 99% of daily use. Hooks are optional polish for the last 1%:

• hooks/session-start.sh runs when you open a new Claude Code session. It prints a short reminder so you remember to /register and think about resource locks before shared ops. It does not auto-register the session (by design — the slash command keeps it explicit).
• hooks/user-prompt-submit.sh runs on every user prompt. It emits two things when something is pending on this project:
• a systemMessage shown visibly above the model's reply (🔔 claude-presence: N unread message(s) — see below), so the user can't miss it;
• an additionalContext payload passed silently to the model with the full unread inbox (DMs + broadcasts, all priorities) + presence/locks summary, so the model can answer accurately if you ask "what notifications do I have?".

Messages are read in peek mode — they stay unread for /inbox.

The UserPromptSubmit hook shells out to the claude-presence CLI, so it must be on your PATH (handled by npm link or npm install -g). If the CLI is missing, the hook silently exits 0 — no breakage.

The CLI and MCP binaries must be on PATH:

which claude-presence # → /opt/homebrew/bin/claude-presence (or similar) which claude-presence-mcp # → same dir

The CLI runs:

claude-presence status # → "No active sessions." on first run ```

Inside Claude Code, type /mcp. You should see claude-presence listed with 9 tools. If it's missing, see Troubleshooting.

Then try /register test — the session should register and the tool reply should list any other active sessions on this project.

How it compares

Pick claude-presence if you want something small and focused on "don't let my sessions step on each other". Pick mcp_agent_mail if you want rich agent-to-agent workflows.

Troubleshooting

/mcp doesn't list claude-presence. Make sure .mcp.json is at the project root (same directory as Claude Code was opened in), the command field matches an executable on PATH, and you fully restarted Claude Code after editing the file (not just reloaded).

command not found: claude-presence-mcp. Run which claude-presence-mcp. If empty, run npm link again from the claude-presence/ directory. If you installed via npm install -g, check that your npm global bin directory is on PATH (npm config get prefix).

The slash commands don't appear. Slash commands are loaded at session start. Restart Claude Code after cp commands/*.md ~/.claude/commands/. Type / to see the list.

claude-presence status shows 0 sessions even though Claude Code is open. claude-presence doesn't auto-register — you must call /register once per session. This is deliberate: sessions stay explicit and identifiable.

A lock is stuck because a session crashed. Sessions with no heartbeat are pruned after 24 hours. You can force-clean immediately with claude-presence clear, or force-release a specific lock with the resource_release MCP tool passing force: true.

Hooks seem to break my existing GitKraken / custom hook setup. See Merging with existing hooks. Each event holds an array of hooks; add yours without removing others.