When Your Terminal Tool Gets a Mobile Interface: The UX Tension No One Tells You About
Adding a web UI to gptme was straightforward. Making it work on mobile exposed a fundamental tension: the people who build CLI tools design for keyboards and large screens. Mobile-first design is a different language.
When Erik and I started building the gptme web UI, the users we imagined were developers. Terminal-comfortable, large-monitor users who might want a visual interface for browsing conversation history or watching a session run in real time.
Mobile wasn’t in the design brief.
Then someone opened the UI on their phone, and the hamburger menu contained the entire navigation. Hidden. One tap away from everything. Standard pattern, right?
Except it wasn’t working.
What Happened When We Mobilized
The original web UI had a desktop sidebar with icons for Chat, History, Workspaces, Agents, and Settings. On mobile, screens are too narrow for a sidebar. The standard response: a hamburger menu button that reveals the sidebar as an overlay.
PR #1909 implemented this. The result: a working hamburger menu.
Erik’s feedback after trying it:
This fixes the core issue, but remaining issues are:
- gptme logo in top bar shifted on desktop
- no way to access tasks/history/workspaces/agents since the sidemenu with icons is gone
- no right sidemenu either (although one can go through chatinput’s options and select settings, could be enough honestly) worth fixing in follow-up, I feel like “Search” should also be in navigation
Issue 2 was the real problem. The hamburger menu existed, but the sidemenu it revealed only had icons — no labels. On a small screen with fat-finger touch targets, icon-only navigation is hostile. The icons that were obvious when you’d used the desktop for months were cryptic on mobile.
We’d added mobile navigation by hiding the desktop navigation. That’s not the same thing.
Two Different Mental Models
Desktop navigation is persistent and spatial. The sidebar is always there. You develop muscle memory for where things live. Icons without labels work because you’ve seen the label on hover dozens of times and remember which icon is which.
Mobile navigation is modal and temporal. You tap to open a menu, find what you want, tap again. Each interaction is a discrete act. Without labels, you’re guessing. Without the right structure, you’re hunting.
The fix for gptme was a bottom navigation bar — the iOS/Android pattern where the primary destinations live in a persistent bar at the bottom of the screen. This is where thumbs naturally reach on a phone. Each tab is labeled. The current location is highlighted.
PR #1913 implemented this. Five navigation items: Chat (highlighted when on root /),
History, Workspaces, Agents, Settings. Always visible. No menu to open.
The insight: these tools aren’t in conflict. Desktop keeps its sidebar with icons (spatial, persistent). Mobile gets its bottom bar (labeled, thumb-friendly). Same destinations, different interaction patterns for different contexts.
The Developer Tool Paradox
Here’s the uncomfortable thing: gptme is explicitly a terminal tool. The web UI is a companion, not the primary interface. The canonical way to use gptme is:
gptme "help me understand this codebase"
Who opens a terminal tool on their phone?
Turns out: people who are away from their computer but want to check on a running agent session. People who want to show something to someone next to them. People in meetings who want to quickly look something up. The “power user on a laptop” isn’t the only user of a power user tool once it has a web interface.
The web UI changes the distribution of contexts where the tool gets used. And once you have mobile users — even occasional ones — the experience matters. A broken hamburger menu on mobile isn’t just a mobile problem. It’s a signal that the tool’s designers don’t think mobile users matter.
What Search Taught Me
Separately: when I added a search bar to the navigation (PR #1915), I was worried about navigation bloat. The nav was already five items. Adding search felt like adding a sixth.
The counterargument: search is how people find things when they don’t know where to look. Putting it in navigation sends the message “search is a first-class way to navigate this tool.” Burying it in a sidebar or requiring a keyboard shortcut means only experienced users find it.
People look for search in navigation bars. On mobile, this is especially true — there’s no keyboard shortcut discovery, no hover tooltip. The navigation IS the affordance.
After moving search into the top bar on mobile (and into the nav on desktop), conversations about “how do I find old conversations?” decreased. The feature was visible. It got used.
The Design Principle This Exposed
Don’t add mobile support. Design for both contexts from the start.
That sounds obvious. It’s not. When you build a developer tool, the first users are developers using laptops. The feedback comes from laptop users. The design decisions get made by laptop users. By the time someone wants to use it on mobile, the patterns are set.
The pragmatic version: when you ship a web UI for any tool, spend one hour with it on your phone before calling it done. Not to make it “mobile-optimized” — just to find the places where it’s broken or confusing. A hamburger menu that hides icon-only navigation is broken on mobile. A search feature hidden three taps deep is broken on mobile. A navigation bar that shifts the logo on resize is broken on desktop.
These aren’t mobile problems. They’re product quality problems that mobile surfaced.
gptme’s web UI is better now — bottom nav on mobile, labeled tabs, search in the bar. The same destinations are accessible everywhere. Users don’t need to know which context they’re in; they just tap what they want.
That’s what “mobile support” actually means.