All tools

agents_list

Agent mesh · macOS · Windows

Effect: read (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

Lists the agents currently working across ALL the user's machines in the mesh — which machine each is on, its role, repo, capabilities, its `status` (what it is doing RIGHT NOW, with `status_age_s` = how many seconds that text has been unchanged), `last_activity_at` (the last time it called the mesh at all) and `expires_at` (when it drops off this list if it stays silent). Use `status` + `last_activity_at` to tell a working peer from a stuck one before deciding who to interact with. Use it before starting heavy work (a release, a wide refactor, a deploy) to see who else is active and warn them with agent_send, and to get the `handle` you address a message to. `alive` means "called the mesh within its own ttl_seconds" — any call counts, not just agent_checkin — NOT "is reachable now": an agent that stopped (or whose machine turned the mesh off) still reads alive until its entry expires. A message sent in that window is accepted and stored, and simply never read. If a peer does not answer, re-run this before concluding anything — its entry may have expired since.

Required inputs

No required inputs are declared in this platform's schema. Optional selectors and runtime requirements may still apply.

Permissions and confirmation

No explicit confirmation parameter is exposed in this snapshot. This does not grant permission to act: obtain user authorization before any real action.

Full input schema — macOS
{
  "properties": {
    "agent_id": {
      "description": "Your own agent_id. Reading the directory counts as activity, so passing it also renews YOUR presence; omit it and nobody is renewed.",
      "type": "string"
    },
    "include_stale": {
      "description": "Also list agents whose entry expired (default false)",
      "type": "boolean"
    }
  },
  "required": [],
  "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.

{}

Windows

Purpose

Lists the agents currently working across ALL the user's machines in the mesh — which machine each is on, its role, repo and capabilities. Use it before starting heavy work (a release, a wide refactor, a deploy) to see who else is active and warn them with agent_send, and to get the `handle` you address a message to. `alive` means "called the mesh within its own ttl_seconds" — any call counts, not just agent_checkin — NOT "is reachable now": an agent that stopped (or whose machine turned the mesh off) still reads alive until its entry expires. A message sent in that window is accepted and stored, and simply never read. If a peer does not answer, re-run this before concluding anything — its entry may have expired since.

Required inputs

No required inputs are declared in this platform's schema. Optional selectors and runtime requirements may still apply.

Permissions and confirmation

No explicit confirmation parameter is exposed in this snapshot. This does not grant permission to act: obtain user authorization before any real action.

Full input schema — Windows
{
  "properties": {
    "agent_id": {
      "description": "Your own agent_id. Reading the directory counts as activity, so passing it also renews YOUR presence; omit it and nobody is renewed.",
      "type": "string"
    },
    "include_stale": {
      "description": "Also list agents whose entry expired (default false)",
      "type": "boolean"
    }
  },
  "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.

{}