circumflex: browsing Hacker News in the terminal, read-only by design

Read-only access to HN stories, comments and articles from a single terminal view

circumflex (binary name: clx) is a Go TUI application that displays Hacker News stories, comment sections and linked articles in a terminal. The interface is built on charm.land/bubbletea/v2 v2.0.10, with terminal styling from charm.land/lipgloss/v2 v2.0.6 and UI components from charm.land/bubbles/v2 v2.2.1; all three are pinned as direct dependencies in go.mod, and article text extraction uses codeberg.org/readeck/go-readability/v2.

circumflex is read-only by design. It does not support logging in, voting or commenting, so a browser is still required for any form of participation. The trade-off is that the application needs no authentication state, no session management and no account tokens to store or refresh.

What circumflex replaces is the context-switching between a story list, a comment thread and an article. From the main view, Enter opens the comment section, Space opens the linked article in Reader Mode, and o sends the story to a browser. Pressing c opens the story's comment page in the system browser instead, for cases where you need to interact with HN directly. The link selector, triggered by Tab, keeps more navigation internal: links inside comments or Reader Mode that point to other HN discussions open within the comment view, while article links open in Reader Mode.

Version 5.1 was released on 2026-10-04, following 5.0 on 2026-07-29 and 4.5 on 2026-07-11; the repository is MIT-licensed and not archived.

Installing clx via Homebrew, Nix, the AUR or go install

The README gives five install paths. For macOS with Homebrew:

brew install circumflex

For NixOS:

nix-shell -p circumflex

For Arch Linux via the AUR:

yay -S circumflex

For any platform with a Go toolchain at version 1.27 or later:

go install github.com/bensadeh/circumflex/cmd/clx@latest

To run directly from a cloned repository without a separate build step:

go run ./cmd/clx

The go.mod file sets go 1.27 as the minimum version. Once installed, the command is clx, not circumflex. Running clx help or man clx lists the full set of available commands and flags. Pressing i in any view shows the complete keymap at runtime, including bindings for the comment section and Reader Mode that do not appear in the main view table.

For Linux distributions outside Arch and for Windows, the go install route is the only package-manager-independent path the README documents; Homebrew and AUR packages are maintained outside the main repository. Among the direct dependencies in go.mod are github.com/spf13/cobra v1.10.2 for the CLI command structure and github.com/alecthomas/chroma/v3 for syntax-aware highlighting of code in comments.

The comment section's read mode and navigate mode serve different traversal patterns

Pressing Enter on a story opens its comment section, which operates in two distinct modes. In read mode, vim-style scrolling is active, and n and N jump between top-level comments. Threads collapse and expand by quote level using h and l, or all at once with Enter. That key is context-dependent: Enter in the main story list opens comments, but Enter inside the comment section toggles thread collapse.

Pressing a switches to `navigate mode`, which lets you individually select comments and collapse specific threads. This is the mode for long threads with branches you want to skip without losing your position in others. Pressing Esc returns to read mode, and pressing i in any view shows the complete keymap, which lists bindings for the comment section that are not visible in the main view table.

Comments added since your last visit are highlighted, drawing on history.json in the cache directory. Disabling history with -d or --no-history removes those highlights entirely. Tab opens the link selector inside the comment section, and links pointing to other HN discussions open within the comment view rather than a browser.

Reader Mode uses go-readability for extraction, with images limited to Kitty terminals

Pressing Space on a story opens its linked article in Reader Mode. Article extraction runs through codeberg.org/readeck/go-readability/v2, a direct dependency in go.mod. Readability extraction works reliably on articles built around prose with clear content regions. It does not cover pages whose substance lives in JavaScript-rendered elements, embedded tables or interactive components. Whatever the library cannot classify as content is absent from the output, with no indication that anything was stripped.

Navigation in Reader Mode mirrors the comment section: n and N jump between headers, vim-style scrolling works throughout, and Tab opens the link selector. Links to HN discussions load in the comment view; other links open in Reader Mode. Pressing q returns to the previous view.

Images are handled separately. In terminals with Kitty graphics support, pressing Enter shows the article's images. No fallback applies to other terminals, and no specific emulators are named in the repository. Whether a given terminal qualifies depends on its own feature set, so check the emulator's documentation before counting on image display in articles.

The 180-character threshold for dual-pane mode and how to configure persistent settings

On terminals at least 180 characters wide, circumflex opens in dual-pane mode automatically, with the story list on the left and selected content on the right; pressing z toggles the layout for the current session. To turn wide view off entirely:

clx --wide-view never

Persistent settings live in the config directory. Two commands write default files as starting points:

clx default-config

clx default-theme

The repository root includes config.toml.example and theme.toml.example as references before running either command. Any flag you pass on the command line can instead be written into the config file to persist across sessions. circumflex uses the terminal's own color scheme by default, so no theme changes are required to get started.

The 180-character threshold has no documented config key to change it. On a narrower terminal, z remains in the keymap but has no visible effect. Nerd Fonts are supported as icons. No fallback character set is described for terminals where Nerd Fonts are absent, and the README does not say what the interface falls back to in that case.

Favorites in favorites.toml and history in history.json: where each file lives and how to reset them

Two files persist data between sessions. Favorites are stored in favorites.toml in the config directory, in a human-readable, VCS-friendly format. Older versions that used favorites.json migrate the file automatically on first run. To add a story to favorites in the main view, press f; press x to remove it. A submission can also be added by its HN ID from the command line:

clx add [id]

History is stored in history.json in the cache directory. Each submission you open is marked as read, and history drives the highlighting of comments added since your last visit. Press u in the main view to toggle a submission's read status without opening it. History tracking can be disabled for a single session with the -d flag (--no-history is the long form). To erase accumulated history entirely:

clx clear-history

The cache directory location depends on the operating system and is not documented. No retention limit is stated for history.json, and the project gives no guidance on what to do when the file grows large.

Categories, Algolia search, and the ceiling on what circumflex can do on HN

The main view header shows category tabs. The default set is top, best, ask, show and favorites. All available categories are top, best, new, ask, show, jobs and favorites. To choose which appear and in what order, pass the --categories flag:

clx --categories top,new,best

Tab in the main view cycles through the active categories, and pressing r refreshes the story list.

Global search across Hacker News launches with / in the main view, powered by Algolia. After entering a query, s toggles between sorting by popularity and by date, and d narrows the date range. The / key also works inside the comment section and Reader Mode for searching within the current content, with n and N cycling between matches.

The read-only ceiling matters for deciding whether circumflex replaces your browser tab or supplements it. circumflex cannot submit stories, vote on submissions, post replies, flag comments or send messages. None of those actions exist at any level because the application has no authentication mechanism. For reading and monitoring HN from a terminal it suits the purpose; for participation, the web interface remains necessary.

Editorial conclusion

circumflex fits engineers who read Hacker News daily and prefer not to leave the terminal for it. The read-only constraint is real: replying, voting and submitting stories still require a browser. Images in Reader Mode appear only in terminals with Kitty graphics support, and the 180-character wide view threshold may not match your setup. Before adopting it, install via Homebrew or go install, run clx default-config to inspect the config file, and confirm whether your terminal emulator supports Kitty graphics if article images matter to you.

Frequently asked questions

Official sources

1. bensadeh/circumflex on GitHub
2. Issues
3. License: MIT
4. README
5. Releases