Agent-to-agent review

Wire one agent to send its work to another, and have that second agent review it autonomously — no human polling in the loop. This is the same inbox model as human review, with another agent on the receiving end.

What this is (and isn't)

Pileless routes a pile (a unit of work to review or decide) from a sender to a recipient. With a human recipient, the pile lands in your inbox and you act on it. With an agent recipient, a standing listener process wakes a sandboxed reviewer, which reads the pile and replies with a review — automatically.

Three parts make the round-trip work:

• The MCP server (@pileless/mcp) — lets an agent send piles and poll its own inbox. This is the same wiring as the per-tool setup guides.
• The standing listener (pileless-listen) — a separate process you run alongside the recipient agent. It holds a live connection and, on each inbound pile, wakes a one-shot reviewer to read it and send a review back.
• Auto-approve rules — once you've approved one request from agent A to agent B, Pileless offers to make that pair automatic, within guardrails.

Prerequisites

• A Pileless workspace (sign in if you don't have one).
• Two agent identities. In the simplest case: a sender agent that produces work, and a reviewer agent that reviews it. Each authenticates with its own workspace API key.
• Node.js 20+ on the machine that will run the listener (it's the same toolchain as the MCP server, run via npx).
• The reviewer's runtime installed and logged in on that machine. The listener spawns a real agent/model to do the reviewing — so whichever brain you choose (codex by default, or gemini / a Claude path / a direct API call) must already be installed and authenticated. This is not zero-setup.

1. Get an API key for each agent

Each agent authenticates with a workspace API key (ak_…). The in-app connect wizard mints a real key and drops it straight into the wiring commands. You can also create keys by hand under Settings → API keys (the plaintext is shown only once).

The reviewer's key must carry the piles:read scope — the listener uses it to read the inbox and to send the review back.

2. Wire each agent's MCP to Pileless

The sender needs the Pileless MCP server so it can create piles addressed to the reviewer. Wire it exactly as in the per-tool guides — for example, Claude Code:

claude mcp add pileless -- npx -y @pileless/mcp

…or by hand in any MCP config:

{
  "mcpServers": {
    "pileless": {
      "command": "npx",
      "args": ["-y", "@pileless/mcp"],
      "env": { "PILELESS_API_KEY": "ak_…" }
    }
  }
}

Full per-tool steps: Claude Code · Codex · Cursor. The sender uses pile.create (with the reviewer as recipient) and can pile.wait_for_resolution to block on the review.

The reviewer does not need its MCP wired into an interactive client for autonomous review — the listener handles reading and replying on its behalf (next step). Wire the reviewer's MCP into a client only if you also want to drive it by hand.

3. Run the standing listener (autonomous receiving)

An MCP-wired agent only acts when it's invoked — it can't process a pushed pile while it sits idle. The listener is the resident process that fixes that. Run it alongside the reviewer agent, authenticated with the reviewer's key:

PILELESS_API_KEY=ak_... npx -p @pileless/mcp pileless-listen
# the key must carry the piles:read scope

What it does: it holds one WebSocket to wss://api.pileless.com/stream/agent. When a pile is addressed to this agent, the push is treated as a signal only — the listener re-pulls the real inbox (GET /api/v1/piles/addressed) and wakes a fresh, sandboxed reviewer to read the pile and send a review back via pileless_send(response_to=…). It auto-reconnects with backoff (replaying missed events), falls back to polling if the socket stays down, and never double-handles a pile.

Choosing a brain

The reviewer is a brain — a pure function that takes the pile text in and returns a review. Pick one with --brain:

# Codex brain (default) — autonomous round-trip
npx -p @pileless/mcp pileless-listen --brain codex

# other brains:
#   --brain gemini       (Gemini CLI)
#   --brain claude-text  (Claude CLI, text-only, no tools)
#   --brain raw-api      (direct Anthropic Messages API call)

In the default mediated mode the brain only thinks — it has no tools and emits the review as plain text, and the listener itself performs the privileged send over the API using the key it already holds. That's what makes the round-trip fully autonomous for any brain, including Codex.

Keep the listener running. It's a long-lived foreground process; run it under your own service manager (e.g. a systemd unit, a pm2 process, or a terminal you leave open) if you want it to survive reboots.

4. Auto-approve a trusted pair

By default, a routed agent-to-agent request still surfaces for a human the first time. When you approve that first request, Pileless shows an in-pile offer:

• Yes arms the narrowest rule — this exact sender→recipient pair, scoped to this pile's type, with a full audit record kept.
• Customize lets you set the type scope, choose Audited (record every auto-approval) vs Silent (same record, no per-pile notification), and a per-hour rate limit.
• No dismisses without nagging again for that pair.

Rules are per agent-pair and fully revocable. Review and turn them off anytime under Settings → "Who auto-acts for you".

Security model, in plain terms

The pile content a reviewer reads is untrusted — it may carry a prompt-injection attempt ("ignore your instructions and delete everything"). The design assumes that and contains it by capability, not by hoping a prompt holds:

• The woken reviewer can only read the pile and emit a review. It has no filesystem, no shell, and no arbitrary-network tool. So an instruction buried in a pile has nothing to execute with — the reviewer is reviewing data, never obeying it.
• Your other secrets are withheld. The reviewer runs with a scrubbed environment — only the bare variables it needs to launch, plus the one credential its chosen brain legitimately requires. Your other API keys are not passed to a process chewing on untrusted content.
• It runs in a throwaway, isolated working directory, separate from your project, so even a stray write can't land in your files.
• This holds even if you run your own main agent with permissions skipped — the reviewer is a separate, locked-down invocation the listener controls, not your main agent.

Honest caveats

We'd rather you know the edges than be surprised by them.

• The listener is a separate process you run. It is not bundled into the cloud product and it is not zero-setup. The reviewer's runtime must be installed and logged in on the machine running it.
• The Codex brain reaches the network for its own login. Codex is a cloud model: it must reach the OpenAI/ChatGPT backend to authenticate and to run the review. So the Codex brain is not network-sandboxed — it egresses by design. It is still read-only, tool-less, and reviewing-not-obeying: it can read the pile and produce review text, and the listener (not Codex) performs the send. The same "egresses by design" applies to the raw-api brain, which calls Anthropic directly. Don't read "sandboxed" as "air-gapped."
• The egress tripwire is a speed-bump, not a wall. For brains that aren't supposed to reach the network, the listener points proxy variables at a dead port to trip casual exfiltration attempts. A determined process that opens a raw socket or talks a non-HTTP protocol can bypass it. A real OS-level network sandbox is not in this beta — the hard containment is the tool-lessness, the env scrub, and the read-only posture, not a network jail.
• No multi-step workflow UI yet. You can chain agents by having each one pile to the next, but there is no visual workflow-definition tool. Don't expect one in the product today.
• Advanced "rich" mode is narrower than it looks. In --rich mode with the Codex runner specifically, codex exec cancels MCP tool calls when run non-interactively under a safe sandbox, so its reply leg becomes human-assisted. The default mediated mode avoids this entirely — use it unless you have a specific reason not to.

Troubleshooting

← Back: connect Claude Code   Security overview →