syzygy

syzygy draws one band above the Claude Code prompt with what the terminal does not show: real context use, session spend, the active model, the git branch and diff, denied tool calls and the turn clock. The same plugin starts a local relay serving a browser dashboard at http://localhost:4317, where every Claude Code session on the machine is a card you can read, answer, rename or close.

What it does

• The context meter reads real token usage from the session transcript. A moon glyph drains from full to empty, and the band border turns yellow at half the window and red at two thirds.
• Hotkeys are the ten digits. 1 toggles a tmux side pane with the same board, 4 asks a small model to narrate what the session is doing, and the other eight are prompt slots you edit in ~/.claude/syzygy-hud-hotkeys.json. They fire only on an empty composer.
• Twenty-two turn spinners replace the built-in one; just spinner <id> pins one.
• The dashboard has eight views, from a switchboard of session cards to a dispatch queue that turns a rough ask into a brief, a worktree and a background session. Dragging one card onto another briefs that session over Claude Code’s own messaging.
• Ten tools are registered for the model: ask_human shows a question in the dashboard and waits up to a minute, remember and recall keep per-project notes, think_harder puts one question to a larger model.

The repo also ships syzygy-editor, which turns file references in a reply into clickable boxes that open your editor in a tmux split, and forge, an opt-in plugin (just install-forge) that mints a repeated sequence of tool calls into one tool.

Install

Needs function hooks enabled, just, Node 22 or later with npm, and python3. The author verified it against Claude Code 2.1.269. tmux 3.1 or later and Go are optional and serve only the side pane.

git clone https://github.com/adenineio/syzygy && cd syzygy
npm install
just install

just install symlinks the plugins and builds the side pane when Go is present. Then, in a Claude Code session, run /plugin-types to generate the API declarations for your build and /reload-plugins. The relay starts by itself, and the dashboard’s first visit asks you to choose a password. just deps-check lists what your machine is missing.

How it works

The module hooks session.start, prompt.submit, ui.render and the * wildcard, which sees every tool.call: it counts calls, denials and consecutive errors, keeps the first 120 characters of the command, path, pattern or URL as a feed entry, counts Edit and Write calls per file for a stuck warning, and matches commands against test runners to log results. On prompt.submit it keeps the first 400 characters of each prompt to chain turns by topic. A prompt that starts or ends with ,, is stashed on the relay’s pasteboard instead of being sent; an empty pasteboardMarker in the hotkeys file turns that off.

Token counts come from the session transcript under ~/.claude/projects/, read incrementally with tail, because turn.complete carries no usage. The context window comes from a per-model table, corrected by an optional wrapper (just statusline-install) that copies the JSON Claude Code hands your status line into ~/.claude/syzygy/statusline/. Branch and diff come from git through $.process.run.

Every $.http.fetch goes to 127.0.0.1 on the relay port, 4317 by default; nothing leaves the machine. Every 1.2 seconds it posts the session’s name, directory, branch, model, counters, edited files, the event feed and the last 2 KB of the answer; after each turn, 400 characters of the prompt and of the answer. Every 0.9 seconds it polls for commands from the dashboard: submit or refill a prompt, abort the turn, rename the session, stop a subagent, brief another session through SendMessage, or read a line aloud with $.audio.speak. An end-of-turn chime is off by a constant in the source.

The relay is a Node process the plugin launches with nohup when nothing answers on the port; it logs to ~/.claude/syzygy/relay.log and keeps its bearer token in ~/.claude/syzygy-relay.json, mode 0600. The password gates the browser only: the README states that anything running under your account can reach the relay and that nothing is encrypted at rest.

The plugin spends tokens. After each turn, at most once every eight seconds, it asks haiku through $.model.complete for a one-line narration capped at 60 output tokens; the 4 key triggers the same call. think_harder makes a separate call to claude-opus-5 by default, up to 1,200 output tokens, when the model chooses to use it. $.model.classify is only named in a comment, never called. In $.store it keeps the session counters under hud:<session id> so /reload-plugins does not reset them, the spinner choice, and up to 500 remember notes per project.

Limitations

• The function hooks API moves between builds; run /plugin-types again after every Claude Code update.
• The band draws only in the terminal; under four rows it shrinks to one line of vitals, and the hotkey row needs six rows and 62 columns.
• The side pane needs tmux 3.1 or later, and Syzygy.app (just app-install) is macOS only. Voice input, enabled from the pane’s gear, downloads a 748 MB Python environment and a 1.6 GB Whisper model.
• The module shells out to printenv, find, tail and sh and skips the transcript and the relay when HOME does not start with /, so it expects a Unix shell.
• Prices live in a table in hud.tsx; when they change, the spend figure is wrong until the table is edited.