# Harness Floating Terminal
An F7 floating shell beside Claude Code, Codex, or OpenCode, without wrapping
your AI CLI. Run your AI command normally in a tmux pane.
## Installation
Requires **tmux 3.4+** and macOS or Linux. Install your AI CLI normally.
Homebrew supplies tmux; other methods require you to install it separately.
**Release note:** Cargo v0.2.2 is published. The simplified Homebrew setup below
requires the next release containing first-use registration; v0.2.2 still uses
[explicit setup](docs/installation.md#homebrew). Homebrew/archive downloads also
require public [release assets](https://github.com/vuongvm812/agent-float-term/releases).
Choose one method; switching an existing installation requires the
[migration steps](docs/operations.md#switching-installation-methods).
### Homebrew
After the new stable release and tap formula are published:
```sh
brew tap vuongvm812/tap
brew install vuongvm812/tap/agent-float-term
```
No separate application installation is needed. The first `agent-float-term bind`
or interactive `agent-float-term start` registers Homebrew's stable binary path
without copying it or editing startup files. Homebrew owns binary updates.
See [platform limits](docs/installation.md#homebrew), then [activate](#activate).
### Cargo
Using the default Cargo installation root:
```sh
cargo install agent-float-term --locked
aft="${CARGO_HOME:-$HOME/.cargo}/bin/agent-float-term"
"$aft" install --external-binary "$aft"
# Review the preview before applying:
"$aft" install --external-binary "$aft" --yes
```
**Cargo compiles locally:** Rust/Cargo and a native build toolchain are required.
Rust 1.84.1 is the release toolchain. Cargo owns the executable and updates;
see [custom installation roots](docs/installation.md#cargo) if your Cargo settings
override the default.
### Release Archives
After publication, download the archive for your OS/architecture from
[GitHub Releases](https://github.com/vuongvm812/agent-float-term/releases), verify
its entry in `SHA256SUMS`, then run the extracted binary's `install` preview and
repeat with `--yes`. No Rust compiler is needed.
Follow the [download and verification commands](docs/installation.md#release-archives).
The installer owns a local copy at `~/.local/bin/agent-float-term`; do not copy a
regular executable to that destination before running the installer.
### Build From Source
```sh
git clone https://github.com/vuongvm812/agent-float-term.git
cd agent-float-term
cargo +1.84.1 build --locked --release
./target/release/agent-float-term install
# Review the preview before applying:
./target/release/agent-float-term install --yes
export PATH="$HOME/.local/bin:$PATH"
```
To build/install the managed application **and patched tmux for status-bar
clicking**, use `make install` instead. `make install DRY_RUN=1` previews the plan.
It does not restart tmux; follow the printed separate-server launch command.
See [patched-server setup](docs/status-bar-mouse.md).
### Activate
Ensure the selected binary directory is on `PATH`: Homebrew's `bin`, Cargo's
installation-root `bin`, or `~/.local/bin` for managed archive/source installs.
Inside your existing tmux server:
```sh
agent-float-term bind
agent-float-term doctor
claude
# Or: codex / opencode
```
Press **F7** to open or hide the float. Shell state survives hiding, but **exiting
the AI terminates its float and terminal jobs**. The next AI run starts fresh.
Tmux shortcuts operate on the main terminal. Switching away leaves the float in
its original AI pane; returning restores it unless you explicitly hid it with F7.
Prompts and choosers temporarily take keyboard focus from the float.
In the next release, `Ctrl+h/j/k/l` remain available to foreground Neovim inside
the float; other tmux shortcuts still target main. The optional
[patched tmux server](docs/status-bar-mouse.md) dismisses the float and switches
sessions with one status-bar click; stock tmux requires hiding the popup first.
See [input behavior](docs/operations.md#lifetime-and-ownership)
for details and limitations.
Fresh installation edits no startup files unless explicitly selected. Review key
conflicts before using `bind --replace-key`. Outside tmux, `agent-float-term start`
opens a dedicated tmux shell. See [installation](docs/installation.md) for automatic
startup and [operations](docs/operations.md) for update, rollback, and uninstall.
Generated integration scripts live in `~/.local/share/agent-float-term/`, not the
config directory. Reinstalling migrates intact legacy scripts and managed references.
## Configuration
Create `${XDG_CONFIG_HOME:-$HOME/.config}/agent-float-term/config.json` if needed:
```json
{
"shortcut": "F7",
"width": 80,
"height": 80
}
```
These are the defaults. Dimensions are integer percentages from **10 to 100**.
Omitted fields use defaults; unknown fields, comments, and trailing commas are
rejected. JSON only: an old `config.toml` is preserved but never loaded. If it
exists without JSON, an error explains migration; `{}` explicitly uses defaults.
Use `shortcut`, not `key`, and rebind the intended server after changing it.
See [configuration details](docs/configuration.md) for safe shortcuts, advanced
`shell`/`harness_paths`, file permissions, and XDG rules.
## Compatible Versions
| tmux | **3.4+**; current PTY tests pass on 3.4, 3.5a, and 3.7c. Client and running server versions must match. |
| Rust / Cargo | **1.84.1** for source builds; not needed to run an installed binary. |
| Claude Code | 2.1.263, previously smoke-tested without model requests. |
| Codex | 0.153.4, previously smoke-tested without model requests. |
| OpenCode | 1.18.29, previously smoke-tested without model requests. |
| OS | macOS and Linux. Native Windows is unsupported. |
See the [validation matrix](docs/compatibility.md) for platform coverage and test
limits. This tool adds no telemetry or prompt logging; tmux is not a sandbox.
[MIT license](LICENSE)
Maintainers: `make release DRY_RUN=1` previews the coordinated release plan;
`make release` requires explicit confirmation before publishing GitHub assets,
the Homebrew formula, and a missing Cargo version. See [release prerequisites](docs/publishing.md#make-release).