# tcell: termbox's ideas rebuilt in pure Go > tcell is an Apache-2.0 Go package providing a cell-based view for text terminals, inspired by termbox and improved well beyond it: Unicode grapheme clusters, 24-bit color, modern keyboard protocols, mouse tracking, and escape-hatch environment variables for misbehaving terminals. Version 3 arrived with breaking changes and steady bug-fix releases since. **gdamore/tcell** — Tcell is an alternate terminal package, similar in some ways to termbox, but better in others. - Repository: https://github.com/gdamore/tcell - Stars: 5,224 · Forks: 377 - Language: Go - License: Apache-2.0 - Published: 2026-09-23 · Updated: 2026-09-23 · Language: en - Canonical page: https://hysenlabs.com/projects/gdamore-tcell ## termbox lineage, without the C tcell provides a cell based view for text terminals like XTerm, and the README is upfront about its ancestry: inspired by termbox, but including many additional improvements. The most consequential improvement is invisible in the API, the package is pure Go with no need for CGO, which removes the entire class of cgo build and cross-compilation pain from terminal projects and is why it works everywhere mainstream Go works. The support policy follows Go's own, officially covering only the current stable release and the one immediately prior, a stance the project justifies as necessary to pick up security fixes and newer language features in dependencies. CI runs Linux, macOS, Windows and WebAssembly workflows, and platform-specific files like tscreen_unix.go, tscreen_win.go and charset_plan9.go carry the per-system detail. ## Grapheme clusters, wide characters and a 2 MB choice Unicode handling goes deeper than runes. Internally tcell uses UTF-8 just like Go, but it understands wide characters and grapheme clusters, the multi-rune user-perceived characters that naive rune counting gets wrong. The Put() API takes a string and displays the first grapheme cluster in it, returning the actual width displayed so the caller can advance the column correctly, while PutStr() and PutStrStyled() render a single line clipped at the screen edge. The documentation also states the sharp edge plainly: displaying a character in the cell immediately adjacent to a wide character, offset by one instead of two, produces undefined results. Conversion to and from non-Unicode locales uses the golang.org/x/text/encoding machinery, and the full set of common encodings is deliberately not built in, because it bloats programs by about 2 MB, with an encoding/ subdirectory available for those who want everything anyway. ## Keys, mice and paste as first-class input Input support is where tcell spends its termbox-improving energy. A larger number of special keys is recognized, and on modern terminal emulators a rich set of modifiers works, including the ability to discriminate CTRL-I from TAB, something legacy protocols cannot express, contingent on the terminal supporting one of the modern keyboard protocols. Mouse support covers enhanced tracking mode, regular motion events, click-drag and wheel, on most terminal emulators and on Windows. Bracketed paste rounds out the set, letting applications distinguish pasted text from keystrokes, enabled through EnablePaste(). The event surface in the codebase mirrors the feature list, with key.go, mouse.go, paste.go, focus.go and resize.go as separate concerns, so an application's input loop can treat each input class deliberately rather than through one opaque blob. ## 256 colors, truecolor, and the theme question Color starts from the assumed ANSI/XTerm palette of up to 256 colors, with legacy terminals possibly offering only 8. Above that sits 24-bit color, enabled in several ways: the COLORTERM environment variable set to truecolor, which supporting emulators usually do themselves; a TERM value suffixed with -truecolor or -direct, compatible with XTerm and ECMA-48; and on Windows, 24-bit support is simply assumed, all modern Windows terminals having it. Disabling is equally explicit, TCELL_TRUECOLOR=disable. The README then addresses the philosophical cost few libraries acknowledge: truecolor displays the colors the programmer intended, overriding the themes the user configured in their terminal emulator, which is right when color fidelity matters and wrong for ordinary text apps that should respect user themes. Making that trade a visible decision, rather than an accident of capabilities detected, is the mature part. ## Environment variables as the user's escape hatch tcell normally negotiates terminal capabilities automatically, but some terminal emulators answer those queries incorrectly, and the project's answer is a set of user-facing overrides rather than a bug report queue. TCELL_KEYBOARD_PROTOCOL accepts auto, legacy, kitty, win32 or xterm to force the keyboard reporting protocol. TCELL_NEGOTIATE can disable startup capability negotiation when terminal responses themselves are problematic. TCELL_MOUSE can prevent applications from enabling mouse reporting. Applications have their own knobs, OptKeyboardProtocol and OptNegotiation, but the environment variables take precedence, a deliberate ordering so that users can recover from bad terminal behavior without modifying the application they are running. It is a small design decision that respects the person at the keyboard, and it encodes an honest assessment of the terminal emulator ecosystem. ## Version 3, its toll, and its predecessors The versioning story is told without varnish. Version 3 contains breaking changes relative to versions 1 and 2, and the README warns that your application will almost certainly need some minor updates, pointing at CHANGESv3.md for the list. Version 2 remains available under the github.com/gdamore/tcell/v2 import path for code not ready to migrate, while version 1, importable without a suffix, is described as unmaintained and should not be used, one of the blunter deprecation sentences in open source. The module itself builds on go 1.26.0 with a compact dependency list, gdamore/encoding for character sets, go-colorful for color work, x/sys, x/term and x/text from the Go project, plus displaywidth and uax29 for text measurement and grapheme segmentation. Release cadence is healthy: v3.4.1 on 2026-07-19, v3.4.2 on 2026-08-20 and v3.5.0 on 2026-09-11, with the last push on 2026-09-24. ## Plan 9, WASM, and documentation in four READMEs The documentation set is platform-shaped: alongside the main README sit README-windows.md, README-wasm.md and README-plan9.md, each carrying the specifics of an unusual target, and the WebAssembly story is backed by a CI workflow rather than left as an aspiration. Learning resources include a TUTORIAL.md the author describes as brief and still somewhat rough, demonstration programs under ./demos and ./_demos, and a community Gallery wiki that accepts submissions. Performance work is described modestly, reasonable attempts to minimize data sent to terminals, avoiding repeated sequences and not redrawing unchanged cells on refresh, which is the correct optimization for cell-based rendering. SECURITY.md, an AGENTS.md for coding assistants, a Discord server and a stand-with-Ukraine badge complete a project that reads as personally maintained but professionally organized. ## Conclusion Use tcell when you are writing a terminal application in Go and want a cell-based screen model that handles Unicode, color and input across POSIX, Windows and WASM without CGO. Consider the original termbox only if you are maintaining an existing program against it, since tcell is its improved spiritual successor. Verify first that your Go version is the current stable or the one prior, per the project's support policy, read CHANGESv3.md before migrating from v2, and decide early whether your app should honor terminal themes or force truecolor, because that choice affects every color you set. ## FAQ ### What is tcell in Go? tcell is an Apache-2.0 Go package providing a cell-based view for text terminals, inspired by termbox. It is pure Go with no CGO requirement and supports Unicode grapheme clusters, wide characters, 24-bit color and enhanced mouse and keyboard handling. ### How do you get started with tcell? Read TUTORIAL.md in the repository, then study the demonstration programs under ./demos and ./_demos plus the community Gallery wiki. The package imports as github.com/gdamore/tcell/v3. ### How do you enable or disable 24-bit color in tcell? Set the COLORTERM environment variable to truecolor, or use a TERM value ending in -truecolor or -direct; on Windows, 24-bit color is assumed. Disable it by setting TCELL_TRUECOLOR=disable in the environment. ## Sources - [gdamore/tcell on GitHub](https://github.com/gdamore/tcell) - [Issues](https://github.com/gdamore/tcell/issues) - [License: Apache-2.0](https://github.com/gdamore/tcell/blob/main/LICENSE) - [README](https://github.com/gdamore/tcell/blob/main/README.md) - [Releases](https://github.com/gdamore/tcell/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gdamore-tcell