The fledge-v1 Protocol

Plugins talk to fledge via newline-delimited JSON over stdin/stdout. The Rust crate fledge-protocol (crates/fledge-protocol) provides typed structs and a PluginIO helper.

Lifecycle

   fledge spawns plugin binary
         │
         ▼
  ────── stdin ──────▶
   InitMessage  {protocol, command, args, project, plugin, fledge}

  ◀───── stdout ──────
   OutboundMessage::Output  {text}
   OutboundMessage::Log     {level, message}
   OutboundMessage::Progress{...}
   ...

  ────── stdin ──────▶
   InboundMessage  {type, id, value}   ← responses to Prompt/Confirm/Select/etc.
         │
         ▼
   plugin exits

Init

Sent once at startup:

{
  "protocol": "fledge-v1",
  "command": "files-read",
  "args": ["src/main.rs"],
  "project": {
    "name": "merlin",
    "root": "/path/to/merlin",
    "language": "rust",
    "git": { "branch": "main", "dirty": false }
  },
  "plugin": {
    "name": "fledge-plugin-files",
    "version": "0.1.0",
    "dir": "/path/to/plugin"
  },
  "fledge": { "version": "1.3.1" }
}

In Rust:

use fledge_protocol::PluginIO;

let mut io = PluginIO::new();
let init = io.recv_init();
let command = init.command.as_deref().unwrap_or("");
let args = &init.args;

Outbound (plugin → fledge)

Plugins emit one JSON object per line. The discriminator is the "type" field.

Type	Fields	Use
`output`	`text`	Tool output that bubbles up to the LLM
`log`	`level` (`"info"` / `"warn"` / `"error"`), `message`	Diagnostics — captured by fledge but not the LLM
`progress`	`message?`, `current?`, `total?`, `done?`	Long-running progress
`prompt`	`id`, `message`, `default?`, `validate?`	Ask user for free-form input
`confirm`	`id`, `message`, `default?`	Yes/no
`select`	`id`, `message`, `options`, `default?`	Pick from a list
`store`	`key`, `value`	Persist a key/value (no response)
`load`	`id`, `key`	Retrieve a stored value (response on stdin)
`exec`	`id`, `command`, `cwd?`, `timeout?`	Have fledge run a sub-command (response on stdin)
`metadata`	`id`, `keys`	Query project metadata (response on stdin)

Plugins can emit any number of output, log, and progress messages without expecting a response. Messages with an id field (prompt, confirm, select, load, exec, metadata) expect a matching inbound response.

Inbound (fledge → plugin)

User responses to id-bearing outbound messages:

{
  "type": "response",
  "id": "1",
  "value": "yes"
}

Or a cancellation:

{
  "type": "cancel",
  "id": "1",
  "reason": "user-requested"
}

The PluginIO::wait_for_response(id) helper blocks on stdin until the matching response arrives.

Helpers

The PluginIO struct in fledge-protocol wraps stdin/stdout with typed helpers:

io.recv_init()                  → InitMessage
io.output(text)                 // emit Output
io.log(level, message)          // emit Log
io.progress(message, cur, tot)  // emit Progress
io.prompt(message, default)     → String   (blocks)
io.confirm(message, default)    → bool     (blocks)
io.select(message, options)     → usize    (blocks)
io.exec(command, cwd, timeout)  → ExecResult (blocks)

The non-interactive flag --ni (used by Merlin’s agent) tells fledge to fail any prompt rather than blocking. Plugins should not assume prompts will succeed.

Conventions

Exit 0 on success, non-zero on failure. Fledge captures the exit code and reports it as success: false to the caller.
Use output for results, log for diagnostics. Anything in log is invisible to the LLM, which is what you want for noisy internal stderr.
Trailing newlines are fine. The Merlin CLI strips trailing whitespace before display.
Keep output structured. Tool results are fed back as opaque strings to the LLM. JSON is great when you need structure; plain text is fine when you don’t.