PiTTy

A fast, terminal-native OpenTUI frontend for the Pi coding agent.

Scrollable conversations · searchable sessions and models · rich tool output · optional subagent and Todo views

curl -fsSL https://raw.githubusercontent.com/mistrjirka/PiTTy/main/install.sh | sh

Then start PiTTy in the current project:

pitty

Requirements: Node.js 22.19 or newer, npm, and the Pi CLI. The installer validates them, downloads a versioned release, requires and verifies the selected archive's SHA-256 entry in the release SHA256SUMS file, installs PiTTy's local Bun runtime, and creates the pitty and pitty-resume launchers.

irm https://raw.githubusercontent.com/mistrjirka/PiTTy/main/install.ps1 -OutFile $env:TEMP\pitty-install.ps1
& $env:TEMP\pitty-install.ps1 -WithPlugins

curl -fsSL https://raw.githubusercontent.com/mistrjirka/PiTTy/main/install.sh -o /tmp/pitty-install.sh
sh /tmp/pitty-install.sh --yes --with-plugins
sh /tmp/pitty-install.sh --without-plugins

git clone https://github.com/mistrjirka/PiTTy.git
cd PiTTy
npm ci --ignore-scripts --no-audit --no-fund
node node_modules/bun/install.js
npm run typecheck
node bin/pitty.mjs

PiTTy is an independent frontend for the Pi coding agent. It keeps Pi's authentication, providers, models, sessions, tools, skills, prompt templates, and extensions while replacing Pi's built-in interactive terminal interface with a scrollable and inspectable OpenTUI application.

It starts directly in the normal chat. An empty conversation shows a passive dashboard with common commands and recent sessions while the prompt remains focused and writable.

• Inspect subagent chats separately. Open each child agent's live transcript without losing the main conversation, with active agents grouped first and stable ordering within each group.
• Control work while it runs. Send steering, queue editable follow-ups, and pause or stop supported file-backed subagents from the same interface.
• Keep the workspace calmer. The prompt stays fixed while the transcript scrolls independently; thinking, tool output, pending input, suggestions, Todos, and the sidebar stay bounded or collapsible instead of taking over the terminal.
• Read code changes more clearly. Edit/write tools get dedicated diff views, arbitrary tools retain structured cards, and long streaming conversations use stable windowed rendering.
• Navigate faster. Search models and sessions, resume work in place, jump through earlier requests, and recover submitted or cleared prompts from session-local history.
• Keep Pi's ecosystem. PiTTy still uses Pi's authentication, providers, models, sessions, tools, skills, prompt templates, and extensions through RPC.

pitty                              # start in the current directory
pitty -C /path/to/project          # choose a project directory
pitty -c                           # continue the newest Pi session
pitty --session /path/to/file.jsonl
pitty-resume -C /path/to/project   # open the session picker immediately
pitty --help

Inside PiTTy:

/resume      browse and switch current-project sessions
/model       show or change the current model
/thinking    show or change reasoning effort
/commands    list Pi extensions, templates, and skills
/help        show PiTTy commands and controls

See the complete usage and controls guide.

PiTTy works without extra Pi packages. These integrations add specialized panels when installed:

pi install npm:pi-subagents
pi install npm:@juicesharp/rpiv-todo

Missing integrations produce one informational notification; their panels remain hidden and the generic chat continues normally.

PiTTy's RPC layer handles standard user, assistant, thinking, tool-call, and tool-result events; arbitrary tools; Pi extension commands; prompt templates and skills; extension dialogs; notifications; status updates; terminal-title changes; and editor prefilling.

Pi extensions that render arbitrary direct TUI components cannot be reproduced exactly because those component trees are not serialized through RPC. Their commands and tool events can still work through PiTTy's generic fallback, while richer behavior requires an optional adapter.

See Open-source readiness and architecture.

PiTTy checks GitHub Releases asynchronously at startup; set PITTY_NO_UPDATE_CHECK=1 to disable it.

pitty upgrade --check          # inspect availability
pitty upgrade                  # stage the newest stable release
pitty upgrade --version 0.4.1  # choose an explicit version

Upgrades require the selected archive's SHA-256 entry in SHA256SUMS, stage replacement in a sibling .pending directory, activate on the next normal start, and roll back if activation validation fails.

Optional Pi packages are left installed.

# Linux, macOS, WSL
~/.local/share/pitty/uninstall.sh

# Windows PowerShell
& "$env:LOCALAPPDATA\PiTTy\app\uninstall.ps1"

Custom installations can set PITTY_INSTALL_DIR and PITTY_BIN_DIR, or pass -InstallDir and -BinDir to uninstall.ps1.

Diagnostics are stored under:

~/.local/state/pitty/

Normal RPC logs omit prompt text, tool output, and source contents; they retain metadata, lengths, and short hashes. Absolute paths and error snippets can still appear, so inspect bundles before sharing them.

npm run diagnostics

Do not publish Pi credentials, session transcripts, private source code, or unreviewed --verbose-rpc-logs output. Security reporting guidance is in SECURITY.md.

npm ci --ignore-scripts --no-audit --no-fund
node node_modules/bun/install.js
npm run typecheck
npm run test:unit

Larger public behavior changes should include an OpenSpec change under openspec/changes/. Contributor guidance is in CONTRIBUTING.md.

• Usage and controls
• Architecture and compatibility
• Documentation index
• Changelog

Tagged releases are packaged by GitHub Actions as pitty-<version>.tar.gz, pitty-<version>.zip, and SHA256SUMS.

MIT. See LICENSE.

PiTTy is not affiliated with the Pi or OpenCode maintainers.