Add PFTerminal as a preset harness
- 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
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