Steeper

TUI client for software forges — browse repositories, issues, pull requests, and track activity from the terminal.

Installation

git clone https://git.lan.thwap.org/thwap/steeper.git
cd steeper
go build -o steeper ./cmd/steeper

Quick Start

./steeper config init

Edit ~/.config/steeper/config.toml:

default_forge = "default"

[[forge]]
name  = "default"
url   = "https://git.example.com"
token = "your-api-token"
type  = "forgejo"

Then launch:

./steeper

Or open directly into a repo from its directory:

cd ~/projects/my-repo
steeper .

CLI Commands

Command	Description
steeper	Launch TUI (defaults to home dashboard)
steeper home	Open home dashboard explicitly
steeper .	Auto-detect repo from .git dir and open it
steeper repos	Launch directly to repos tab
steeper issues	Launch directly to issues tab
steeper issues --state closed	Launch issues filtered by state
steeper pr	Launch directly to pull requests tab
steeper pr --state open	Launch PRs filtered by state
steeper config show	Show current configuration
steeper config init	Create default config file
steeper --forge <name>	Use the named forge from config (overrides default)

Key Bindings

Global (all tabs)

Key	Action
1-4	Switch tab (home, repos, issues, pulls)
Enter	Open / select / drill down
Alt+?	Help modal
Alt+F	Open forge selector (switch between configured forges)
Ctrl+L	Force redraw screen
Ctrl+R	Refresh data for current view
Ctrl+Q	Quit

Home Dashboard

Key	Action
—	Displays contribution heatmap and activity feed
Alt+S	Open activity dashboard (PR/issue/contribution sparklines)
(read-only view, uses nav keys to switch tabs)

Repos Tab

Key	Action
Enter	Browse repository contents (file listing + README)

Repo Detail View (after Enter on a repo)

Key	Action
Tab	Cycle focus between file listing and README panes
Bks / Esc	Return to repo list
Alt+A	View action/workflow runs (Enter for details)
Alt+S	Open repo activity dashboard (sparklines + heatmap)
Alt+B	View branches
Alt+C	View commit history (Enter for diff)
Alt+I	View issues for this repo (Alt+O toggles open/closed)
Alt+M	View milestones
Alt+P	View pull requests (Alt+O open, Alt+C closed)
Alt+T	View tags

Diff Viewer (PR diffs, commit diffs)

Key	Action
q / Esc / Bks	Close
Space	Page down
g	Go to top
G	Go to bottom
n	Next diff hunk
N	Previous diff hunk

Issues Tab

Key	Action
Enter	Open issue detail (body + comments)
Alt+O	Show only open issues
Alt+C	Show only closed issues

Pulls Tab

Key	Action
Enter	Open PR detail (body + files + diff)
Alt+O	Show only open PRs
Alt+C	Show only closed PRs
Alt+D	Open dedicated diff viewer
n / N	Next / previous diff hunk

Features

• Home dashboard — landing view showing a contribution heatmap (12-month GitHub-style graph) and recent user activity feed
• Kanagawa Wave theme — dark, low-contrast color scheme
• Multi-forge support — configure multiple forges and switch between them at runtime with Alt+F
• Pagination — all list views fetch complete data across all API pages
• Totals bar — summary counts displayed in tab bar header
• Repo columns — PR and issue tables show which repo each item belongs to
• Open-first sorting — open items listed first with a divider, bold highlighted
• Markdown rendering — issue/PR bodies and READMEs rendered with glamour
• Syntax highlighting — diff and source code highlighted with chroma
• Resizable modals — all overlays respond to terminal resize
• Client-side filtering — instant state toggling without API calls
• Activity dashboard — fullscreen modal showing 7-day activity heatmap, PR/issue/contribution sparklines with Braille UTF-8 rendering, and auto-refresh (5 min interval)
• Offline resilience — renders cached data with stale indicator when offline; recovers from corrupted cache automatically
• Auto-refresh — home dashboard refreshes every 30 seconds

Environment Variables

Variable	Description	Default
STEEPER_CONFIG	Path to config file	~/.config/steeper/config.toml
STEEPER_MAX	Max contributions per cell in heatmap (higher = less granular)	7

Configuration

See DESCRIPTION.md for forge connection setup for Gitea, Forgejo, and Codeberg.

Dependencies

• tview — TUI framework
• tcell — terminal handling
• glamour — markdown rendering
• chroma — syntax highlighting
• go-git — local git repository parsing
• urfave/cli — CLI framework
• modernc.org/sqlite — pure-Go SQLite for local activity cache

Development

# Install pre-commit hooks
pre-commit install

# Run tests
go test ./...

# Run linter
golangci-lint run ./...