ttt README

项目的 README,来自 github.com/eugenioenko/ttt。合并为一个 markdown 文件:README.md。

TTT Editor: Terminal Text Tool

The IDE that lives in your terminal. A TUI that feels like GUI. A real alternative to VS Code, Zed, and Sublime that happens to run in your terminal. Single Go binary, zero config.

TTT Demo

Full documentation lives in docs-web/src/content/docs/ (published at tttedit.dev).

Installation

Optional dependencies

Neither tool is required to install or use ttt for basic editing. They enable additional functionality:

Quick Install MacOS (brew)

brew tap eugenioenko/ttt
brew trust eugenioenko/ttt
brew install ttt

Quick Install Linux, macOS, FreeBSD, & Android (Termux)

curl -sSfL https://raw.githubusercontent.com/eugenioenko/ttt/main/install.sh | sh

The script downloads the latest release binary for your OS/architecture and installs it to ~/.local/bin on Linux, /usr/local/bin on macOS and FreeBSD, or $PREFIX/bin in Android Termux (arm64). To install elsewhere:

curl -sSfL https://raw.githubusercontent.com/eugenioenko/ttt/main/install.sh | INSTALL_DIR="$HOME/bin" sh

Set INSTALL_DIR on sh so the installer receives it.

Arch Linux (AUR)

ttt-bin installs the prebuilt release binary:

yay -S ttt-bin

Or build from source with ttt:

yay -S ttt

NixOS

Available in nixpkgs:

environment.systemPackages = [ pkgs.ttt ];

Or install directly from the repo flake (tracks the development branch):

nix run github:eugenioenko/ttt

Quick Install Windows (scoop)

scoop install ttt

Go Install

Requires Go 1.25 or newer:

go install github.com/eugenioenko/ttt/cmd/ttt@latest

This installs the ttt binary to your $GOPATH/bin (or $HOME/go/bin by default). Make sure that directory is in your PATH.

Download Binary

Pre-built binaries for Linux, macOS, FreeBSD, Android (arm64), and Windows are available on the Releases page. Windows downloads include ttt-windows-amd64.exe for Intel/AMD PCs and ttt-windows-arm64.exe for ARM PCs. Download the one for your platform, make it executable, and put it in your PATH.

From Source

Note: Building from source compiles the latest development code, which may include work-in-progress features and could be less stable than official releases.

git clone https://github.com/eugenioenko/ttt.git
cd ttt
make build

This produces an optimized binary at bin/ttt. Add it to your PATH or copy it somewhere convenient:

cp bin/ttt ~/.local/bin/

Herdr

TTT is available as a Herdr plugin, so you can open it as a pane inside your Herdr terminal workspace.

herdr plugin install eugenioenko/ttt/herdr-plugin

Once installed, bind it to a key (e.g. Ctrl+b e) to launch TTT in the active worktree with a single keystroke. See the Herdr plugin README for setup and configuration details.

Features

Editor

Multi-Folder Workspaces

Open multiple project directories in a single session. Each root appears as a collapsible group in the explorer, search, and changes panels.

ttt                             # opens the current directory
ttt .                           # also opens the current directory
ttt /path/to/dir                # opens that directory as the workspace
ttt /path/to/file.go            # opens just the file — no workspace folder
ttt /path/to/file.go:42:5       # opens the file at line 42, column 5
ttt /path/to/repo/subdir        # opens that folder; git features (changes,
                                # branch) use the enclosing git repo root
ttt dir1 dir2                   # opens multiple folders as a multi-root workspace
ttt --workspace project.ttt     # loads a saved workspace file
ttt https://github.com/owner/repo/pull/123 # opens pull request review
git diff | ttt                  # opens piped output in an unsaved tab (or: ttt -)

Set "reuseWindow": true in settings.json (off by default; restart required) to open command-line files and add folders in a running editor using the same config directory. The integrated terminal sets TTT_FORWARD_SOCKET to prefer its parent editor; otherwise, or if that socket is unavailable, the newest reachable editor receives the files and folders. If none is reachable, ttt starts normally. Once connected, open errors or timeouts exit with status 1 without trying another editor. Successful forwarding prints opened in running editor (pid N) to stderr (without the PID when unavailable). Use ttt --new-window file to start a separate editor. With reuse enabled, EDITOR=ttt returns immediately; use EDITOR="ttt --new-window" for commands that wait for editing.

Folder arguments add workspace roots without closing existing tabs; folders already in the workspace are ignored using the same rules as Add Folder to Workspace. For example, ttt . adds the current directory, and ttt dirA file.go adds the folder and opens the file. Bare ttt and ttt --workspace project.ttt still start a new editor. To forward folders after upgrading, restart the running editor with the updated binary, or use --new-window to start a separate editor.

Workspace files use the .ttt extension and store a list of folders as relative paths:

{
  "folders": [
    { "path": "." },
    { "path": "../other-project" }
  ]
}

See File Explorer & Workspaces.

File Explorer

Multi-root file tree in the sidebar (Ctrl+K E). When multiple folders are open, each root is shown as a collapsible group.

Sidebar search panel (Ctrl+K F) powered by ripgrep. Results are grouped by file with match counts.

See Search.

Git Integration

Changes panel in the sidebar (Ctrl+K C) with full staging workflow.

Working-tree files and files under expanded commits can be shown as a compact directory Tree or a full-path List (the default). The choice persists in git.fileView. File-type icons sit between the status letter and the file name; like the Explorer's, they follow the shared appearance.icons setting, need a Nerd Font, and default off — Options > Appearance > Font Icons toggles them. Changes, commit details, and Explorer expose safe Expand All and Collapse All actions in their relevant menus.

Staging:

Committing:

Remote operations:

Diff view:

Multi-root:

GitHub pull request review:

ttt https://github.com/owner/repo/pull/123      # review a PR
ttt . https://github.com/owner/repo/pull/123    # review a PR with the repo tree open

Opens the PR as a review surface — commit-by-commit history detail, a live view of the current changes, and the same unified presentation controls as local diffs.

See Git Integration.

Command Palette

Integrated Terminal

Built-in terminal emulator. Press Ctrl+T to toggle the terminal panel, or Alt+T for fullscreen.

See Integrated Terminal.

LSP (Language Server Protocol)

TTT has built-in LSP support for language-aware editing: autocomplete, signature help, go to definition/implementation/type definition, find references, rename symbol, hover, document/selection formatting, format-on-save, and diagnostics.

Language servers are configured via plugins — install the LSP plugin for your language and the corresponding server binary from the Plugins panel or command palette.

You can also add custom servers manually in ~/.config/ttt/settings.json. To disable LSP entirely: "lsp": { "enabled": false }.

The language segment in the status bar shows server state for the current file: ◉ connected, ◌ starting, ⚠ failed. Click it to open the OUTPUT panel, where each server logs its startup command and stderr under lsp:<server>.

See the LSP guide and LSP feature reference for keybindings, configuration, and per-feature detail.

Theming

TTT supports fully customizable themes via JSON files. Every color is themeable — syntax highlighting, diff backgrounds, sidebar, tabs, status bar, terminal ANSI colors, borders, and semantic colors (success, danger, warning).

Built-in themes ship with the binary, and extra themes are available for download from the repo.

Switch themes via Options > Theme (or the command palette) for a live preview. To create a custom theme, copy a built-in file to ~/.config/ttt/themes/ and set "theme" in settings.json. To use your terminal's native colors, set foreground/background to empty strings in your theme file.

See Themes.

Plugins

TTT supports Lua plugins that add sidebar panels, bottom panel tabs, commands, and keybindings. Plugins run in a sandboxed Lua VM with a permission system — users approve each plugin's capabilities on first load.

Editor emulation — prefer modal or Emacs-style editing? Install Vim Mode or Emacs Mode from the Plugins sidebar tab. Both require ttt 1.1.0 or newer.

Installing — open the Plugins sidebar tab to browse and install from the community registry, or use Plugins: Install from URL to install from any git repository. Browse the available utilities, formatters, and language servers at ttt-plugins.

Managing — click an installed plugin to enable/disable it; ↑ to update, × to uninstall, Plugins: Reload for live reload during development. To disable the plugin system entirely: "plugins": { "enabled": false }.

Creating — plugins are Lua scripts with a plugin.ttt.json manifest. See the Plugin Authoring Guide.

The optional terminal.palette plugin permission exposes ttt.terminal.request_palette() to start an asynchronous terminal-color query and ttt.terminal.palette() to read its snapshot. TTT does not poll the terminal at startup or periodically. Since the TTY API cannot cancel a blocked write, shutdown does not wait for an in-flight palette query; in the rare case that the operating system leaves that write blocked, its goroutine may remain until the write returns.

See Plugins.

Configuration

Config files are loaded from <exe-dir>/config/ (bundled defaults) or ~/.config/ttt/ (user overrides):

File Purpose
settings.json Editor settings (tabSize, wordWrap, theme, lsp, autocomplete, etc.)
keybindings.json Custom keybindings (VS Code key format)
themes/*.json Custom color themes

Most settings can be edited from a form: View → Settings, Ctrl+K ,, or Settings: Open Editor Settings from the command palette. Changes are held until you press Apply; Cancel drops them. Settings marked (restart) take effect on next launch. LSP settings and external formatters are JSON-only — use Settings: Open settings.json.

See Settings reference for every key, its type, default, and description.

Keybindings

All keybindings are customizable via keybindings.json. Chord sequences (e.g. ctrl+k e) are supported. Open your keybindings file with Ctrl+K Y, or press Ctrl+P and type ? to browse shortcuts in-app.

Set keyboard.modifierKey to "control+super" to also accept Super/Cmd for Ctrl shortcuts, or "super" to use Super/Cmd instead. The default is "control". Binding definitions stay unchanged, and the terminal must forward the shortcuts.

Use the editor tab bar’s More menu to split right or down (up to four groups), or close a split. Each new group starts with an independent, numbered untitled document; opening a file replaces the untouched placeholder. The command palette groups split actions under Split:, including Split: Equalize Sizes. Views of the same document share text and undo history, with independent cursors and scrolling. Ctrl+K Left/Right/Up/Down focuses the group in that direction; F6 and Shift+F6 cycle groups, the sidebar, and the panel. Drag tabs between groups, or use Open to the Side in a text-tab or Explorer context menu. Split: Move to Other Group is available in the command palette. Closing the last tab removes its group; Close Split merges its remaining tabs into a neighbor.

Choose Extended, Hidden, or Auto-hide tab bars in Settings > Appearance > Window or Options > Appearance > Tab Bar Style. Hidden keeps a one-row divider; tab commands remain available. Auto-hide reveals the strip when the pointer reaches the editor’s top edge.

The full default keybinding list is in docs-web/src/content/docs/reference/keybindings.md.

Testing

TTT uses deterministic tests at several boundaries, from core data structures to real-binary and live-PTY workflows.

Unit Tests (Go)

Core algorithms such as buffer operations, cursor math, and undo/redo have focused Go tests. Core packages are presentation-independent; syntax highlighting lives in the presentation-owned internal/highlight package.

make test                            # run all unit tests
go test ./internal/core/buffer/      # test a single package

E2E Tests (Go + SimScreen)

These wire the complete App to an in-memory term.SimScreen and exercise editor state, commands, event dispatch, and rendered output without starting a real terminal.

go test ./tests/e2e/

Functional Tests (vitest + --exec)

These launch the real ttt binary via the built-in --exec debug harness, run scripted commands in batch, and assert on screenshots and file contents. No external dependencies beyond vitest. Coverage includes:

cd tests/functional
pnpm install
pnpm test              # run all functional tests

The harness acknowledges scripted input and commands after main-thread handling and redraw. Tests should wait only for genuine asynchronous work, using a unique visible post-transition state; raw elapsed waits belong only in tests whose invariant is timing or delayed lifecycle behavior.

Integration Tests (vitest + tui-use)

Tests that require live PTY interaction or a real external process boundary. Built with vitest and tui-use, they cover real language servers, external file changes, settings roundtrips, and bracketed paste.

cd tests/integration
pnpm install
pnpm test

To run the pinned LSP tests independently in GitHub Actions, open Actions → LSP Tests → Run workflow, select a branch, and choose all, c, go, or typescript. The same workflow runs in CI. With the GitHub CLI:

gh workflow run lsp-tests.yml --ref main -f language=go

The LSP Latest Canary workflow can also be triggered manually to test the broader set of servers at their latest versions.

Use the smallest deterministic layer that proves an invariant. Functional tests are a compact real-binary contract, not a mandatory copy of lower-layer coverage. Add a broader test only when it establishes behavior unique to that boundary. CI runs the broad regression lanes on pull requests.

Chaos Monkey (Fuzz Testing)

A randomized fuzz tester that hammers the editor with thousands of random events — keypresses, mouse clicks, resizes, clipboard operations, and command palette commands — to find panics and crashes that normal testing misses. It runs against an in-memory simulated screen (term.SimScreen) so no real terminal is needed.

All chaos targets run in Docker: the random command stream can write files, persist settings, and open browser tabs, so the harness refuses to run unsandboxed (set CHAOS_ALLOW_HOST=1 to force a host run, e.g. under a debugger).

# Quick run (50 iterations x 500 events)
make chaos

# Run continuously (crash logs saved to chaos-output/)
make chaos-docker

# Reproduce a specific crash deterministically
CHAOS_REPLAY=chaos-output/crash-<seed>-<iter>.json make chaos-replay

Each crash is saved as a JSON report with the random seed and full event log, so any panic can be replayed and debugged deterministically.

Debug & Testing CLI Flags

TTT includes a built-in scripted interaction system designed for AI agent interactivity and automated debugging. Think of --exec as a fast Playwright for the terminal — full click, keyboard, and command simulation with screenshot and state dump capture, all without the overhead of a terminal emulation layer.

Flag Description
--exec "commands" Execute semicolon-separated commands after startup
--listen Start an HTTP command server on 127.0.0.1:4242 (POST /exec accepts the same script format as --exec, against an already-running editor)
--plugin FILE Load a Lua plugin file on startup without approval, using the name and permissions of a plugin.ttt.json next to it (without one: every permission except system.exec)
--size WxH Force screen dimensions (e.g. 120x40) for deterministic layout
--debug Enable debug mode regardless of config

The TTT_CONFIG_DIR environment variable overrides the config directory (~/.config/ttt) entirely — settings, keybindings, themes, and plugins are read from and written to that directory instead. Use it to run scripted sessions isolated from your real configuration. Headless --exec sessions also use a process-local clipboard so concurrent automation cannot overwrite the desktop clipboard; interactive sessions, including --listen, keep the system clipboard.

--exec Commands

The --exec flag accepts a semicolon-separated string of commands that run sequentially after the editor starts. AI agents (like Claude Code) can use this to interact with the editor, inspect UI state, and verify behavior programmatically — no manual interaction needed:

Command Description
click X Y Simulate a mouse click at screen coordinates
key COMBO Simulate a key press (e.g. key ctrl+p, key enter)
type TEXT Type a string of text character by character
exec "Command Name" Run a command palette command by title
screenshot PATH Save the current screen text to a file
debug PATH Save the editor's debug state as JSON to a file
wait MS Wait for the given number of milliseconds
wait-for TEXT [timeout=MS] Wait until text appears on the visible screen (default timeout: 5000ms)
quit / shutdown Exit the editor

Quote wait-for text when it contains leading/trailing whitespace or escapes, for example wait-for "Indexing complete" timeout=10000. Scripted input and commands are acknowledged only after the main event loop handles and redraws them, so a following wait-for, screenshot, or debug observes their completed visible state. Invalid actions, missing commands/panels, capture failures, and wait timeouts stop the script: CLI --exec writes the error to stderr and exits nonzero; POST /exec returns a non-2xx response with the same detail.

Example — capture a screenshot and debug state, then quit:

ttt --size 120x40 --exec "wait-for Explore; screenshot /tmp/screen.txt; debug /tmp/state.json; quit"

Example — drive an already-running editor over --listen instead of scripting in advance:

ttt --listen &
curl -X POST --data "type hi; wait-for hi; screenshot /tmp/screen.txt" http://127.0.0.1:4242/exec
curl -X POST --data "shutdown" http://127.0.0.1:4242/exec

Architecture

See ARCHITECTURE.md for the package structure, dependency boundaries, and architecture convergence plan.

Contributing

Bug reports, feature requests, and pull requests are all welcome — open an issue or a PR. See CONTRIBUTING.md before opening one.

Contributors & Acknowledgments

TTT is better because of the people who took the time to try it, report bugs, request features, and contribute code. Thank you. This project grows because of you. 🙏

@eugenioenko @arimxyer @SimonOcampo1 @tenox7 @pirate-boop @bet4it @Detoy @DBinK @risixdzn @LetMeSleep8h @austinm911 @sjdonado @mshafir @w3lld1 @omar3903 @RhenCloud @RonanCodes @choephix @O1sumitkumar @vikas-0 @YodHeVauHe @anyingiit @Dominiquini @jetpax @egorse @forthrin @lozzo @JohnWJ-co @hassanabdulqayyum @atreus44 @z-hunter @LeTuR @aaronsb @rishubil @leandrocm86 @anderlli0053 @lecheel @michalekmatej @micuit-cuit @antonantal @HarshRajSinghania @xircon @hazymoon22 @aahoughton @AnushreeKasturi @EuanTop @rafjaf @sercanatalik @jayhemnani9910 @kooler @cestercian @ibraah007 @gondsman @Yami066 @KeuqS @wzd8888 @MattOrmianek @mahirhir @vincentmathis @danielmrdev @ulrichheringer @adamsiwiec1 @aazminu @Hrushikesh-ramilla @mangeshraut712 @orshih6 @bfs2021 @dannyward630 @alytaphoenix @montionugera @peterheo @webdevsamran @premiuslol @tyza66 @wangyusheng1985 @briandowns @cristianchiriac @motodriver @bluzername @huskyhao @jay23606 @LuckTerence @mike-ward @paoValle @lien-hung @Yuren0312 @philpax @samarthyadavv @sduensin @Catalyze4

Want to help? Bug reports, feature requests, and pull requests are all welcome — open an issue or a PR.

License

MIT

ttt (eugenioenko/ttt)

正在搜索数据库…

1.1K ·GitHub
这是什么?TTT(Terminal Text Tool)是一款运行在终端里的完整代码编辑器,目标是成为 VS Code、Zed 或 Sublime 的真正替代品,而不只是一个轻量级文本编辑器。
这是轻量级文本编辑器还是完整的 IDE?它是一款完整的 TUI IDE:支持 124 种语言的语法高亮,提供 LSP 支持(自动补全、诊断、跳转到定义),内置终端,集成 Git 并带有差异视图,还有基于 Lua 的插件系统。
除了可执行文件本身,我还需要安装别的东西吗?源代码管理功能需要 Git,工作区搜索需要 ripgrep(rg);如果想显示文件类型图标,还需要安装 Nerd Font。
在 NixOS 上安装或从源码构建时要注意什么?NixOS 的 flake 目前跟踪 main 分支,还没有固定的正式版本;从源码构建时编译的是仍在开发中的代码,可能不如官方发布版稳定。
它能在哪些平台上运行?TTT 提供 Linux、macOS、FreeBSD、Android(Termux,arm64)和 Windows(amd64/arm64)的预编译二进制文件,均为单一的 Go 二进制文件。
我能同时打开多个项目吗?可以。多文件夹工作区允许你在一个会话中打开多个项目目录,每个目录在资源管理器、搜索和变更面板中显示为可折叠的分组,并保存为 .ttt 工作区文件。
我能用插件扩展编辑器吗?可以。TTT 支持带权限系统的沙盒化 Lua 插件,可添加侧边栏面板、命令和快捷键;还有社区插件注册表,并支持 Vim/Emacs 编辑模式。
Herdr 是什么?Herdr 是一款终端工作区工具。TTT 可以作为 Herdr 插件使用,只需按一个键,就能在 Herdr 的 worktree 中以窗格形式打开它。
大小
61 MB
星标
1.1K
时长
10个月
提交 · 90 天