Case Study · Terminal Systems Software
A terminal-first workspace orchestrator that unifies project management, command execution, tmux sessions, Git operations, and developer workflows into a single high-performance Go TUI application.
Vision
Centralizing project registries, process runners, and session orchestration into a unified terminal workspace engine.
Modern software engineering demands constant switching between terminal windows, Git repos, tmux tabs, Docker containers, shell scripts, and IDEs. Repeated directory navigation, manual session spawning, and command re-typing create significant cognitive friction and derail developer flow.
DevFlow acts as a single, keyboard-driven starting point for every coding session. It turns raw terminal tabs into a managed environment where developers register projects, launch multi-pane tmux layouts, stream background process logs, and inspect Git states seamlessly.
Goals
flowchart LR
subgraph Friction["Developer Friction Points"]
F1["Directory Navigation"]
F2["tmux Layout Spawning"]
F3["Git Status Checks"]
F4["Command Re-typing"]
end
subgraph Engine["DevFlow Terminal Engine"]
TUI["Bubble Tea Event Loop"]
Store[("Registry DB")]
Runner["Process Executor"]
end
subgraph Outcome["Automated Workflow"]
O1["1-Key Session Launch"]
O2["Live Log Streaming"]
O3["Unified Repository Insights"]
end
Friction --> Engine --> Outcome
Capabilities
Serves as the source of truth for all local repositories. Maintains persistent metadata including project name, description, absolute path, tech stack tags, favorite status, Git detection, Docker awareness, and custom run commands.
Built with Lip Gloss styling and Bubble Tea keyboard navigation. Displays project cards with real-time Git branch indicators, uncommitted change indicators, tech stack tags, and recent session history.
Executes project-specific scripts (e.g. go run ., docker compose up, npm run dev, make test) with live output streaming, execution history tracking, and environment variable injection.
Provides instant repository diagnostics without requiring manual git status calls. Tracks current branch, dirty working directory trees, unpushed commits, and ahead/behind remote divergence.
Uses tmux as the workspace layout manager. Automatically creates named sessions, attaches terminal clients, restores multi-pane windows, and isolates workspace environments per project.
Instant filtering across project names, tags, and languages. Features a dual-phase persistence model: initial human-readable JSON storage with seamless migration to ACID-compliant SQLite storage.
Stack
| Component | Library / Tool | Role & Architectural Responsibility |
|---|---|---|
| Language & Runtime | Go 1.24+ | High-concurrency compiled binary with minimal memory footprint and fast execution. |
| TUI Framework | Charm Bubble Tea | Elm-architecture event loop, keyboard navigation, and terminal view rendering. |
| TUI Styling | Charm Lip Gloss | Declarative terminal layout formatting, borders, colors, and responsive components. |
| CLI Commands | Cobra CLI | Subcommand routing, flag parsing, and shell autocomplete (devflow add, devflow run). |
| Configuration | Viper Config | Environment variable parsing, config file discovery, and user theme preferences. |
| Persistence Layer | JSON & SQLite | Zero-dependency JSON for phase 1; fast indexed SQLite for phase 2 relational storage. |
| System Integrations | tmux & Git CLI | Subprocess execution for session creation, window attachment, and repository status checks. |
Architecture
Clean separation of presentation, application, domain service, and persistence layers.
flowchart TB
subgraph Presentation["Presentation Layer - TUI"]
BT["Bubble Tea View Engine"]
LG["Lip Gloss Layout Styles"]
end
subgraph Application["Application Layer"]
App["App Controller and State Coordinator"]
end
subgraph Services["Service Layer"]
PS["ProjectService"]
CS["CommandService"]
GS["GitService"]
TS["TmuxService"]
WS["WorkspaceService"]
end
subgraph Infrastructure["Storage and OS Subprocesses"]
DB[("JSON / SQLite Storage")]
OS["OS Exec - Git, tmux, Shell, Docker"]
end
Presentation --> Application
Application --> Services
Services --> DB
Services --> OS
The TUI is structured around immutable state updates. User input events (keypresses, resizes) trigger messages sent to the Bubble Tea event loop, which evaluates state modifications and re-renders Lip Gloss component views cleanly.
Business logic resides in dedicated services (GitService, TmuxService, ProjectService). Services execute OS commands via Go's os/exec package, parsing raw command stdout/stderr into structured Go domain models.
Codebase
Idiomatic Go project organization separating binary entry points from internal domain packages.
flowchart TB
subgraph Domain["Core Domain Architecture"]
Workspace["Workspace Root"] --> Projects["Project Registry"]
Workspace --> Config["Viper Configuration"]
Workspace --> Runner["Process Runner"]
Projects --> Commands["Predefined Commands"]
Projects --> Git["Git State & Branch"]
Projects --> Sessions["tmux Layouts & Sessions"]
Projects --> Tags["Tech Stack Badges & Tags"]
Runner --> Logs["Real-time Streamed Logs"]
end
| Directory Path | Purpose & Package Responsibility |
|---|---|
cmd/devflow/main.go |
Application entry point, CLI root command initialization. |
internal/app/ |
Application bootstrapper, lifecycle wiring, and graceful signal handlers. |
internal/config/ |
Viper configuration struct parsing and environment defaults. |
internal/models/ |
Pure Go domain entities (Project, Command, GitStatus, Workspace). |
internal/repository/ |
Storage interface declarations and JSON/SQLite storage drivers. |
internal/services/ |
Business logic engines for Project, Command, Git, tmux, and Docker. |
internal/ui/ |
Bubble Tea models, keymaps, Lip Gloss components, and screen renderers. |
internal/runner/ |
Pty/process executor for streaming shell command output. |
Progression
Engineering
System architecture, TUI state design, and core Go development by Dhrutinandan Swain.