wtf

A browser-like terminal for macOS and Linux. A Go backend with a native UI on each: AppKit + SwiftTerm on macOS (macos/, see NATIVE_MACOS_ROADMAP.md), GTK 4 + libadwaita + VTE on Linux (internal/gtkui, see NATIVE_LINUX_ROADMAP.md). Before 1.0 it was a Wails v3 + Svelte 5 + xterm.js app; that UI was removed after 1.7.1 (roadmap #21).

What's next: see ROADMAP.md.

Install on Linux

The .deb (Ubuntu 24.04+, Debian 13+) or .rpm (Fedora 40+) for your processor from the release, e.g. sudo apt install ./wtf_1.1.0_amd64.deb or sudo dnf install ./wtf-1.1.0-1.x86_64.rpm. It replaces an older Wails build of wtf and keeps its windows and settings (~/.config/wtf).

Build the macOS app

Needs Xcode (full, not only the Command Line Tools) and Go 1.25+:

macos/build.sh                   # bin/native/wtf.app (release, this Mac's processor)
macos/build.sh debug             # a debug build
macos/build.sh release universal dmg   # arm64 + x86_64, and bin/native/wtf-<version>.dmg
(cd macos && swift test)         # the Swift core's tests

The version comes from the VERSION file; the build stamps the git commit and date into the app.

Build the native Linux app

In Docker, on any machine (linux/Dockerfile is Ubuntu 24.04 with the GTK, libadwaita and VTE headers):

docker build -t wtf-gtk-dev:ubuntu24 linux
linux/build.sh                   # bin/gtk/wtf-gtk
linux/check.sh                   # tests and headless self-checks under Xvfb
linux/package.sh arm64 amd64     # .deb and .rpm in bin/gtk/packages
linux/package/test-install.sh amd64   # installs them on clean Ubuntu, Debian, Fedora

If a distribution's mirror is slow, UBUNTU_MIRROR=http://mirrors.mit.edu/ubuntu/ or DEBIAN_MIRROR=… points test-install.sh at another one.

Tests

go vet ./... && go test ./...    # the Go backend and shared UI logic
(cd macos && swift test)         # the macOS app's Swift core
linux/check.sh                   # the Linux app, headless, in its dev image

testdata/secrets/cases.json holds what the secret finder must find; both the Go and Swift tests check against it. After changing the rules, regenerate it with go run testdata/secrets/generate.go.

At run time the Linux app uses ss (or lsof) for the Network tab, notify-send for notifications and xdg-open to open files.

Command-line tools

Side-pane features run the programs you'd run yourself — kubectl, the AWS CLI, git, OpenSSH, lsof/ss, notify-send — found on the focused shell's PATH, then wtf's, then the usual install folders (/opt/homebrew/bin, /usr/local/bin, ~/.local/bin…). None is needed to start; a feature whose program is missing says so with an Install… link.

The wrench at the bottom of the side pane's icon rail (also the palette's Command-Line Tools, the macOS wtf menu, and About wtf → Tools) lists each one with its path and version, and installs a missing one for this OS and processor: Homebrew, the official release (kubectl SHA-256-checked into ~/.local/bin; the AWS CLI's signed macOS package or Linux zip into ~/.local), Apple's Command Line Tools, or the distribution's package manager. It shows the exact command or script first and runs it in a new tab, where sudo can ask for a password. On first start it opens once if anything is missing. The .deb/.rpm recommend git, OpenSSH, lsof and libnotify. Code: internal/tools.

Layout

• macos/: the macOS app (AppKit + SwiftTerm); macos/Sources/WtfCore is its shared, tested logic. cmd/libwtf builds the Go backend as a C archive for it.
• internal/gtkui, cmd/wtf-gtk: the Linux app (GTK 4 + libadwaita + VTE); internal/uicore is its shared, tested logic (a Go port of WtfCore).
• internal/backend: builds every service once, for both apps.
• cmd/wtf-mcp: the wtf Claude Code plugin's MCP server (claude-plugin/).
• manual/: the in-app manual's pages.
• internal/terminal: shell sessions (PTY) and foreground-process/cwd polling.
• internal/state: atomic session file storage.
• internal/config: config file, themes (built-in, Ghostty, iTerm2), live reload.
• internal/terminal/shellintegration: the bash/zsh scripts.
• internal/notify: desktop notifications.
• internal/sshhosts: the SSH tab: hosts from ~/.ssh/config and known_hosts, keys and ssh-agent, server host keys, git identities, and background tunnels.
• internal/infra: Kubernetes/AWS/gcloud/Terraform/git context for the context badges.
• internal/kube: the Kubernetes tab: deployments, pods and events, read with kubectl using the focused shell's variables.
• internal/awsprofiles: the AWS tab: profiles in ~/.aws/credentials and ~/.aws/config, checks and key rotation through the aws CLI.
• internal/files: directory listings (with git ignore rules) for the file tree.
• internal/netconn: connections and listening ports, attributed to terminal sessions.
• internal/procs: the user's processes, attributed to terminal sessions.
• internal/cloudsecrets: the Cloud Secrets tab: Secrets Manager, Parameter Store and Vault through the aws and vault CLIs.

Manual

wtf has a user manual built in: Help → wtf Manual (⌘?, F1 on Linux), the command palette, or the ? at the top right of the side pane, which opens the page for the tab on screen. It covers every feature, with search, and its shortcuts come from the app's own command list. The pages are Markdown in manual/ (internal/uicore/manual.go describes the subset they use); tests check that every command and page they mention exists.

About wtf (the wtf menu on macOS, the command palette anywhere) shows the version, the commit and date of the build (the build stamps them in from git), the system, the shell and whether shell integration is on, and where settings, snippets, the session and backups live. Copy Diagnostics copies the version and system facts, with no paths, for a bug report.

Shortcuts

Every command is also in the command palette.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗