Feature request: headless/print mode + SDK support for freebuff authToken (for third-party orchestrators)

[micahcooley]

Summary

Requesting two related capabilities that would make Freebuff drivable by third-party orchestrators (e.g. Koryphaios, Zed via ACP, CI runners) without a TTY:

1. A --print / -p headless flag on the freebuff CLI (mirroring what codebuff exposes, or at least what the @codebuff/sdk exposes via handleEvent).
2. Allowing the freebuff device-OAuth authToken to work with @codebuff/sdk's CodebuffClient so the free ad-supported account can run agents programmatically — not just interactively.

Background

Freebuff is the free, ad-supported build of Codebuff. Today the freebuff CLI is purely interactive — a TUI with no headless path. I verified this against the installed native binary (freebuff v0.0.140, ~/.config/manicode/freebuff):

• freebuff -p / --print → error: unknown option '-p'
• freebuff --headless → error: unknown option '--headless'
• freebuff --json → error: unknown option '--json'
• freebuff "do something" → no [prompt...] argument accepted (only [command] with choices ["login"])
• piping a prompt via stdin → hangs waiting for a TTY

The codebuff (paid) CLI has more flags (--agent, --max, --plan, [prompt...]) but also lacks --print/--json — headless execution today is only available through @codebuff/sdk's CodebuffClient.run(), which requires a paid CODEBUFF_API_KEY (cb_...).

The freebuff CLI stores credentials at ~/.config/manicode/credentials.json with shape:

{ "default": { "id", "name", "email", "authToken", "fingerprintId", "fingerprintHash" } }

This authToken is a device-OAuth token, not a cb_... API key. Passing it to CodebuffClient({ apiKey }) is untested and may be rejected by the backend (different token class, fingerprint validation, ad-enforcement requirements, etc.).

Why this matters

Third-party agent orchestrators (I'm building Koryphaios) currently wrap CLI agents like Claude Code, Codex, Grok Build, Cursor, Devin, and Cline by spawning their binaries in --print/headless mode and parsing their NDJSON/JSONL event streams. Freebuff is the only major free CLI agent with no headless path at all, which means it's the only one we can't offer as a provider — even though it's the one users without paid subscriptions need most.

Freebuff's "6 one-hour sessions per day" limited mode is a usage policy, not a technical barrier — there's no reason it couldn't be enforced in a headless run too (show the ad text as a structured event, count the session, enforce the clock).

Proposed design

Option A — --print / -p on the CLI (preferred, lowest friction)

freebuff -p "refactor the auth module" --output-format stream-json --verbose

• Emits one JSON object per line on stdout (same PrintModeEvent shape the SDK already defines: start, text, tool_call, tool_result, subagent_start, subagent_finish, error, finish, reasoning_delta).
• Reads the initial prompt from the CLI arg or stdin.
• Honors --cwd, --continue [id], --agent <id>.
• No TTY required; safe for CI and subprocess spawning.
• Ad enforcement: emit an ad event (or print ad text to stderr) before the run starts; require --ads-ack or an env var to acknowledge.

Option B — @codebuff/sdk accepts the freebuff authToken

import { CodebuffClient } from '@codebuff/sdk'
// Read from ~/.config/manicode/credentials.json instead of CODEBUFF_API_KEY
const client = new CodebuffClient({ apiKey: freebuffAuthToken, fingerprintId, ... })

This already works for paid keys — the ask is just to accept the freebuff device-OAuth token as a valid credential for run(), with the same session/ad limits enforced server-side. This is the cleanest path for orchestrators that already speak the SDK event protocol.

Option C — both

A is the universal solution (works for any subprocess-based integrator). B is the ergonomic solution for Node/TS integrators. They're complementary.

What I've already verified

• The freebuff npm package is a thin launcher (index.js → launcher.js) that downloads a 124MB native binary to ~/.config/manicode/freebuff.
• The native binary uses Commander.js; the freebuff flag set is intentionally stripped vs codebuff (no --agent, --max, --plan, [prompt...]).
• The --headless and --json strings exist inside the binary but come from bundled chrome-devtools-mcp (browser-use agent), not from the CLI's own flag parser.
• @codebuff/sdk exists, is published, and exposes CodebuffClient.run() with handleEvent: (event: PrintModeEvent) => void — exactly the streaming protocol an orchestrator needs.
• Freebuff/Codebuff is an MCP client (consumes .codebuff/mcp.json), not an MCP server — so MCP is not a viable transport for driving it as a provider.

Related

• [Feature request] ACP Support #319 (ACP support) — ACP would also solve the orchestrator-integration case; this request is a lighter-weight, lower-friction alternative.
• codebuff PR feat(cli): add read-only /mcp status command #876 added a read-only /mcp status command — useful but orthogonal.

Willing to contribute

Happy to help prototype/test either option against a real third-party orchestrator integration. I have a working provider harness for 7 other CLI agents and can validate the event-mapping end-to-end.