Lasso

lasso

Start here for lasso itself. Use the lasso MCP server to inspect and manage lasso agents, hosts, repos, and branches.

Reach for these purpose-built tools before falling back to the lasso.db sqlite file, the filesystem, or generic shell tooling — those are last resorts, not the front door.

Tool	What it does
list_agents	List lasso agents
get_agent	Fetch one agent's record/metadata
read_agent	Read an agent's terminal output / transcript
wait_agent	Block until an agent reaches a state (e.g. idle/done)
create_agent	Spawn a new first-class lasso agent
close_agent	Shut an agent down
list_hosts	List hosts lasso knows about
list_repos	List repos available to spawn agents into
list_branches	List branches for a repo
whoami	Resolve your own agent record
notify	Push a notification to the human running lasso

The rest of this skill covers the common self-identity case; everything above applies to acting on other agents too.

lasso self-identity

If you were spawned by lasso, you are running inside a herdr pane that lasso created, and your own identity is already in your environment. You do not need to call list_repos / list_agents and guess which entry is you — that wastes tokens. Read your pane id from the env instead.

Your environment variable

Check whether you're a lasso agent at all by testing HERDR_PANE_ID:

echo "$HERDR_PANE_ID"   # empty/unset => you are NOT in a lasso-managed herdr pane

Closing yourself when you're done

The easiest way to shut yourself down is the CLI — it reads $HERDR_PANE_ID for you, so there's nothing to pass:

lasso closeme

That tells the running lasso server to kill your agent process and close your pane (the same soft-close the UI and the close_agent MCP tool perform). This works even when you were spawned by a lasso on a different machine: the local server finds the owning record on its peer and closes your pane locally. If the server runs on a non-default port, set LASSO_LISTEN=host:port — it must stay an address of the machine you run on.

Acting on yourself via the lasso MCP tools

The lasso MCP server runs inside lasso's own process, not your shell, so it cannot read your environment — you must pass $HERDR_PANE_ID yourself.

• whoami — pass $HERDR_PANE_ID as pane_id to get your own agent record, including your agent id and the host your pane lives on. Pane ids are only unique per host, so if the same pane id exists on several hosts, whoami refuses to guess (found:false) and names the candidate hosts — call it again with host set to the machine you actually run on (compare hostname against the labels from list_hosts).
• close_agent — call with the id and host whoami returned to shut yourself down (the long-hand of lasso closeme). Never guess the host: passing the wrong one (or another agent's id) kills an unrelated agent.

If $HERDR_PANE_ID is empty, you are not running under lasso and none of this applies to you.

Broadcasting what you're working on

Your pane has a status card in the herdr sidebar and lasso's ⌘K pane switcher. You can put a live one-line summary on it so the human can see what you're doing without opening your terminal:

herdr pane report-metadata "$HERDR_PANE_ID" --source agent:self \
  --token summary="migrating auth tests to vitest" --ttl-ms 1800000

Update it when you change phases (exploring → implementing → testing); the TTL clears it automatically if you go quiet. Keep it under ~60 characters.

Do not use herdr pane report-agent — that claims lifecycle authority over your pane, overriding herdr's own idle/working/blocked detection, and a stale claim sticks if you exit uncleanly. report-metadata is display-only and fails safe.

Getting your human's attention

A status card only helps if someone is looking at a screen. When you actually need the human — a decision only they can make, a question that blocks you, a long job finishing while they're away — push them a notification:

lasso notify "vitest is green across all 3 packages — want me to open the PR?"

It reaches their phone with the screen off (lasso as an iOS home-screen app), so treat it as a real interruption:

• Only when you need them. An agent that pings on every step trains its human to ignore every ping. Blocking on an approval needs no notification at all — lasso already watches for that and notifies on its own.
• Say what you need, not that you need something. It's read on a lock screen: "the migration drops 2 columns — safe to run on prod?", not "please check lasso".
• Check the outcome. The command exits non-zero and prints why when no device is registered — nothing was delivered, so don't tell your human you notified them. (Same signal in the MCP tool's sent field.)
• The notification is titled with your agent name and opens on your host, resolved from $HERDR_PANE_ID (the CLI reads it for you). -title overrides it; a piped message works too: make test 2>&1 | tail -3 | lasso notify.

The notify MCP tool is the same call — pass message and your $HERDR_PANE_ID as pane_id. Use the CLI unless you're already in an MCP round trip; use the tool when you want the structured sent / transports reply.

Using the rest of the herdr CLI

herdr ships its own agent skill (npx skills add herdrdev/herdr --skill herdr) covering pane orchestration — splitting panes, starting sibling agents with herdr agent start / prompt / wait, and running commands with herdr pane run / wait-output. Those all work from inside a lasso pane too (you are in a herdr session; HERDR_ENV=1 is set). Two lasso-specific rules on top of it:

• Never herdr pane close yourself or any pane lasso created. lasso closeme (or the close_agent MCP tool) is the only sanctioned way to shut yourself down — it also cleans up lasso's agent record and staged prompt files, which a raw pane close leaves behind.
• Panes and agents you spawn directly via herdr are invisible to lasso's agent list (no record, no repo/branch, no close tracking). Prefer lasso's create_agent MCP tool when the new agent should show up as a first-class lasso agent; use raw herdr panes only for short-lived helpers.

Inspecting and managing lasso agents

Use the lasso MCP tools to inspect agent state and manage agent lifecycles:

• List: list_agents (who's running), list_hosts / list_repos / list_branches (where they can run), get_agent (one agent's record).
• Inspect: read_agent to read another agent's terminal output/transcript.
• Wait for state: wait_agent to block until an agent reaches a state (e.g. idle/done).
• Manage: create_agent to spawn a first-class lasso agent, close_agent to shut one down.

These are the canonical, purpose-built path. Only drop to reading lasso.db directly or shelling out when a tool genuinely can't express what you need.

Scope: which agents you can actually see

Your view of the fleet may be bounded by the credential you authenticate with — not by what exists. What to expect:

• list_hosts / list_agents return only the hosts your credential may address: your own host, plus any hosts the operator grouped yours with. An empty-ish listing is usually containment working as intended, not an outage.
• The host argument of every tool defaults to your own host — the one your credential was issued for — not to the machine lasso runs on.
• Direction matters. Another caller may be able to inspect your host while you cannot inspect theirs. Don't infer reciprocal access from your own credential's reach.
• A refusal like "this credential may not address host …" is a policy boundary, not a transient error. Do not retry, work around it via ssh, or read lasso.db to peek past it. If you genuinely need the reach, tell the human — widening is an operator action (lasso mcp-group / lasso mcp-client), never something you can do from your side.
• Group membership can change live: reach you lacked a moment ago may appear on your next call without any reconnect.