agent_checkin

Agent mesh · macOS · Windows

Effect: write (strongest supported action). Status: gated.

Gated means the tool requires an installed app, a connected account, permission, or runtime availability. Check those requirements on the listed platform before using it.

macOS

Purpose

Announces this agent session to the mesh: its role, the repo it is working on and what it can do. The entry expires after ttl_seconds, so a session that goes quiet leaves the directory instead of looking alive forever; checking in again renews it. agent_inbox delivers only to a session that has checked in, and only what arrives after it did, not the backlog. The first call returns a preview and announces nothing; confirm=true checks in.

Required inputs

agent_id — Stable name for this agent session (e.g. 'builder', 'qa', 'release'). Reuse it across check-ins.

Permissions and confirmation

Explicit confirmation parameter: inspect the schema and tool description before any real call. The documentation example keeps confirm false. Obtain user authorization before performing the action.

Use only the apps, accounts and resources authorized by the user on this platform. Consult this tool's platform-specific description for its connection and permission requirements; this catalog does not assert additional OAuth scopes or OS entitlements.

Full input schema — macOS

{
  "properties": {
    "agent_id": {
      "description": "Stable name for this agent session (e.g. 'builder', 'qa', 'release'). Reuse it across check-ins.",
      "type": "string"
    },
    "caps": {
      "description": "What this agent can do (e.g. ['merge','deploy'])",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "confirm": {
      "description": "Must be true to act. Without it the call returns a preview and changes nothing.",
      "type": "boolean"
    },
    "herdr_pane": {
      "description": "If you are running inside a Herdr-managed pane (check HERDR_ENV=1 first), your own pane id — e.g. $HERDR_PANE_ID. Registers this agent for #2540's automatic wake: when a Mesh message arrives, a fixed local prompt ('[auto-wake #2540] Hay N mensajes de Agent Mesh; llamá agent_inbox') is submitted to this pane via `herdr agent prompt`, so you get a real turn instead of a silent notification. The '[auto-wake #2540]' prefix is what tells you the turn came from the mesh and not from a person typing the same sentence. Never send the value of a remote message here — only your own pane id. Purely local: never sent to the mesh backend. Omit if you are not in Herdr.",
      "type": "string"
    },
    "repo": {
      "description": "Repo you are working on (e.g. 'local-mcp')",
      "type": "string"
    },
    "role": {
      "description": "What you are doing (e.g. 'builder', 'reviewer', 'release')",
      "type": "string"
    },
    "status": {
      "description": "What you are doing RIGHT NOW, one line (e.g. 'porting evernote to Go', 'measuring #1164 on 3674da7e'). agents_list shows it with its age, so peers can tell working from stuck — update it when your task changes.",
      "type": "string"
    },
    "ttl_seconds": {
      "description": "Seconds until this entry goes stale, 60-86400. Omit it and the default comes from `role`: 3600 for an agent that works (builder, reviewer…), 900 for 'ping' and 'verification'. Your presence also renews itself with every mesh call you make, so this is the silence you can afford, not how often you must check in.",
      "type": "integer"
    }
  },
  "required": [
    "agent_id"
  ],
  "type": "object"
}

Documentation example

Do not execute this example. These concrete inputs refer to a fictional demonstration dataset. Resolve real handles and obtain user authorization before any real call.

{
  "agent_id": "demo-reviewer",
  "confirm": false,
  "repo": "demo-project",
  "role": "reviewer",
  "status": "Reviewing the documentation example."
}

Windows