# Agent Bridge

> Delegate real coding work to a peer AI agent (such as Claude Code, Codex (ChatGPT), or Gemini (Antigravity)) that runs its own full harness, or use that peer as an independent reviewer, adversarial red-team, ideation & planning partner. Trigger when the user says "use agent bridge", "ask <another agent>", "delegate to <agent>", "have <agent> implement/build/fix this", "get <agent> to review/critique", "get a second opinion", or otherwise hands work to a different agent than the one they're talking to. The bridge auto-detects which agent you are and offers the others as peers, so the same instructions work whichever agent you are running inside. Do NOT trigger for normal work the user wants you to do yourself.

- Skill: `kununu/agent-bridge` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add kununu/agent-bridge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kununu/agent-bridge/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: kununu (https://skillmd.com/u/kununu)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kununu/agent-bridge

---


# agent-bridge — delegate to a peer coding agent

You are the lead engineer. Through the bridge you can hand self-contained work to a **peer
coding agent** — another full agent (e.g. Claude Code or Codex) running its own harness in
auto mode, so it can take real, meaty work and run it to completion: building, testing, and
verifying its own output before reporting back.

The bridge **auto-detects which agent you are** and which peers you can call — you never
delegate to yourself, and the same skill works whichever agent is driving.

## Who can I call?

```
bash "$HOME/.agents/skills/agent-bridge/scripts/bridge.sh" agents
```

Lists the peers available on this machine (everyone except you). Pick one as `<peer>` in the
commands below. For a specific peer's quirks, read `references/<peer>.md` in this skill.

Naming exception to keep in mind: **"Gemini" means peer `agy`** — Google renamed the Gemini
CLI's successor to the Antigravity CLI, so *"ask Gemini"* (or *"Antigravity"*) targets `agy`.

## How to delegate

Run this from the **project root** (where you're already working):

```
bash "$HOME/.agents/skills/agent-bridge/scripts/bridge.sh" <peer> "your task for the peer"
```

- It **streams the peer's reasoning and actions live** — read it as it runs.
- Each run's full transcript is saved under that peer's `logs/`. State lives in a global store
  at `~/.agent-bridge/projects/<project>/<you>/<chat>/<peer>/<thread>/`; you don't manage any
  of it. The thread defaults to `main` — you only name threads when running peers in parallel
  (see **Parallel delegations** below).
- If the peer gets confused, or the user asks to start fresh, reset and retry — see
  **Starting a peer over** below.

**Long tasks, or any task containing `$`, backticks or quotes: write it to a file and pass
`--task-file` instead of an argv.** The argv goes through your shell first, so a literal
`$12B` in a prompt becomes `2B` and the peer works from a corrupted brief. `-`
reads stdin. It solves mangling, not size — past ~120KB the bridge refuses (the task still
travels as argv to the peer); tell the peer to read the file itself instead.

```
bash "$HOME/.agents/skills/agent-bridge/scripts/bridge.sh" <peer> --task-file brief.md
```

Read **Gotchas** below before your first run — most "it looks stuck" moments are the peer thinking.

## Gotchas

- **Thinking looks like hanging — it isn't.** Before its first action, and between actions, a
  peer often reasons for one to a few minutes. Some peers emit `· thinking… ~Nk tokens`
  heartbeats with a climbing count; others show steady `· exec:` / `· tool:` action lines.
  That is the peer working. **Do not interrupt, kill, or restart it while output is flowing** —
  step in only if the stream goes fully silent for a long stretch.
- **The peer's final answer comes after the `── <peer> done ──` marker.** Everything before it
  is live reasoning and actions; read the stream, but treat the post-marker text as the answer.
  One thing can follow the answer: an `── <peer> artifacts ──` list, when the peer wrote files
  into its own private session directory instead of the repo (agy's generated images do this).
  Those paths are real files — copy what you want to keep into the project.
- **A peer's report on its own output is a claim, not a result.** Verify with your own tools
  before relaying it; peers do state that every constraint was met when it wasn't.
- **Sessions persist per conversation, per peer, per thread.** A new chat starts a fresh peer
  session; within this chat, every call to the same peer (on the same thread — `main` unless
  you name one) continues the same one. Write follow-ups as continuations ("the parser you
  wrote drops trailing numbers — fix it and rerun the tests"), not as fresh, re-explained tasks.
- **One run at a time per thread.** If a delegation fails immediately with "already has a run
  in progress", another run is live on that thread — wait for it, or use your own `--thread`
  label. (After a crash the stale lock is detected and cleared automatically.)

## Reasoning effort

The peer runs at a reasoning level — **`high` by default**. To run it harder or lighter, pass
`--effort`:

```
bash "$HOME/.agents/skills/agent-bridge/scripts/bridge.sh" <peer> --effort <level> "your task"
```

Levels are `low` · `medium` · `high` · `xhigh` · `max` (low → fast and cheap, max → think as hard
as possible). **Translate what the user asks into the nearest level** — e.g. *"think hard / be
thorough"* → `high` or `xhigh`; *"go all out"* → `max`; *"quick / rough / don't overthink it"* →
`low`. If the user says nothing about effort, omit the flag (you get `high`). You always pass these
canonical levels; the bridge maps each to the peer's own setting (some peers cap lower — that's
expected, and shown in the run header).

## Model

On a fresh thread the bridge sends **no model flag** — the peer runs on whatever its own
CLI is configured to use (a thread that already pinned a model reuses it — see below).
That's the right call whenever the user doesn't bring up models. Pick one only when the
user names a model or clearly asks for a capability (*"strongest"*, *"cheapest"*):

```
bash "$HOME/.agents/skills/agent-bridge/scripts/bridge.sh" <peer> --model <model> "your task"
```

`--model` takes one peer-independent value — `top`, the peer's strongest coding model — or
a model's short name (e.g. `sonnet`, `luna`); each peer's lineup lives in
`references/<peer>.md`, and the adapter translates the name into the peer CLI's own model
argument. Anything it doesn't recognize is passed to the peer CLI verbatim, so exact or
brand-new model IDs work too. **Normalize the user's wording yourself**: *"Claude's best model"* → `--model top`;
*"codex tera"* (typo) → `--model terra`; *"codex's cheapest"* → the cheapest model named in
that peer's reference notes.

**Model and effort are independent knobs**: `--model` picks the model, `--effort` how hard
it reasons. Words like *"quick"*, *"thorough"*, *"don't overthink"* move **effort only** —
don't infer a cheaper model from them unless the user also expresses a model or cost
preference.

**An explicit model sticks to the thread.** Once you pass `--model`, follow-ups on that
thread reuse the same model automatically — don't repeat the flag. Passing a different
model later switches the thread (the header spells out `switching model old→new`). A reset
clears the choice along with the session.

## Parallel delegations (threads)

By default all your calls to a peer share **one** session — that's what makes follow-ups work.
But if several delegations to the same peer run **at the same time** (e.g. you spawn helper
subagents that each call the bridge), they must not share that session: subagents inherit your
chat id, so without separation they'd resume each other's context and overwrite each other's
state. Give each parallel lane its own thread label:

```
bash "$HOME/.agents/skills/agent-bridge/scripts/bridge.sh" <peer> --thread worker-1 "task A"
bash "$HOME/.agents/skills/agent-bridge/scripts/bridge.sh" <peer> --thread worker-2 "task B"
```

- **When you spawn helper subagents that delegate, put a unique `--thread <label>` in the
  exact command you hand each helper** — the helper can't tell on its own that it's one of many.
- Labels are yours to choose — `worker-1`, `review`, `tests` (must start with a letter or digit).
- Each thread is its own persistent peer session — follow-ups on the same label continue it.
- A helper that needs a clean slate should reset **only its own lane** —
  `<peer> reset --thread <its-label>` — never a bare `<peer> reset`, which clears every
  thread's session for that peer.

## Brief the peer like the capable engineer it is

- **Hand it substantial chunks, not micro-steps.** A whole feature, a module, a refactor, a
  real debugging task. Don't break work into tiny one-function asks — that wastes round-trips
  and badly underuses it. Assume it can own a meaty, well-scoped piece end to end and verify
  its own work before reporting back.
- **Give complete context up front:** the goal, the files that matter, constraints, and how
  to know it succeeded (which tests, expected behavior). The more complete the brief, the
  bigger the chunk it can take.
- **State the scope clearly** so it neither overreaches nor stops short.

## Three ways to use a peer — pick what fits

1. **Implementer** — give it the work; let it build, test, and report.
2. **Independent reviewer** — fresh eyes on something you or it wrote:
   "Review the changes in X for correctness and edge cases; be specific."
3. **Adversarial red-team** — have it try to break a design or find the worst failure:
   "Find inputs where this parser returns the wrong answer."

For reviews, ask pointed questions and judge the critique on its merits — push back when you
disagree, take it when it's right. Two strong models disagreeing is the point.

## Starting a peer over

A peer's session persists per conversation, so by default you continue it. But if it gets
stuck or confused, or the user says anything like *"start a new session and try again"*,
**run the reset yourself and then re-issue the task** — the user shouldn't have to type any
command:

```
bash "$HOME/.agents/skills/agent-bridge/scripts/bridge.sh" <peer> reset                    # this peer, all threads
bash "$HOME/.agents/skills/agent-bridge/scripts/bridge.sh" <peer> reset --thread <label>   # one thread only
bash "$HOME/.agents/skills/agent-bridge/scripts/bridge.sh" reset                           # every peer, this chat
```

Your next call starts that peer from a clean slate. Other conversations are untouched.
A reset refuses while an affected delegation is live, so it won't wipe a run mid-flight — but
don't reset while you're spawning parallel helpers, as a brand-new thread can still slip through.

## Your part of the loop

- After the peer reports, **verify independently** with your own tools (read the files, run
  the tests) before accepting. Don't rubber-stamp.
- If something's off, delegate the fix in the **same session**, or fix it yourself — your call.
- When it's done and verified, give the human a short summary: what was built, what you
  checked, and anything still open.