block / block/buzz

Add PFTerminal as a preset harness

Open
#4,958 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
32.7k
Forks
4.3k
Avg merge
1d 13h
Merged PRs (30d)
253

Description

**Motivation**

[PFTerminal](https://github.com/agtico/PfTerminal) is an open-source, multi-provider coding terminal built on the Codex CLI. Users who run it today cannot select it in Buzz without hand-authoring a custom harness JSON, because PFTerminal exposes the Codex **app-server** protocol rather than ACP and so cannot be registered as a harness command directly.

The custom-harness route works, but it has a sharp edge that argues for a preset instead: `custom_harnesses.rs` derives reserved IDs from `PRESET_HARNESSES` at compile time, so the moment `pfterminal` ever becomes a preset, every user's hand-authored `pfterminal.json` is rejected with *"id is reserved for a built-in harness and cannot be overridden"*. Anyone who sets it up manually now has to delete that file later.

**Proposed solution**

Add PFTerminal as a tier-2 preset harness, reached through a `pfterminal-acp` launcher that ships with PFTerminal and points the maintained [`codex-acp`](https://github.com/agentclientprotocol/codex-acp) adapter at the PFTerminal binary via `CODEX_PATH`:

```
Buzz --ACP/stdio--> pfterminal-acp --CODEX_PATH--> codex-acp --app-server--> PFTerminal
```

This is the same shape as the existing `amp` / `amp-acp` preset, so `underlying_cli: Some("pfterminal")` gives the correct *AdapterMissing* vs *NotInstalled* distinction when a user has the CLI but not the bridge.

I have this working end to end and opened it as a draft: #4956 (+27/-0). Verified against a real install — ACP `initialize`, `session/new`, an 80-model catalogue, a streamed prompt returning `stopReason: end_turn`, and confirmation that PFTerminal uses its own state directory rather than stock Codex's.

Opening this issue per CONTRIBUTING so a maintainer can acknowledge the approach. **The main question is whether you want PFTerminal in the preset catalog at all** — happy to close both this and the PR if the answer is no, or to keep it as a documented custom harness instead.

**Alternatives considered**

- *Custom harness JSON only, no preset.* Works today and needs nothing from Buzz, but leaves the reserved-ID migration above, and users get the generic terminal icon.
- *Register `codex-acp` directly with `CODEX_PATH` set in the harness `env`.* Mechanically launches PFTerminal, but Buzz's built-in Codex runtime is already defined around `codex-acp`; two runtimes sharing one command risks incorrect runtime identity, stale persona pins, and merged usage attribution. A distinct command avoids that entirely.

**Additional context**

- Draft PR: #4956
- Upstream PR adding the `pfterminal-acp` entry point: [agtico/PfTerminal#78](https://github.com/agtico/PfTerminal/pull/78). #4956 stays draft until that lands and ships in a release, so the preset never points at a command nobody can install.
- Duplicates: none found — searched open and closed issues and PRs for `pfterminal`, `PfTerminal`, and `codex-acp preset`.

Contributor guide

Open the contributing guide

Research direction

Review the draft implementation in PR #4956 and the reserved-ID handling in custom_harnesses.rs, including PRESET_HARNESSES and the existing amp/amp-acp preset. Check whether upstream PfTerminal PR #78 has shipped the pfterminal-acp entry point; the work is done when a maintainer approves the preset approach and the required launcher is installable.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
cli, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.