charmbracelet / charmbracelet/bubbletea

Proposal: DevTools inspector for Bubble Tea apps (charm-devtools)

Open
#1,655 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
44.9k
Forks
1.3k
PR merge metrics
No merged PRs in 30d

Description

## Problem

Debugging Bubble Tea apps currently relies on logging to files with \`log.Printf\`. There's no way to inspect:
- What messages are flowing through the system
- The current model state at any point
- The component hierarchy

React has React DevTools, Flutter has DevTools — Bubble Tea has nothing equivalent.

## Proposed Solution

**charm-devtools** — a middleware that wraps any Bubble Tea model and provides a toggleable inspector panel.

```go
// Just wrap your model
model := devtools.Middleware(myModel)
p := tea.NewProgram(model)
```

Press **F12** to toggle the inspector:
\`\`\`
┌─ Charm DevTools ──────────────────┐
│ Messages (last 10): │
│ → KeyPressMsg "j" 00:01.23 │
│ → TableMoveDown 00:01.23 │
│ → WindowSizeMsg 80x24 00:00.05 │
│ │
│ State: │
│ cursor: 5 │
│ filter: "api" │
│ rows: 42 │
│ │
│ Components: │
│ ├─ App │
│ │ ├─ Header │
│ │ └─ Table │
└────────────────────────────────────┘
\`\`\`

### Features
- **Message log** — ring buffer of last 100 messages with timestamps and types
- **State viewer** — \`fmt.Sprintf("%+v")\` dump of current model
- **Component tree** — auto-detected via reflection on nested \`tea.Model\` fields
- **Zero config** — single \`Middleware()\` call, toggle with F12
- **Tab navigation** — 3 panels (Messages, State, Components)

## Working POC

https://github.com/junhinhow/charm-devtools

Bilingual docs (EN/PT-BR).

## Questions

1. Would this be useful as an official debugging tool?
2. Should it use a split-screen approach or a separate terminal window?
3. Any interest in a message replay/time-travel feature?

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the proposed charm-devtools POC and the Bubble Tea middleware entry point described in the issue. Clarify whether an official inspector should be pursued, how its panels and terminal integration should work, and what implementation scope and acceptance criteria would define completion.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
cli, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.