toe

Thom's Own Editor (toe)

toe is a modal terminal editor for Go development. toe edits Go projects, not the universe.

toe is my daily driver. It is 0.x software: the editing core is settled, while configuration keys, commands, and defaults can still change between releases.

Super Opinionated

toe is opinionated because it is built for one tight workflow: editing Go projects from a terminal without growing into a general-purpose IDE. It favors modal editing, gopls, TOML config, project-local state, Git diff gutters and a changed-file picker, and a small set of deliberate defaults over plugin sprawl or endless knobs.

• Modal editing: normal, insert, and selection modes; multi-cursor editing; undo and redo
• Project navigation: multiple buffers, split views, fuzzy file/buffer pickers, global search, file and diff previews, image panes, binary/hex panes, and an integrated terminal pane
• Go-focused language tooling: syntax highlighting, language server completion, hover, signature help, formatting, symbols, code actions, rename, go-to navigation, and diagnostics
• Editor display: soft wrap, rulers, whitespace rendering, indent guides, gutters, configurable cursor shapes, and statusline elements
• Version control: git diff gutters, changed-hunk navigation and reset, and a changed-file picker with unified diff previews
• Project state: workspace trust, user/workspace TOML config, EditorConfig, session persistence, external file change detection, and clean-buffer reloads
• 4 Catppuccin themes: frappe, latte, macchiato, mocha

Scope

• Go first. Other language servers are configurable in languages.toml; Go with gopls is the workflow toe is designed and tested around.
• Version control is Git. Diff gutters, hunk navigation and reset, and the changed-file picker all run against the git binary.
• Extension. toe is extended through commands, key bindings, and conditional bindings.
• Terminal capability. Image panes need a terminal that speaks the Kitty graphics protocol; other binary files open as a read-only hex dump. Nerd Font glyphs are on by default and fall back to short ASCII labels.
• Clipboard. toe uses pbcopy/pbpaste, xclip, xsel, or wl-copy/wl-paste when present, with an OSC 52 fallback so copies reach the clipboard over SSH.

Requirements

• Go 1.26 when building from source
• A terminal with ANSI color support
• gopls on PATH for Go language features
• A Kitty graphics capable terminal
• Nerd Font glyphs for enhanced UI

Install

Install the latest stable release with Homebrew (recommended):

brew install kode4food/tap/toe

Odd minor versions (e.g. 0.3.x) are unstable previews, available separately:

brew install kode4food/tap/toe@next

To build the current source:

make build    # writes to dist/toe
make install  # installs to $GOPATH/bin

Usage

toe
toe path/to/file.go
toe file1 file2
toe path/to/project

When the first argument is a directory, toe uses it as the project root.

Configuration

$XDG_CONFIG_HOME/toe/config.toml
$XDG_CONFIG_HOME/toe/languages.toml

Workspace config goes in .toe/config.toml and .toe/languages.toml at the project root.

Workspace config is trust-gated. See docs/content/docs/configuration.md for details.

:workspace-trust
:workspace-untrust

Changes

See CHANGELOG.md for what shipped in each release.

Development

make pre-commit   # run this before committing
make test
make coverage

Acknowledgements

toe is possible because of excellent terminal UI, parsing, syntax highlighting, and theme projects:

• The Charm team for Bubble Tea, which gives toe its TUI runtime, input handling, and terminal output
• The Tree-sitter project for the incremental parsing stack and grammars behind toe's Tree-sitter highlighting
• The Chroma project, the pure-Go syntax highlighter toe uses as its highlighting fallback
• The Catppuccin project for the Latte, Frappe, Macchiato, and Mocha palettes. toe ships only Catppuccin themes because I love them and I don't care if you don't ;-)