{"id":31161444,"url":"https://github.com/taigrr/bubbleterm","last_synced_at":"2025-10-04T12:24:21.293Z","repository":{"id":302548152,"uuid":"1012825603","full_name":"taigrr/bubbleterm","owner":"taigrr","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-03T00:39:13.000Z","size":46,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-03T01:29:01.577Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"0bsd","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/taigrr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"taigrr","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2025-07-03T00:18:31.000Z","updated_at":"2025-07-03T00:39:17.000Z","dependencies_parsed_at":"2025-07-03T01:39:18.690Z","dependency_job_id":null,"html_url":"https://github.com/taigrr/bubbleterm","commit_stats":null,"previous_names":["taigrr/bubbleterm"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/taigrr/bubbleterm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taigrr%2Fbubbleterm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taigrr%2Fbubbleterm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taigrr%2Fbubbleterm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taigrr%2Fbubbleterm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/taigrr","download_url":"https://codeload.github.com/taigrr/bubbleterm/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taigrr%2Fbubbleterm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275877133,"owners_count":25544466,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-19T02:00:09.700Z","response_time":108,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-19T03:53:17.992Z","updated_at":"2025-09-19T03:53:23.439Z","avatar_url":"https://github.com/taigrr.png","language":"Go","funding_links":["https://github.com/sponsors/taigrr"],"categories":[],"sub_categories":[],"readme":"# Bubbleterm: A Headless Terminal Emulator in Go\n\nA fully-functional, headless, embeddable terminal emulator written in Golang.\nThis library focuses on **terminal emulation** - parsing ANSI escape sequences, maintaining screen state, and rendering frames.\nIt's designed to work with PTY libraries like [`creack/pty`](https://github.com/creack/pty) for complete terminal functionality.\nFinally, we provide a Bubbletea-compatible output format for building terminal user interfaces (TUIs).\n\n## 💡 Goals\n\nThis library provides the **terminal emulation layer** and Bubble components that sits between PTY I/O and your application. It can:\n\n- Parse and interpret ANSI escape sequences (CSI, OSC, ESC, DCS)\n- Maintain terminal screen state (cursor position, colors, attributes)\n- Handle 256-color and true color (24-bit RGB) rendering\n- Support alternate screen buffers and scrollback\n- Process keyboard and mouse input events\n- Render frames as ANSI-preserved strings for TUI frameworks\n- Emulate `$TERM = xterm-256color` behavior accurately\n\n## 📦 Features\n\n| Feature                                | Status            |\n| -------------------------------------- | ----------------- |\n| ANSI parser (CSI, OSC)                 | ✅ Core complete  |\n| UTF-8 support                          | ✅                |\n| Text attributes (bold, underline, etc) | ✅                |\n| 256-color + true color                 | ✅                |\n| Cursor \u0026 scrollback                    | ✅                |\n| Keyboard input support                 | ✅                |\n| Resize support                         | ✅                |\n| `$TERM` compatibility                  | ✅ xterm-256color |\n| Bubbletea-compatible output            | ✅                |\n| Adjustable frame rate                  | ✅                |\n| Process termination API                | ✅                |\n\n## 🚀 Getting Started\n\n```bash\ngo get github.com/taigrr/bubbleterm\n```\n\n## 📋 Usage Examples\n\nThis library provides three ways to use the terminal emulator:\n\n### 1. Bubbletea Integration (`cmd/bubbleterm`)\n\nRun a terminal application within a Bubbletea TUI:\n\n```bash\ngo run cmd/bubbleterm/main.go\n```\n\nThis example shows how to:\n\n- Create a terminal bubble that runs `htop`\n- Handle keyboard input (Ctrl+C/q to quit)\n- Forward all messages to the terminal bubble\n- Display the terminal output in a TUI\n\n```go\n// import bubbleterm \"github.com/taigrr/bubbleterm\"\n// Create a new terminal bubble and start htop\ncmd := exec.Command(\"htop\")\nterminal, err := bubbleterm.NewWithCommand(80, 24, cmd)\n\n// Use in your Bubbletea model\nfunc (m *model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {\n    var cmd tea.Cmd\n    terminalModel, cmd := m.terminal.Update(msg)\n    m.terminal = terminalModel.(*bubbleterm.Model)\n    return m, cmd\n}\n```\n\n### 2. Headless Emulator (`cmd/staticprint`)\n\nUse the terminal emulator without a TUI for programmatic access:\n\n```bash\ngo run cmd/staticprint/main.go\n```\n\nThis example demonstrates:\n\n- Creating a headless terminal emulator\n- Starting a command (`htop`)\n- Capturing terminal output as frames\n- Resizing the terminal dynamically\n\n```go\n// Create a new emulator\nemu, err := emulator.New(80, 24)\ndefer emu.Close()\n\n// Start a command\ncmd := exec.Command(\"htop\")\nerr = emu.StartCommand(cmd)\n\n// Get the screen output\nframe := emu.GetScreen()\nfor i, row := range frame.Rows {\n    fmt.Printf(\"%2d: %s\\n\", i, row)\n}\n\n// Resize the terminal\nemu.Resize(100, 40)\n```\n\n### 3. Multi-Window Terminal Manager (`cmd/multiwindow`)\n\nA complete windowing system with multiple terminal instances:\n\n\nhttps://github.com/user-attachments/assets/c318dcab-4152-4166-94ba-3f20e228822d\n\n\n```bash\ngo run cmd/multiwindow/main.go\n```\n\nFeatures:\n\n- **Right-click**: Create new terminal window\n- **Left-click**: Select and drag windows\n- **'i'**: Enter insert mode (input goes to focused terminal)\n- **ESC**: Exit insert mode\n- **+/-**: Resize focused window\n- **Ctrl+C/q**: Quit application\n\nThis example shows advanced usage:\n\n- Multiple terminal instances running simultaneously\n- Window management with focus and z-ordering\n- Mouse event translation between screen and window coordinates\n- Centralized terminal updates with proper cleanup\n\n## 🔧 Core API\n\n### Basic Terminal Emulator\n\n```go\n// Create emulator\nemu, err := emulator.New(width, height)\n\n// Start a command\ncmd := exec.Command(\"your-command\")\nemu.StartCommand(cmd)\n\n// Get rendered output\nframe := emu.GetScreen()\nfor _, row := range frame.Rows {\n    fmt.Println(row)\n}\n\n// Resize\nemu.Resize(newWidth, newHeight)\n\n// Cleanup\nemu.Close()\n```\n\n### Bubbletea Integration\n\n```go\n// Create terminal bubble\nterminal, err := bubbleterm.NewWithCommand(width, height, cmd)\nterminal.SetAutoPoll(false) // Disable auto-polling for updates\n\n// In your Bubbletea model\nfunc (m *model) Init() tea.Cmd {\n    return m.terminal.Init()\n}\n\nfunc (m *model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {\n    terminalModel, cmd := m.terminal.Update(msg)\n    m.terminal = terminalModel.(*bubbleterm.Model)\n    return m, cmd\n}\n\nfunc (m *model) View() string {\n    return m.terminal.View()\n}\n```\n\n### Advanced Features\n\n```go\n// Focus management\nterminal.Focus()\nterminal.Blur()\nfocused := terminal.Focused()\n\n// Manual input sending\nterminal.SendInput(\"ls\\n\")\n\n// Process monitoring\nif terminal.GetEmulator().IsProcessExited() {\n    // Handle process exit\n}\n\n// Auto-polling control (for custom update loops)\nterminal.SetAutoPoll(false)\ncmd := terminal.UpdateTerminal() // Manual poll\n```\n\n## Limitations and Known Issues\n\n- Damage tracking is not yet implemented, so the entire screen may be redrawn on every frame\n- Sometimes, character deletion (backspace) may not work as expected due to missing damage tracking\n- Running tmux inside the emulator fixes these issues, as tmux handles its own damage tracking\n- We may decide to use a different emulator library in the future if it provides better performance or features\n\n## 📚 Resources\n\n- [creack/pty](https://github.com/creack/pty) - PTY interface for Go (recommended companion library)\n- [XTerm Control Sequences](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html)\n- [VT100 / VT220 Reference](https://vt100.net/)\n- [Charm Bubbletea](https://github.com/charmbracelet/bubbletea)\n- [Charm Glamour (ANSI Renderer)](https://github.com/charmbracelet/glamour)\n- [Bubbletea v2 Compositing Example](https://gist.github.com/Gaurav-Gosain/f6ff73cd53b8732af452dc27a3c76f59)\n\n## 📜 License\n\n0BSD\n\n## ⚙️ Roadmap\n\nThis library focuses on terminal emulation. For complete terminal functionality:\n\n- **PTY Management**: Use [`creack/pty`](https://github.com/creack/pty) for process and PTY handling\n- **Terminal Emulation**: This library handles ANSI parsing and screen rendering\n- **TUI Integration**: Output works seamlessly with Bubbletea and other TUI frameworks\n\nContributions welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaigrr%2Fbubbleterm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftaigrr%2Fbubbleterm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaigrr%2Fbubbleterm/lists"}