paseo-freebuff-plugin

Paseo provider plugin for the Freebuff CLI (~/.config/manicode/freebuff).

Freebuff ships neither an ACP adapter nor a headless mode (freebuff#319, freebuff#947), so Paseo cannot drive it as a plain extends: "acp" custom provider. This plugin bridges the gap: it runs the interactive Freebuff TUI inside a hidden tmux session, types the prompt with send-keys, reads the screen with capture-pane, and publishes the conversation back to Paseo as timeline items.

Requirements

• Paseo >= 0.10.3 (daemon on the same machine that runs the plugin)
• tmux on the daemon host's PATH
• freebuff on the daemon host's PATH (optionally override with FREEBUFF_BIN=/path/to/freebuff in the daemon environment)

Install

# from any directory
paseo plugin install /path/to/paseo-freebuff-plugin

# verify
paseo provider ls
# freebuff      Freebuff          available     Enabled     default

paseo provider models freebuff

The plugin starts automatically (no npm install needed — Paseo supplies the plugin SDK at runtime).

Usage

# one-shot task
paseo run --provider freebuff "refactor the auth module"

# follow up on an existing agent
paseo send <agent-id> "now add tests"

# watch the timeline
paseo logs <agent-id>

Each Paseo session gets its own tmux session named paseo-freebuff-<shortid>. Closing the Paseo agent kills its tmux session.

Models

The catalog exposes a single default entry — the plugin always uses whichever model Freebuff itself has selected. Change it inside Freebuff:

• interactively with /model, or
• by editing ~/.config/manicode/settings.json:

{ "freebuffModel": "upstage/solar-mini4" }

The plugin reads the active model from the TUI status bar (e.g. GLM 5.3 Flash • max · …) and reports it back to Paseo.

Tip: cost

Freebuff bills per session in Freebucks. If a prompt fails with Not enough Freebucks for <model>, switch to a cheaper or promotional model (e.g. upstage/solar-mini4 was free through Oct 4, 2026). The failure surfaces in Paseo as a failed turn with the TUI's message.

How it works

Paseo ──ProviderRegistration──▶ plugin
                                 ├─ tmux new-session -d freebuff      (session.open)
                                 ├─ send-keys -l <prompt>, Enter      (session.prompt)
                                 ├─ capture-pane -p  →  parseScreen() (poll every 700ms)
                                 ├─ User / reasoning / assistant timeline items
                                 └─ tmux kill-session                 (session.close)

Turn completion is detected from the TUI's turn footer (⎘ • 4s • △▽). Streaming is emulated: the same timeline items are re-published as their text grows.

TUI quirks handled:

• the first-run referral modal (Refer friends → earn Freebucks) is dismissed with Enter automatically;
• Freebuff sometimes swallows the Enter right after pasted text, so the plugin re-sends Enter (up to 4 attempts with 700 ms spacing) until the prompt shows up in the transcript;
• prompts are single-line in the TUI, so embedded newlines are flattened to spaces.

Maintenance

This is screen scraping, not a protocol. All TUI anchors live in server/screen.ts (parseScreen): the input placeholder (Enter a coding task or / for commands), the turn footer regex (/⎘\s*•\s*[\d.]+\s*[smh]/), and the chrome filters (banner █, box-drawing ┌└╭╰│─, timestamps, spinner, status bars).

When Freebuff changes its TUI:

1. tmux capture-pane -p -t <session> to grab a fresh screen,
2. paste it as a fixture in the import.meta.url === … self-check at the bottom of server/screen.ts,
3. adjust the anchors until green, then run:

node server/screen.ts        # 14 checks, no dependencies
paseo plugin reload paseo-freebuff-plugin

Known limits

• No prompt images, no output schemas, no steering commands.
• No Paseo-side persistence; reopening a persisted session re-attaches to the live tmux session if it still exists, otherwise starts fresh.
• session.interrupt sends Escape (best effort).
• Multi-line prompts are flattened to a single line.
• A concurrent paseo run against Freebuff shares your Freebucks quota.

Files

index.server.ts      registerProvider(createProvider())
server/provider.ts   ProviderRegistration: catalog, open, prompt, close
server/screen.ts     TUI parser + self-check (node server/screen.ts)
server/tmux.ts       tmux spawn / capture / send helpers
freebuff.svg         provider icon

License

MIT