Circumflex: Terminal Hacker News Made Beautiful

Transform your Hacker News experience with this revolutionary terminal tool that keeps you focused and productive.

Tired of browser tabs stealing your attention? Circumflex delivers the entire Hacker News ecosystem directly to your terminal. No distractions. No context switching. Just pure, streamlined content consumption where developers live—the command line. This powerful TUI application reimagines how you interact with HN, combining syntax highlighting, intelligent caching, and seamless navigation in one sleek package. Get ready to supercharge your reading workflow.

What Is Circumflex?

Circumflex (binary name: clx) is a modern, Go-powered terminal user interface that lets you browse Hacker News without ever leaving your command line. Created by bensadeh, this open-source tool has quickly become essential for developers who value focus and efficiency.

Unlike traditional browser-based reading, circumflex pipes content through less, the ubiquitous pager Unix users already know and love. This architectural decision eliminates learning curves while providing instant familiarity. The application leverages Bubble Tea—the same TUI framework behind legendary tools like LazyGit and Glow—to deliver a responsive, keyboard-driven experience that feels native to your terminal.

What makes circumflex genuinely revolutionary is its Reader Mode. Using advanced content extraction algorithms powered by go-readability and html-to-markdown, it strips away ads, sidebars, and clutter—delivering only the article's core content. This isn't just a wrapper around HN's API; it's a complete rethinking of how technical content should be consumed in a distraction-free environment.

The tool has gained massive traction in the developer community because it solves a real pain point: context switching kills productivity. By keeping HN in the terminal alongside your code, you maintain flow state while staying informed. The project consistently trends on GitHub because it represents the terminal renaissance—where developers reclaim their workflow from bloated web applications.

Key Features That Transform Your Workflow

🛋 Everything in One Place

Circumflex unifies your reading experience. Press Enter to dive into threaded comment sections. Hit Space to launch Reader Mode for the linked article. No external browsers. No copy-pasting URLs. Everything flows through the same interface, maintaining your mental context and keeping you in the zone.

🌈 Intelligent Syntax Highlighting

The tool doesn't just display text—it understands it. Comments receive rainbow-colored indentation blocks that make nested threads visually parseable at a glance. Text formatting renders bold, italics, and code segments exactly as intended. Special HN conventions like @username mentions, $variables, and bracketed references [1] receive distinct highlighting for instant recognition.

⚡️ Less Integration for Power Users

By piping content through less, circumflex inherits decades of pager optimization. Scroll half-screens with d/u, navigate line-by-line with j/k, and search with /. This integration means zero new keybindings to memorize. Power users can even leverage their existing less configuration—custom colors, keymaps, and behaviors work automatically.

🤹 Native Terminal Color Scheme Support

Circumflex respects your aesthetic choices. Using lipgloss and go-term-text, it adapts to your terminal's color palette automatically. Whether you prefer Solarized Dark, Dracula, or a custom theme, the application looks native without configuration. This philosophy—"bring your own color scheme"—eliminates the tedious theming work required by other TUIs.

💎 Nerd Fonts Integration

For users with Nerd Fonts installed, the -n flag unlocks beautiful iconography. Stars, arrows, and UI elements render as crisp symbols instead of ASCII approximations. This optional enhancement makes the interface feel modern and polished while remaining completely functional without font patches.

❤️ Persistent Favorites System

Press f to save any submission instantly. Favorites live in ~/.config/circumflex/favorites.json as pretty-printed JSON—human-readable and Git-friendly. You can even add stories by ID from the command line: clx add 12345. This creates a permanent, portable library of valuable content that syncs across machines via dotfiles.

📚 Smart History Tracking

Visited submissions automatically mark as read, with new comments highlighted on return visits. History stores in ~/.cache/circumflex/history.json, enabling intelligent resume functionality. Run clx clear to wipe your browsing history, or use -d flag to disable tracking entirely for privacy-focused sessions.

Real-World Use Cases That Deliver Results

1. The Morning Dev Routine

Start your day with clx in a tmux pane alongside your editor. Scan top stories while your coffee brews. Press Tab to cycle through categories—top, best, ask, show—without touching your mouse. When you find an interesting post, Space opens it in Reader Mode. By the time you finish your first cup, you're informed and ready to code, all without opening a single browser tab.

2. Deep Research Workflow

Investigating a new technology? Use clx to harvest community insights. The syntax highlighting makes code snippets in comments instantly visible. Rainbow indentation reveals discussion structure, helping you find authoritative voices. Save relevant threads with f to build a research corpus. Later, clx comments [ID] jumps directly to specific discussions, bypassing navigation overhead.

3. Airplane Mode Productivity

No Wi-Fi? No problem. Circumflex caches content intelligently. Before your flight, quickly open articles in Reader Mode—they're now available offline through less. Your favorites and history remain accessible, letting you catch up on saved content at 30,000 feet. This transforms dead travel time into valuable learning opportunities.

4. Distraction-Free Focus Blocks

Pair circumflex with tools like do-not-disturb modes or focus timers. The terminal interface eliminates the temptation of browser tabs. You can't accidentally open Twitter when you're in clx. The keyboard-driven workflow keeps your hands on the keyboard and your mind on content. When you're done, q returns you to your shell—no rabbit holes, no lost hours.

Step-by-Step Installation & Setup Guide

Getting started with circumflex takes under two minutes. Choose your installation method:

Package Manager Installation (Recommended)

macOS with Homebrew:

brew install circumflex

Nix environments:

nix-shell -p circumflex

Arch Linux via AUR:

yay -S circumflex

These methods handle dependencies automatically and provide easy updates.

Building From Source

For the latest features or custom modifications:

# Clone the repository
git clone https://github.com/bensadeh/circumflex.git
cd circumflex

# Build and run directly with Go
go run main.go

# Or install to $GOPATH/bin
go install

⚠️ Critical Requirement: When building from source, ensure you're running the latest version of less. Circumflex depends on modern less features for optimal rendering. Check your version with less --version—you need version 590 or newer. Update via your package manager if necessary.

Post-Installation Verification

Verify installation succeeded:

clx --version

Launch the application:

clx

On first run, circumflex creates its configuration and cache directories:

• Config: ~/.config/circumflex/
• Cache: ~/.cache/circumflex/

You're now ready to browse Hacker News from your terminal!

REAL Code Examples from the Repository

Example 1: Command-Line Favorites Management

The README provides powerful CLI commands for managing your reading list:

# Add a specific HN submission by ID to your favorites
clx add 12345

# Remove all browsing history (clears read markers)
clx clear

# Jump directly to a submission's comments
clx comments 12345

# Read a specific article in Reader Mode
clx article 12345

# Open any URL directly in Reader Mode (bypasses HN)
clx url "https://example.com/article"

Explanation: These commands enable scripting and integration with other tools. The add command is perfect for building automated reading lists. clx clear helps maintain privacy. The direct-access commands (comments, article) are invaluable for bookmarking systems or note-taking workflows where you want to reference HN content without manual navigation.

Example 2: Advanced Flag Configuration

Customize circumflex behavior with these runtime flags:

# Launch with Nerd Fonts icons enabled
clx -n

# Disable history tracking for this session
clx -d

# Auto-expand all comment threads on entry
clx -a

# Set custom comment width (default 70)
clx -c 80

# Hide indentation bars for cleaner view
clx -t

# Combine multiple flags for personalized experience
clx -n -c 90 -a --categories="top,ask"

Explanation: Flags provide session-level customization without editing config files. The -n flag enhances visual appeal with icons. -d is perfect for shared machines or privacy-conscious browsing. -a saves time in threads you know you'll read fully. The comment width flag (-c) adapts to your terminal size, preventing awkward line wraps on wide displays.

Example 3: Category Filtering for Focused Browsing

Control which HN categories appear in the header:

# Show only Ask HN and Show HN submissions
clx --categories="ask,show"

# Include newest stories alongside defaults
clx --categories="top,best,ask,show,new"

# Minimalist view: just top stories
clx --categories="top"

Explanation: The --categories flag curates your feed based on your goals. Ask HN reveals community wisdom. Show HN surfaces new projects. Best highlights high-engagement discussions. This filtering eliminates noise and helps you focus on content types that match your current mindset—perfect for time-boxed reading sessions.

Example 4: Keyboard Navigation Mastery

The keymap system is your gateway to efficient browsing:

# Essential Navigation
Enter      # Open comment section
Space      # Launch Reader Mode
Tab        # Cycle categories (top→best→ask→show→new)
r          # Refresh current category
o          # Open article in default browser
c          # Open comments in default browser
f          # Add to favorites
x          # Remove from favorites
q          # Quit application

# In Comment Section (less pager)
d/u        # Scroll half screen down/up
j/k        # Scroll one line down/up
h/l        # Hide/show comment replies
n/N        # Jump to next/previous top-level comment
?/i        # Show help overlay

Explanation: This dual-layer navigation keeps you productive. Global keys (Tab, r, f) work from the main view. Once inside comments, less keys take over. The h/l keys for collapsing threads are game-changers for long discussions—they let you skim structure before diving deep. Mastering n/N jumps helps you quickly sample top-level opinions before committing to full thread reading.

Advanced Usage & Best Practices

Optimize Your Less Configuration

Circumflex inherits your less settings. Enhance the experience by adding to ~/.bashrc or ~/.zshrc:

# Better syntax highlighting in less
export LESS='-R -M -I -X'

# -R: Allow raw control characters (enables colors)
# -M: Show detailed prompt with line numbers
# -I: Case-insensitive search
# -X: Don't clear screen on exit (preserves content)

Create Shell Aliases for Workflows

# Morning news routine
alias hn-morning='clx --categories="top,best" -c 80'

# Quick Ask HN wisdom
alias hn-ask='clx --categories="ask" -a'

# Privacy mode
alias hn-private='clx -d -t'

# Research mode: save everything
alias hn-research='clx -n -c 90'

Integrate With Your Editor

Vim users can open HN submissions directly:

" In .vimrc
command! HN :!clx comments <args>

" Usage: :HN 12345

Performance Optimization

For slow connections, disable syntax highlighting temporarily:

clx -o -p  # Plain comments and headlines

This reduces rendering time significantly while maintaining core functionality.

Comparison: Circumflex vs. Alternatives

Why Circumflex Wins: While haxor-news offers basic CLI access, it lacks the refined UX that makes circumflex addictive. The Reader Mode alone justifies the switch—no other terminal HN client extracts article content. Compared to browsers, circumflex eliminates distractions and reduces memory usage by 97%. It's the only tool that treats HN as a first-class citizen of the terminal ecosystem.

Frequently Asked Questions

What makes circumflex different from other HN clients?

Circumflex is the only terminal HN reader with integrated Reader Mode, intelligent syntax highlighting, and seamless less integration. While alternatives provide basic browsing, circumflex delivers a complete reading experience that respects your terminal workflow and color scheme.

Can I use circumflex without Nerd Fonts?

Absolutely. Nerd Fonts support is optional via the -n flag. Without it, circumflex uses clean ASCII characters that look great in any terminal. The core functionality remains identical—icons are purely aesthetic enhancements.

How do I fix "less version too old" errors?

Update less to version 590 or newer:

# macOS
brew install less

# Ubuntu/Debian
sudo apt update && sudo apt install less

# Verify
less --version  # Should show 590+

Is my browsing history private?

History stores locally in ~/.cache/circumflex/history.json. No data leaves your machine. Use clx -d to disable tracking entirely, or clx clear to wipe history on demand. The project is open-source—audit the code for complete transparency.

Can I customize the color scheme?

Circumflex automatically adapts to your terminal's colors. For advanced customization, modify your terminal theme. The application uses standard ANSI colors, so any theme change reflects instantly. No separate config files needed.

How does favorites storage work?

Favorites live in ~/.config/circumflex/favorites.json as pretty-printed JSON. This format is:

• Human-readable: Edit with any text editor
• VCS-friendly: Commit to your dotfiles repository
• Portable: Sync across machines via Git or Dropbox
• Robust: Never loses data on crashes

What if a website doesn't work with Reader Mode?

Circumflex maintains a blacklist of domains with known incompatibilities. For these sites, Reader Mode simply won't activate—press o to open in your default browser instead. The list updates regularly, and you can contribute fixes via GitHub issues.

Conclusion: Reclaim Your Focus Today

Circumflex isn't just another HN client—it's a statement about how developers should consume information. In a world of infinite browser tabs and attention-grabbing UIs, this tool returns you to the fundamentals: keyboard-driven, distraction-free, and blazingly fast.

The combination of Reader Mode, intelligent caching, and native terminal integration creates an experience that feels like it was always meant to be. Whether you're researching a new technology, staying current with industry news, or simply enjoying quality discussions, circumflex keeps you in your terminal—where real work happens.

I've personally replaced my morning HN ritual with clx and reclaimed 30 minutes of daily productivity. No more falling into browser rabbit holes. No more context switching. Just pure, focused content consumption.

Ready to transform your Hacker News experience?

⭐ Star the repository to support development: github.com/bensadeh/circumflex

🚀 Install now with brew install circumflex and join thousands of developers who've already made the switch.

The terminal is your home. It's time your news reader lived there too.