Open Source Terminal GUI
ShellFrame
An AI terminal anyone can pick up.
Born from a designer's need. Now the whole team uses it.
Origin Story
My collaborator is a designer. She watched me fly through tasks with Claude Code and Codex in the terminal and wanted to try it herself. But she immediately hit a wall: you can't paste images in a terminal.
IDEs like Windsurf and Cursor let you paste screenshots directly to ask AI questions, but the raw terminal can't do that. Having to save an image, type out the file path, then reference it — that single extra step killed the motivation.
So I built a ultra-lightweight GUI wrapper — not Electron-heavy, but Python + native OS WebView. Fast startup, tiny memory footprint. Cmd+V to paste images, multi-tab to manage different projects, and a Telegram bridge for remote access from your phone.
After completing it, I introduced ShellFrame to my colleagues. Designers and PMs benefited just as much. They no longer had to face the intimidating black-and-white terminal — ShellFrame lowered the barrier to AI CLI tools down to "if you can use a chat app, you can use this."
Problem & Solution
The Problem
- x Terminals can't paste images
- x Non-engineers fear command lines
- x Can't use AI tools away from desk
- x Electron is bloated, VS Code is overkill
The Solution
- > Cmd+V to paste screenshots instantly
- > Clean GUI with one-click presets
- > Telegram bridge for mobile access
- > Native WebView — lightweight & fast
Key Features
📋
Smart Paste
Cmd+V to paste screenshots or multiple files. Since v0.11.9, file paths are wrapped in bracketed-paste escapes so Claude Code / Codex recognize them as attachments and collapse them into [image #N] — not typed characters.
📑
Multi-Tab + tmux Persistence
Each tab runs inside a tmux session (Unix) or uses soft persistence (Windows). Close the window, reopen — conversations resume where you left off. Window geometry also persists across restarts.
🎛
sfctl Master Orchestration
Since v0.11.0: sfctl new / send / peek / rename / close / list. One master Claude session can spin up workers, dispatch tasks, poll results, and clean up — parallel-agent workflows native to ShellFrame, no tmux fiddling.
📱
Telegram Bridge
One bot manages all sessions. Text, images, files, voice messages (STT) flow both ways. Commands: /list /new /fetch /pause /reload /restart /update /close. Destructive ones require inline confirm.
🔴
AI Busy Indicator
Each session shows a status dot — orange when working, pink when waiting on your input (Claude permission dialogs, Codex exec confirms). A glance tells you who's busy and who's blocked on you.
📜
Clean Scroll History
tmux copy-mode captures every intermediate streaming frame, making scrollback look like the same line pasted 20 times. v0.11.0–0.11.5 replaces it with an xterm.js overlay + prefix-dedup + CJK-width dedup — streaming Claude Code / TUI scrollback stays clean, ANSI colors preserved.
🎙
Voice / STT
Voice messages from TG are transcribed and sent into the session. Plugin-first architecture: local whisper.cpp, custom HTTP server, or your own Python plugin — never tied to a single cloud provider.
🧠
AI Context + Editable Prompts
Claude / Codex sessions start with environment context auto-injected (active sessions, bridge state, sfctl command reference). Since v0.11.8, the init prompt and per-turn TG preamble are both editable from Settings.
🛡
sfctl permissions
v0.11.8 adds a one-shot subcommand. macOS: opens Privacy panes (Files & Folders, Accessibility, Automation, etc.) + whitelists python/bun in ALF. Windows: adds Defender inbound allow rules for the bundled Python. Run once post-install.
🔄
Two-Tier Reload + Merged /update
UI changes hot-reload; Python changes trigger a restart with session preservation. v0.10.12 folded /update_now into /update with an inline-keyboard "⬇️ Update Now / Cancel" when a new release is detected.
⌨️
Input Ergonomics
Shift+Enter for newlines without send, right-click CMD-style copy/paste, Esc to clear input (plain terminals), Ctrl+Click to open file paths (even hard-wrapped URLs), and S / M / L UI scale.
⚡
Global Hotkey ⌃⌥Space
Since v0.11.27. Press Ctrl+Option+Space from any app to summon ShellFrame; press again to hide. Spaces-aware: the window moves to your current virtual desktop instead of pulling you away. Toggle in Settings. macOS only for now.
🧹
Auto /compact
Since v0.11.26. Bridge monitors Claude Code's token gauge in real time. When remaining context drops below the threshold (default 15%), it auto-sends /compact to summarize context and free tokens. Threshold configurable in Settings. Claude-only — never fires on Codex / bash.
🔔
Completion Notifications
Since v0.11.29. When ShellFrame is in the background, a native macOS notification pops up the moment an AI session finishes its reply. Click the banner to jump straight back. 30s per-session cooldown to avoid spam. Toggle in Settings.
🌐
Cross-Platform + i18n
macOS (WKWebView + tmux persistence), Windows (Edge WebView2 + ConPTY + soft persistence), Linux (GTK WebView). Auto-detects OS language (en / zh-TW), switchable in Settings.
Tech Stack
Frontend
xterm.js terminal
Native OS WebView
Zero Electron dependency
Backend
Python + pywebview
PTY / ConPTY
WebSocket communication
Bridge
Telegram Bot API
Multi-session routing
Zero dependencies (urllib)
Deploy
One-line install script
Git-based auto-update
macOS .app bundle
Making AI Tools Belong to Everyone
Claude Code and Codex are powerful AI tools, but they live inside the terminal — for non-engineers, that's an invisible wall.
ShellFrame tears that wall down.
When a designer can paste a screenshot to ask AI about layout.
When a PM can use Telegram to ask AI to organize data remotely.
When a new hire doesn't need to learn the command line to start using AI.
That's what tools should be: serving people, not the other way around.
v0.11.34
Open Source MIT — macOS / Windows / Linux
17 stars · 3 forks
What's in v0.11.34