forgetop #

A fast, keyboard-driven command center for your pull requests, work items, and CI pipelines — in one place.

Across GitHub, GitLab, Azure DevOps, Bitbucket, Linear, and Jira. Triage and act on everything without tab-hopping between forges, as a terminal UI and a web dashboard.

• GitHub
• GitLab
• Azure DevOps
• Bitbucket
• Linear
• Jira

This is the full reference. For install and a 60-second start, see the README.

forgetop --demo

What forgetop does #

A short inventory of the whole app, before the section-by-section detail.

• The Command Center — the default landing screen: one cross-provider action inbox that triages every PR, work item, and pipeline into "what needs you", so you start on your queue instead of scrolling three separate lists.
• Terminal or browser — the same app as a keyboard-driven TUI and a local web dashboard, opened together by default. Everything below works in both.
• Three sections in one dashboard — Pull Requests, Work Items, and Pipelines, each a tab you can act on.
• Six forges — GitHub, GitLab, Azure DevOps, Bitbucket, Linear, and Jira, plus a built-in --demo.
• Cross-provider aggregation — bind several connections to a section and their items merge into one list, tagged by provider. All your PRs across GitHub and GitLab and Azure, in a single view.
• Do work, not just watch it — approve / request changes / merge / comment on PRs, change work-item states, re-run or cancel pipeline runs — all from the keyboard.
• Real code review — a full-screen PR view with Conversation, Commits, Checks, and Diff tabs; syntax-highlighted diffs grouped by directory, per-file viewed checkboxes, thread jump-navigation, a line cursor in the patch; inline line comments buffered locally then submitted as one review (Comment / Approve / Request changes); replying in-thread to someone else's comment; and an event timeline of who approved / requested changes / merged / commented.
• Pipeline drill-in — expand stages → jobs → steps with per-node durations, failure reasons, a scrollable logs pane, and open-in-browser.
• Pipeline actions — from a run's detail pane, re-run a failed run or cancel a running/queued one (GitHub, GitLab, Azure DevOps, Bitbucket).
• Pipeline approvals — see which runs are blocked on a gate (red Approval needed); acting on a gate is available in the terminal (GitHub, Azure DevOps, GitLab).
• Filter, sort, and shape — a live quick-filter, per-column sorting, work-item state visibility, and pipeline subscriptions — all remembered per view.
• Command palette (Ctrl-P) — fuzzy-jump to any PR, work item, or pipeline across every provider from one search box, without scrolling or switching tabs.
• Notification inbox (i) — your cross-provider notification stream (reviews, mentions, CI failures, assignments) in one list, with a top-left unread indicator; Enter drills straight into the item. GitHub, GitLab, and Linear.
• Saved views — bundle a filter + sort + state into a named view and flip between them from an always-visible view bar ([ / ]).
• Desktop notifications — get pinged when a pipeline fails, a review is requested, or your PR is approved / gets changes requested — across every connected provider.
• Secure by default — tokens live in your OS keychain; the config file only ever holds a reference.

Core concepts #

Sections, connections, capabilities — and where your tokens actually live.

Sections and bindings #

forgetop has three sections: Pull Requests, Work Items, and Pipelines. Each is bound to one or more connections (a configured account on a forge). A section only shows data from the connections bound to it. You manage connections and bindings in the web dashboard — press C in the TUI to open it.

Providers and capabilities #

Each provider advertises capabilities — which sections it can serve. A connection only ever offers what it can actually do, so the UI never dangles a dead option:

Cross-provider aggregation #

Every section aggregates. Bind two or more connections to Pull Requests (or Work Items, or Pipelines) and their items merge into a single list with a Provider column so you can tell them apart. Filtering, sorting, and actions all work across the combined list — and each action targets the row's own provider, so approving a GitLab MR and merging a GitHub PR just work from the same screen.

Try it live: forgetop --demo seeds two demo connections so you can see the merged lists immediately.

Security #

Tokens are written to the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service). The JSON config only stores a reference to each token — never the secret itself. For headless use you can supply a token via an environment variable instead (see Configuration).

The web dashboard is served on 127.0.0.1 only, gated by a per-session token carried in its URL. Because its API can act on your behalf (merge a PR, change a state), it never listens off-loopback and never accepts cross-origin requests; the token is never returned by the API, written to config, or logged.

Getting started #

Try it with the built-in demo, then point it at your own accounts.

Try it with no setup — everything is in memory, nothing is written:

forgetop --demo

Then run it for real:

forgetop

This opens the terminal UI and the web dashboard together (the default). On first launch — before any connection has a token — the dashboard drops into a quick setup: pick a provider, paste a token, choose which sections it feeds. Tokens go to your OS keychain and are shared straight back to the terminal. Press C in the TUI (or open the dashboard's Settings) to manage connections any time, and ? shows every keybinding. See Web dashboard for the run modes.

Diagnosing setup #

If a connection isn't working, run the diagnostic — it checks the config location, keychain access, and each connection's token + connectivity, without opening the UI:

forgetop doctor

It prints a line per connection (✓ healthy, ⚠ no token, ✗ token present but auth failed), so you can see at a glance whether it's a missing token, a bad scope, or an expired credential.

Command-line options #

Web dashboard #

The same app in a browser, built into the binary and served on loopback.

forgetop ships the same app as a local web dashboard — the Command Center, all three lists, PR review with an inline-comment diff viewer, the command palette, sort/filter, themes, and every write action (approve, merge, comment, submit a review, change a work-item state, approve a pipeline gate, retry a run, mark a notification read). It's a React app built into the binary and served by forgetop itself — no separate install, no external network.

The terminal UI and the dashboard are two frontends over one core, so they show the same data, act through the same providers, and share the same config + keychain — a connection or a setting changed in one shows up in the other.

Opening it #

• From the TUI: press B (shown in the footer and ? help on every screen).
• Give feedback: use the dashboard button beside connection health, or press F in the TUI. Both open the public GitHub feedback issue form; forgetop does not send logs or credentials.
• Headless: forgetop --dashboard serves it and opens your browser — no TTY, so it's handy over SSH with a forwarded port.

Connections & settings #

Connection setup lives in the dashboard's Settings page: add a provider from a form tailored to it, paste a token (stored in the OS keychain), tick which sections it feeds, and Test / Edit / Delete it. First launch with nothing set up opens this automatically. Pressing C in the TUI jumps straight here.

Security #

The server binds 127.0.0.1 only and gates its API with a per-session token in the URL — see Security.

Command Center #

The landing screen: everything that needs you, from every provider, on one page.

The Command Center is the screen forgetop opens on. Instead of browsing by type, it answers one question — what needs me right now? — by pulling every PR, work item, and pipeline across every connected provider into a single, prioritised page. The Pull Requests / Work Items / Pipelines views are still there as drill-downs.

It's split into two columns:

• Needs you (left) — things ripe for action now, in urgency order:
  • Needs your review — PRs where you're a requested reviewer.
  • Approvals waiting — pipeline runs blocked on a gate you can approve.
  • Ready to merge — your PRs that are approved, mergeable, and green.
  • Needs fixing — your PRs with changes requested / failing checks / conflicts, and failed pipeline runs.
• Your work (right) — your own things:
  • Assigned to you — work items assigned to you.
  • Your open pull requests — the full list of your open authored PRs (a PR that's also an action item on the left still appears here; this is the complete list).
  • Recently merged — your PRs merged in the last few days.

Every row is laid out on one aligned grid so PRs, pipelines (CI), and work items (WI) read as siblings: a coloured type badge, a status signal (a PR shows its review state — ✓ ok, ○ review, ✗ changes, ◌ draft; a pipeline its run status; a work item its state), a short #ref, the title, one type-specific detail (PR +/-, pipeline branch, work-item type), the provider, and the age (which reddens once it's stale). For pipelines the title is the pipeline name (e.g. CI Build) and the ref is the run/release (e.g. 10.1.100).

Pull Requests #

Find a pull request in the list; do the review work inside it.

Work Items #

The items assigned to you, with state transitions pulled from the provider.

The Work Items view shows only items assigned to you — each provider resolves the current user from your token (@me, currentUser(), isMe, …), so there's nothing to configure.

Pipelines #

Runs, a stages → jobs → steps drill-in, logs, re-runs, and approval gates.

Each entry is a run, tagged with its pipeline (definition) name — e.g. CI Build or CD (Release) — and its own run name or release (e.g. 10.1.100, or its number when it has none).

Approvals #

When a run is blocked on a manual gate — a GitHub environment required-reviewer, an Azure DevOps approval check, or a GitLab manual job — forgetop surfaces it, refreshed on the normal poll (and you can opt into a desktop notification when a gate first appears):

Acting is capability-scoped:

• GitHub / GitLab — approve or reject in-app (on GitLab a reject cancels the manual job).
• Azure DevOps — view-only: the pending gate is surfaced, but Azure doesn't expose the environment check as an actionable approval over the API, so there's no A action — approve it in the Azure UI.
• Bitbucket — approvals aren't surfaced at all (its API can't resume a paused manual step); the run shows an explicit "not supported" note.

Filtering and sorting #

Cut a busy view down, and keep the shape you chose.

Command palette #

Fuzzy-jump to any loaded PR, work item, or pipeline from one box.

The command palette is a fuzzy jump across everything already loaded: every PR, work item, and pipeline, from every connected provider, in one list. Type to filter (matching the title, author, branch, identifier, or connection); each row carries a status dot in the usual green/blue/red/grey colours. It searches only what's loaded — no network round-trip — so it's instant.

Notification inbox #

What just happened, aggregated across every provider that reports it.

The notification inbox is your notification stream aggregated across providers: review requests, @mentions, assignments, CI failures, comments, and state changes, newest first. It answers what just happened, where the Command Center answers what needs me now. A Notifications nav item carries an unread count that stands out when something's waiting.

Provider support. The inbox is fed by the providers that expose a personal notification feed:

Azure DevOps, Bitbucket, and Jira don't offer a personal notification feed in their APIs, so connections for those providers simply don't contribute to the inbox. (This is separate from desktop notifications, which is about which events fire an OS ping.)

Saved views #

Bundle a filter, a sort, and a state set into a named view.

Notifications #

Native desktop pings for the events you opt into.

forgetop raises native desktop notifications on the events you choose:

• Pipeline failed — a run transitions into a failed state.
• Pipeline approval needed — a run first starts waiting on a gate you can approve.
• Review requested — you're newly a requested reviewer on a PR.
• Your PR approved / changes requested — a reviewer votes on a PR you authored.

Press N anywhere to open a checklist and opt in/out of each event; the choice is persisted. Detection is seeded on load (no startup spam), de-duped, and re-seeded when you change settings — and enabling fires one confirmation notification so you can verify it works on your machine. Every event spans all bound providers, not just the first.

Keybindings #

Every key, grouped by the screen it belongs to.

forgetop shows a context-aware key glossary along the bottom — it only lists the keys valid for where you are. Press ? for the full panel. The complete set:

Global #

Command Center #

Saved views #

Pull Requests (list) #

Inside the PR view #

Work Items #

Pipelines #

Connections (terminal fallback) #

Connection management lives in the web dashboard — C opens it and also shows a connections list in the terminal. That list still supports the original keys as a fallback:

Configuration #

Where config lives, how tokens are stored, and what gets logged.

Config is a small JSON file, created and managed for you:

It never contains secrets — only a reference to each token in the keychain, plus your bindings and view preferences (saved views, sorts, hidden states, notification choices).

Tokens #

You add connections and paste tokens in the dashboard's Settings page (see Web dashboard); each token is stored in your OS keychain under the service name forgetop. In headless environments (CI, containers) you can instead supply a token via an environment variable named FORGETOP_PAT_<CONNECTION_ID> (uppercased; non-alphanumeric characters become _).

Logs & diagnostics #

forgetop keeps rolling diagnostic files next to your config — forgetop.log and its numbered segments in the same directory (e.g. ~/.config/forgetop/). The retained history is limited to approximately the latest 24 hours and never more than 3 MiB; under heavy logging, the size limit wins. It records:

• Crashes — if forgetop ever panics it restores your terminal (no garbled screen), writes the panic to the log, and prints the path so you can send it on.
• Errors — a failed action (approve / merge / comment / trigger / …) and background provider / auth / network fetch failures, which otherwise only flash on screen — each timestamped, so intermittent issues are reviewable after the fact.

forgetop doctor prints the active log's path. Logging is best-effort and redacts common credential headers, token fields, credential-bearing URLs, dashboard session tokens, and known provider-token formats. Request/response bodies and configuration contents are not intentionally logged, but you should still inspect diagnostics before sharing them manually. forgetop never attaches them to the GitHub feedback form.

The running version is shown in the header (▟ forgetop v…) and via forgetop --version, so it's easy to include when reporting an issue.

Token scopes #

Themes #

Four built-in themes, remembered per surface.

Four built-in themes — slate (default), dark, light, and matrix. In the terminal, cycle with t (256-colour palettes, so they render correctly on every terminal, including ones without truecolor); in the web dashboard, use the theme toggle in the sidebar footer. Each side remembers your choice (the dashboard's per browser).

How it works #

A Rust workspace: core, providers, terminal UI, server, CLI.

forgetop is a Rust Cargo workspace:

A few design ideas hold it together:

• Capability-scoped traits. Providers implement PullRequestSource, WorkItemSource, and/or PipelineSource — only what they support. The core never assumes a provider can do something it can't, which is how a Linear connection appears for Work Items but not Pull Requests.
• Sections resolve to feeds. A section binds to a set of connections; the service resolves each to a live source (a "feed"). Aggregation is just iterating every feed and tagging each item with its connection — the same shape for PRs, Work Items, and Pipelines.
• Config never holds secrets. The config service persists bindings and preferences and stores only a credential_ref per connection; the actual token lives in the OS keychain via a separate secret store.
• Immediate-mode UI, own input loop. The TUI owns a dedicated input reader thread feeding a tokio loop, and redraws the whole frame each tick — so there are no framework focus fights, and every keystroke is dispatched explicitly.

Development #

Build it, test it, run it from source.

cargo test        # run the test suite
cargo clippy      # lint
cargo run -- --demo

Source: github.com/magna-nz/forgetop.