emacs-gravity
An idiomatic Emacs UI for Claude Code — structured, navigatable, fully native.
emacs-gravity gives you a magit-style working memory interface for Claude Code. Instead of watching a scrolling terminal, you get a structured, collapsible view of every session: plans, tool executions, agent trees, file changes, and tasks — all keyboard-navigatable, all in Emacs.
Claude Code's TUI is hidden by default. You see the conversation as data, not as a chat log.
Current state
I'm using it as my daily driver for several projects with Claude Code TUI. While stability is imploving, we're at beta quality, mostly.
- unmanaged sessions are the most frequently used and have the least amount of bugs
- the most confusing "feature" is that in 90% of the cases you see permission request or question displayed both in TUI and Gravity. The remaining 10% Claude may appear "stuck" because the request/question is not shown in the TUI, but only in Gravity. The menubar indicator helps a lot with this case.
- managed sessions (tmux) are not well tested yet. They are my next priority.
- known issue is you have to have running tmux before Gravity can start managed session.
- performance is OK. With many sessions and frequent updates editors freeze too often. I regularly have performance focused sessions, but I'm not sure we can ever get to state where Gravity buffers are receiving frequent updates and regular editors feel as smooth as usual.
This project has been vibecoded on purpose as experiment, so desipite my best effort to keep complete test suite, regressions happen.
Project is being used & developed exclusively on MacOS, so windows & linux users may hit obstacles I'm unaware of.
v3: Server-Driven Architecture
Breaking change. v3 is a ground-up rewrite of the backend. The v2 standalone mode (where Emacs held all state directly) is gone. You must remove v2 completely before upgrading — gravity-server is now required.
What changed
- Server-driven architecture — All session state moved from Emacs Lisp hash tables to gravity-server, a long-running TypeScript/Effect backend. Emacs is now a thin terminal client that applies semantic patches and renders via magit-section.
- Multi-client support — Multiple terminals connect to the same server simultaneously. The macOS menu bar app and Emacs share the same live state. First responder wins for inbox actions.
- Semantic patch protocol — Typed incremental updates (
add_tool, complete_agent, set_plan) replace full state rebuilds. Any client that speaks the protocol can render the full UI — future web or native dashboards included.
- Centralized enrichment — Transcript parsing, agent attribution, and event enrichment run server-side with full in-memory state. No more file I/O for agent tracking.
- Inbox system — Permissions, plan reviews, and questions from all sessions funnel into a centralized inbox. Any connected terminal can respond.
- macOS menu bar client — New lightweight Swift app with colored status dots per session, project-grouped dropdown, health monitoring, and auto-reconnect.
- Two-socket architecture — Hook socket (bridge shim, one-shot per event) and terminal socket (persistent client connections) are cleanly separated.
- Monorepo with shared types —
packages/{shared, emacs-bridge, gravity-server} with npm workspaces and type-safe protocol definitions shared across all components.
- Beads issue tracking integration — Projects with a
.beads/ directory get a live Issues section in the overview buffer. Open, in-progress, and blocked issues displayed per project with priority labels, status indicators, and async refresh.
See ARCHITECTURE.md for the full v3 design and docs/refactor-implementation.md for the design rationale.
Migrating from v2
- Remove old socket config — v2 connected the bridge directly to Emacs. Delete any custom socket paths pointing at Emacs.
- Delete agent state files — Remove
~/.claude/emacs-bridge-agents.json (agent state is now in-memory in gravity-server).
- Clean install — Run
npm install at the monorepo root.
- Re-register the plugin — Update
marketplace.json if needed (the source path is unchanged).
- Update your init.el — Replace
(claude-gravity-start) with (claude-gravity-server-start).
- Delete stale byte-compiled files — Run
rm -f *.elc in the project root. Emacs loads .elc over .el, so stale compiled files silently override your changes.
Why emacs-gravity?