ShepAlderson · ShepAlderson · Jan 21, 2026 · Jan 21, 2026 · Jan 21, 2026 · Jan 21, 2026
diff --git a/.ralph-tui/config.toml b/.ralph-tui/config.toml
@@ -16,4 +16,4 @@ prompt_template = "ralph-prompt.hbs"
   name = "claude"
   plugin = "claude"
   default = true
-  options = { model = "sonnet" }
+  options = { model = "opus" }
diff --git a/.ralph-tui/iterations/iteration-001-US-001.log b/.ralph-tui/iterations/iteration-001-US-001.log
diff --git a/.ralph-tui/iterations/iteration-002-US-002.log b/.ralph-tui/iterations/iteration-002-US-002.log
diff --git a/.ralph-tui/iterations/iteration-003-US-004.log b/.ralph-tui/iterations/iteration-003-US-004.log
diff --git a/.ralph-tui/iterations/iteration-004-US-003.log b/.ralph-tui/iterations/iteration-004-US-003.log
diff --git a/.ralph-tui/iterations/iteration-005-US-005.log b/.ralph-tui/iterations/iteration-005-US-005.log
diff --git a/.ralph-tui/iterations/iteration-006-US-006.log b/.ralph-tui/iterations/iteration-006-US-006.log
diff --git a/.ralph-tui/iterations/iteration-007-US-007.log b/.ralph-tui/iterations/iteration-007-US-007.log
diff --git a/.ralph-tui/iterations/iteration-008-US-008.log b/.ralph-tui/iterations/iteration-008-US-008.log
diff --git a/.ralph-tui/iterations/iteration-009-US-009.log b/.ralph-tui/iterations/iteration-009-US-009.log
diff --git a/.ralph-tui/iterations/iteration-010-US-013.log b/.ralph-tui/iterations/iteration-010-US-013.log
diff --git a/.ralph-tui/iterations/iteration-011-US-010.log b/.ralph-tui/iterations/iteration-011-US-010.log
diff --git a/.ralph-tui/iterations/iteration-012-US-011.log b/.ralph-tui/iterations/iteration-012-US-011.log
diff --git a/.ralph-tui/iterations/iteration-013-US-012.log b/.ralph-tui/iterations/iteration-013-US-012.log
diff --git a/.ralph-tui/iterations/iteration-014-US-014.log b/.ralph-tui/iterations/iteration-014-US-014.log
diff --git a/.ralph-tui/progress.md b/.ralph-tui/progress.md
diff --git a/.ralph-tui/session-meta.json b/.ralph-tui/session-meta.json
@@ -1,15 +1,15 @@
 {
-  "id": "6700ace9-747a-479d-87d7-2d919e1e4bff",
+  "id": "d4c4d3d6-681c-4d11-8c00-3ceed9e36a8e",
   "status": "completed",
-  "startedAt": "2026-01-19T18:22:32.322Z",
-  "updatedAt": "2026-01-19T18:22:38.081Z",
+  "startedAt": "2026-01-21T22:12:42.652Z",
+  "updatedAt": "2026-01-22T00:31:38.750Z",
   "agentPlugin": "claude",
   "trackerPlugin": "json",
   "prdPath": "./tasks/prd.json",
-  "currentIteration": 0,
-  "maxIterations": 10,
+  "currentIteration": 14,
+  "maxIterations": 20,
   "totalTasks": 0,
-  "tasksCompleted": 0,
+  "tasksCompleted": 14,
   "cwd": "/Users/shepbook/git/github-issues-tui",
-  "endedAt": "2026-01-19T18:22:38.081Z"
+  "endedAt": "2026-01-22T00:31:38.750Z"
 }
diff --git a/README.md b/README.md
@@ -0,0 +1,256 @@
+# ghissues
+
+A terminal user interface (TUI) for browsing GitHub issues offline. Sync issues from any GitHub repository to a local database and browse them with a fast, keyboard-driven interface.
+
+## Features
+
+- **Offline browsing** - Sync issues once, browse anytime without internet
+- **Interactive setup** - First-run wizard configures repository and authentication
+- **Multiple auth methods** - Environment variable, config file, or GitHub CLI
+- **Split-panel interface** - Issue list with detail view side-by-side
+- **Markdown rendering** - View issue bodies and comments with full markdown support
+- **Comments drill-down** - Browse all comments in a full-screen view
+- **Configurable display** - Choose which columns to show and how to sort
+- **6 color themes** - Default, Dracula, Gruvbox, Nord, Solarized Dark/Light
+- **Multi-repository support** - Configure and switch between multiple repos
+- **Auto-refresh** - Syncs on startup with manual refresh available
+
+## Prerequisites
+
+- Go 1.21 or later
+- A GitHub account with access to the repository you want to browse
+- One of the following for authentication:
+  - `GITHUB_TOKEN` environment variable
+  - GitHub CLI (`gh`) installed and authenticated
+  - A personal access token
+
+## Installation
+
+### From Source
+
+```bash
+git clone https://github.com/your-username/github-issues-tui.git
+cd github-issues-tui
+go build -o ghissues ./cmd/ghissues
+```
+
+### Install to GOBIN
+
+```bash
+go install ./cmd/ghissues
+```
+
+This installs the binary to your `$GOBIN` directory (usually `~/go/bin`).
+
+## Quick Start
+
+1. **Run the application:**
+   ```bash
+   ghissues
+   ```
+
+2. **Complete the setup wizard:**
+   - Enter the repository in `owner/repo` format
+   - Choose your authentication method
+   - Optionally specify a custom database path
+
+3. **Browse issues:**
+   - Use `j/k` or arrow keys to navigate
+   - Press `Enter` to view comments
+   - Press `?` for help
+
+## Usage
+
+### Commands
+
+```bash
+ghissues              # Launch TUI (runs setup on first use)
+ghissues sync         # Sync issues without launching TUI
+ghissues config       # Re-run the setup wizard
+ghissues themes       # List available themes
+ghissues repos        # List configured repositories
+```
+
+### Command Flags
+
+```bash
+ghissues --repo owner/repo    # Use a specific repository
+ghissues --db /path/to.db     # Use a specific database file
+```
+
+### Theme Management
+
+```bash
+ghissues themes                    # List all available themes
+ghissues themes --preview dracula  # Preview a theme
+ghissues themes --set dracula      # Set the active theme
+```
+
+### Repository Management
+
+```bash
+ghissues repos                           # List configured repos
+ghissues repos --add owner/repo          # Add a new repository
+ghissues repos --set-default owner/repo  # Set the default repository
+```
+
+## Keybindings
+
+### Issue List View
+
+| Key | Action |
+|-----|--------|
+| `j` / `↓` | Move down |
+| `k` / `↑` | Move up |
+| `Enter` | View comments |
+| `r` / `R` | Refresh issues |
+| `s` | Cycle sort field |
+| `S` | Toggle sort order |
+| `m` | Toggle markdown rendering |
+| `h` / `l` | Scroll detail panel |
+| `?` | Show help |
+| `q` / `Ctrl+C` | Quit |
+
+### Comments View
+
+| Key | Action |
+|-----|--------|
+| `j` / `↓` | Scroll down |
+| `k` / `↑` | Scroll up |
+| `Esc` / `q` | Return to list |
+
+## Configuration
+
+Configuration is stored in `~/.config/ghissues/config.toml`.
+
+### Full Configuration Example
+
+```toml
+# Default repository to use
+default_repository = "owner/repo"
+
+# Multiple repositories can be configured
+[[repositories]]
+  name = "owner/repo"
+  database_path = ".owner-repo.db"
+
+[[repositories]]
+  name = "another/repo"
+  database_path = ".another-repo.db"
+
+# Authentication settings
+[auth]
+  method = "env"    # "env", "token", or "gh"
+  # token = "ghp_xxx..."  # Only needed if method = "token"
+
+# Database settings
+[database]
+  path = ".ghissues.db"  # Default database path
+
+# Display preferences
+[display]
+  columns = ["number", "title", "author", "date", "comments"]
+  sort_field = "updated"  # "updated", "created", "number", "comments"
+  sort_order = "desc"     # "desc" or "asc"
+  theme = "default"
+```
+
+### Authentication Methods
+
+Authentication is resolved in priority order:
+
+1. **Environment variable** (`method = "env"`)
+   - Uses the `GITHUB_TOKEN` environment variable
+   - Recommended for security
+
+2. **Config file token** (`method = "token"`)
+   - Stores token directly in config file
+   - Set `token = "ghp_..."` in the `[auth]` section
+
+3. **GitHub CLI** (`method = "gh"`)
+   - Uses `gh auth token` to retrieve the token
+   - Requires GitHub CLI to be installed and authenticated
+
+### Display Columns
+
+Available columns for the issue list:
+- `number` - Issue number
+- `title` - Issue title
+- `author` - Issue author username
+- `date` - Created date
+- `comments` - Comment count
+
+### Themes
+
+Available themes:
+- `default` - Clean terminal colors
+- `dracula` - Dark purple-based theme
+- `gruvbox` - Warm retro colors
+- `nord` - Arctic blue colors
+- `solarized-dark` - Solarized dark theme
+- `solarized-light` - Solarized light theme
+
+## Database
+
+Issues are stored in a local SQLite-compatible database (LibSQL). By default, the database is created at `.ghissues.db` in the current directory, but this can be configured.
+
+### Database Location Priority
+
+1. `--db` command-line flag
+2. Repository-specific `database_path` in config
+3. `[database].path` in config
+4. Default: `.ghissues.db`
+
+### Data Storage
+
+The database contains:
+- **issues** - Issue metadata (number, title, author, body, dates, etc.)
+- **comments** - Issue comments with author and body
+- **metadata** - Sync timestamps and other metadata
+
+Only open issues are synced. When issues are closed or deleted on GitHub, they are removed from the local database on the next sync.
+
+## Development
+
+### Building
+
+```bash
+go build -o ghissues ./cmd/ghissues
+```
+
+### Running Tests
+
+```bash
+go test ./...
+```
+
+### Project Structure
+
+```
+├── cmd/ghissues/         # Application entry point
+├── internal/
+│   ├── auth/             # GitHub authentication
+│   ├── cmd/              # CLI commands (cobra)
+│   ├── config/           # Configuration loading/saving
+│   ├── db/               # Database operations
+│   ├── github/           # GitHub API client
+│   ├── setup/            # Interactive setup wizard
+│   ├── sync/             # Issue synchronization
+│   ├── themes/           # Color theme definitions
+│   └── tui/              # Terminal UI (bubbletea)
+├── go.mod
+└── go.sum
+```
+
+### Dependencies
+
+- [bubbletea](https://github.com/charmbracelet/bubbletea) - TUI framework
+- [lipgloss](https://github.com/charmbracelet/lipgloss) - Terminal styling
+- [glamour](https://github.com/charmbracelet/glamour) - Markdown rendering
+- [huh](https://github.com/charmbracelet/huh) - Interactive forms
+- [cobra](https://github.com/spf13/cobra) - CLI framework
+- [go-libsql](https://github.com/tursodatabase/go-libsql) - SQLite-compatible database
+
+## License
+
+MIT
diff --git a/cmd/ghissues/main.go b/cmd/ghissues/main.go
@@ -0,0 +1,15 @@
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/shepbook/ghissues/internal/cmd"
+)
+
+func main() {
+	if err := cmd.Execute(); err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		os.Exit(1)
+	}
+}
diff --git a/go.mod b/go.mod
@@ -0,0 +1,59 @@
+module github.com/shepbook/ghissues
+
+go 1.25.5
+
+require (
+	github.com/BurntSushi/toml v1.6.0
+	github.com/charmbracelet/bubbletea v1.3.10
+	github.com/charmbracelet/glamour v0.10.0
+	github.com/charmbracelet/huh v0.8.0
+	github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834
+	github.com/spf13/cobra v1.10.2
+	github.com/stretchr/testify v1.11.1
+	github.com/tursodatabase/go-libsql v0.0.0-20251219133454-43644db490ff
+)
+
+require (
+	github.com/alecthomas/chroma/v2 v2.14.0 // indirect
+	github.com/antlr4-go/antlr/v4 v4.13.0 // indirect
+	github.com/atotto/clipboard v0.1.4 // indirect
+	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
+	github.com/aymerick/douceur v0.2.0 // indirect
+	github.com/catppuccin/go v0.3.0 // indirect
+	github.com/charmbracelet/bubbles v0.21.1-0.20250623103423-23b8fd6302d7 // indirect
+	github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc // indirect
+	github.com/charmbracelet/x/ansi v0.10.1 // indirect
+	github.com/charmbracelet/x/cellbuf v0.0.13 // indirect
+	github.com/charmbracelet/x/exp/slice v0.0.0-20250327172914-2fdc97757edf // indirect
+	github.com/charmbracelet/x/exp/strings v0.0.0-20240722160745-212f7b056ed0 // indirect
+	github.com/charmbracelet/x/term v0.2.1 // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/dlclark/regexp2 v1.11.0 // indirect
+	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
+	github.com/gorilla/css v1.0.1 // indirect
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/libsql/sqlite-antlr4-parser v0.0.0-20240327125255-dbf53b6cbf06 // indirect
+	github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/mattn/go-localereader v0.0.1 // indirect
+	github.com/mattn/go-runewidth v0.0.16 // indirect
+	github.com/microcosm-cc/bluemonday v1.0.27 // indirect
+	github.com/mitchellh/hashstructure/v2 v2.0.2 // indirect
+	github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 // indirect
+	github.com/muesli/cancelreader v0.2.2 // indirect
+	github.com/muesli/reflow v0.3.0 // indirect
+	github.com/muesli/termenv v0.16.0 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/rivo/uniseg v0.4.7 // indirect
+	github.com/spf13/pflag v1.0.9 // indirect
+	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
+	github.com/yuin/goldmark v1.7.8 // indirect
+	github.com/yuin/goldmark-emoji v1.0.5 // indirect
+	golang.org/x/exp v0.0.0-20231006140011-7918f672742d // indirect
+	golang.org/x/net v0.33.0 // indirect
+	golang.org/x/sys v0.36.0 // indirect
+	golang.org/x/term v0.31.0 // indirect
+	golang.org/x/text v0.24.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)