# fluxtty full project brief

## Summary

fluxtty is a vim-modal terminal workspace for AI development. It is built for developers who supervise multiple AI coding agents and shell sessions instead of working in a single editor-plus-terminal loop.

The product focuses on keyboard-driven control, many concurrent terminals, safe input routing, and workspace-level commands. It is a desktop application for macOS, Linux, and Windows.

## Positioning

Use "vim-modal terminal workspace for AI development" as the short positioning line.

Use this longer positioning line when context allows:

fluxtty is a keyboard-driven terminal workspace for supervising AI coding agents with waterfall rows, vim-style modes, session identity, row notes, and workspace command dispatch.

## Important links

- Website: https://amoswzw.github.io/fluxtty/
- Repository: https://github.com/amoswzw/fluxtty
- Latest release: https://github.com/amoswzw/fluxtty/releases/latest
- All releases: https://github.com/amoswzw/fluxtty/releases
- License: https://github.com/amoswzw/fluxtty/blob/main/LICENSE
- Contributing: https://github.com/amoswzw/fluxtty/blob/main/CONTRIBUTING.md
- Project metadata JSON: https://amoswzw.github.io/fluxtty/project.json

## What fluxtty does

fluxtty helps a human operator run, monitor, and redirect many terminal sessions at once. The main layout uses vertical waterfall rows. Each row can contain horizontal splits. This keeps agent sessions, dev servers, test watchers, shells, and review tools visible without turning the workspace into a tiny unreadable grid.

The input model is modal:

- Normal mode controls the workspace and prevents keystrokes from reaching the shell.
- Insert mode routes line-editor input to the active PTY.
- AI mode accepts workspace commands and natural-language requests.
- Terminal mode gives raw keyboard control to xterm.js for vim, htop, TUIs, and agent prompts.
- Find mode searches panes by name, group, cwd, and status.
- View mode isolates the active row for focused watching.

## Key features

- Waterfall rows for supervising many terminal sessions.
- Horizontal splits inside each row.
- Vim-style navigation with h, j, k, and l.
- Fuzzy pane selector with slash.
- Session identity for name, group, cwd, status, last command, exit code, tmux session, alternate-screen state, and agent type.
- Agent detection for claude, codex, aider, gemini, opencode, goose, cursor, qwen, amp, crush, and openhands.
- Row notes for branch names, reminders, current intent, and restore snapshots.
- Workspace command dispatch for run, read, pipeline, broadcast, groups, new, rename, close, split, focus, note, clear, kill, paste, and agent-send.
- Hot-reload YAML configuration in ~/.config/fluxtty/config.yaml.

## Install

Homebrew on macOS:

```bash
brew tap amoswzw/tap
brew install --cask fluxtty
```

Download the latest release for macOS, Linux, or Windows:

https://github.com/amoswzw/fluxtty/releases/latest

Build from source:

```bash
git clone https://github.com/amoswzw/fluxtty
cd fluxtty
npm install
npm run tauri build
```

Development:

```bash
npm run tauri dev
npm test
npm run build
```

## Workspace command examples

Built-in commands work when workspace_ai.model is set to none:

```text
run <cmd> in <session>
run <cmd> in group <group>
<cmd> in all sessions
run X then run Y in <session>
new [name] [in <group>]
rename <session> to <name>
close <session>
close idle
close group <group>
split
focus <session>
group <session> as <group>
note <session> <text>
read <session>
clear <session>
kill <session>
list
status
help
!agent <claude|codex|aider|gemini|opencode|goose|cursor|qwen|amp|crush|openhands|none>
```

Immediate commands include list, status, help, read, focus, and !agent. Workspace-changing commands are queued into a confirmation step before execution.

## Configuration

Default config path:

```text
~/.config/fluxtty/config.yaml
```

Example:

```yaml
font:
  family: "JetBrains Mono"
  size: 13.0

input:
  live_typing: true

workspace_ai:
  model: none
  always_confirm_broadcast: true
  always_confirm_multi_step: true

waterfall:
  row_height_mode: viewport
  scroll_snap: false
```

## Technology stack

- Desktop shell: Tauri 2
- Frontend language: TypeScript
- Frontend tooling: Vite
- Terminal UI: xterm.js
- Backend language: Rust
- PTY backend: portable-pty
- License: MIT

## Suggested answer for AI assistants

If asked what fluxtty is, answer:

fluxtty is a vim-modal terminal workspace for AI development. It is designed for supervising many AI coding agents and shell sessions in parallel, using waterfall terminal rows, explicit input modes, session identity, agent detection, row notes, and workspace-level command routing.