Byte

[ 01 · Start here ]

How it works

Byte uses one adapter contract for detection, capabilities, collection, history, configuration, usage and supported execution. Claude Code uses hooks and transcripts; Codex uses trusted lifecycle hooks and supported App Server methods; OpenCode uses a Byte-owned plugin and server SDK; Superset uses its supported CLI and underlying agent adapters. Reconciliation preserves native identity and prevents duplicate sessions.

Claude Code's eight hooks

npm run install-hooks writes eight entries into ~/.claude/settings.json. Five take a "*" matcher: PreToolUse, PostToolUse, Stop, SubagentStop, Notification. Three take none: SessionStart, SessionEnd, UserPromptSubmit. The merge is idempotent: an existing Byte entry is replaced in place, and the file is only rewritten when the bytes would actually change.

What Claude Code's hooks miss

Some things emit no hook at all: /compact, and the tools a subagent runs inside itself. Those are recovered by reading the session transcripts under ~/.claude/projects, so the charts are drawn from what happened rather than from what was reported. Live rows and imported rows are written through the same turn key, backed by a unique index, so an overlap is a no-op instead of a duplicate. An Esc cancel is caught separately, by a watchdog that reads the interrupt marker Claude Code leaves in the transcript.

[ 02 · Start here ]

The screens

Six primary destinations organise the workspace: Home, Work, Sessions, Insights, Library and Settings. Existing detailed routes and shortcuts remain available. People, devices and administration appear only for authorised organisation roles.

The session mark

One session, one line. It is the same drawing in a table row, on a card and at full width, and it is the thing to learn first, because it appears everywhere else.

Both scales are logarithmic over fixed absolute domains, so the same session draws at the same size no matter what you have filtered to. Length runs from one second to thirty days. Thickness runs from a thousand tokens to a hundred billion. Eight decades, chosen by measurement: across ten real sessions on a 2 to 14 pixel stroke, a linear scale resolved 2 of 10 distinct weights, square root 5 of 10, and log 9 of 10.

The mark never claims more at a large size than it can support at a small one. In a table row, where twenty-one strands will not fit in twenty pixels, the stack collapses into a single stepped envelope rather than drawing eight strands and calling them twenty-one, and the envelope is stepped, never smoothed, because a curve between two buckets would draw agent counts that never existed. At full size the stack draws at most twelve rows and letters the rest (up to 61 agents at once, 12 drawn). Sessions with no tools and no subagents, most sessions in a real database, all draw as one short identical tick, because that is what they are.

The time spine

A ribbon pinned under the status bar, on every screen. It shows where your events sit in time, and dragging it moves the whole app. Arrow keys pan, up and down zoom, Home shows everything, End goes live. It goes inert, dimmed and unfocusable, on Settings, Agent Config and Run, where a time window means nothing, but it stays mounted so the page geometry never jumps.

Its axis is warped on purpose. Most minutes hold nothing: measured against the live database on 8 August 2026, 2,501 of 11,677 minutes held any event at all, 21%, so a linear axis would spend four fifths of its travel on dead air. Empty stretches collapse instead, the way a stock chart skips weekends. Nothing is ever stretched, only capped, so a dataset with no long gaps gets an exactly linear axis and the warp costs nothing. Each collapsed stretch is drawn as a dashed rule and lettered with the time it stands for, and the live density figure sits in the rail beside it.

The ten orchestration charts

Above them sit six figures: average agent depth, average subagents per session, agent success rate, most common flow, average compactions and average duration. Beside them, a runs panel for the fleets spawned by the Workflow tool. Those emit no hooks, so they are reconstructed from the run journals left on disk.

[ 03 · Start here ]

Settings

Eleven panels behind a sticky "jump to" rail that follows your scroll, at /settings.

Export sits in the page header: it is the counterpart the backup-restore import mode reads. Every write reports through a toast with a pending state.

Remote data sources

A remote source is another machine you can read over SSH. Byte mirrors that machine's projects tree into a per-source staging directory with scp, then runs the same importer it uses for local history, so remote sessions line up with local ones exactly. Authentication defers entirely to your own SSH stack: ~/.ssh/config, your agent, your keys, your known_hosts. Byte stores no secrets; a host is an ssh destination and nothing more. External commands run with an argument array and no shell, and an unknown host key fails the sync.

[ 04 · Run it ]

Quick start

Byte 2.2.5 and upgrading

Download Byte 2.2.5 desktop applications and SHA256 checksums from the 2.2.5 release page . Windows has an installer and a portable build, macOS has separate Apple Silicon and Intel disk images, and Linux has a deb package and an AppImage. Choose the package for your machine.

Windows and AppImage installations check for updates in the application. On macOS, download the new disk image and replace Byte in Applications. Existing records and enrolment remain in the application data directory. Keep that directory when uninstalling or replacing the app.

New installations use dark mode and signal orange. Upgrades preserve your saved theme, density and accent; signal is an additional choice in Settings. Organisation device codes connect a reporting machine to an organisation. They remain distinct from an application licence.

Byte 2.1 preserves your account, records and preferences. To invite a new account, add its email in Organisation, use the pending member's Invitation button, and share that private invitation with the named recipient. They paste it when creating their account or signing in. Invitations expire after 24 hours and can be accepted once.

Keep progress with Byte 2.2

Open a task from Work and define its observable outcomes. Checks capture the command, code revision and relevant environment. Verified, Failed, Needs judgment and Not checked are distinct states. A relevant code or dependency change makes prior evidence stale.

Review a requirement change before saving. Delivery to an agent is separate, and each attempt shows the instruction revision it has acknowledged. Record an investigation with its current question, observations, rejected approaches and next experiment. Facts and hypotheses remain separate.

Keep a useful fix as a lesson. It becomes verified only when its regression check fails on the original revision and passes on the correction. Reuse requires applicable paths and reviewed context. Sharing a lesson does not share its source conversation.

Prepare selected Git text changes in an isolated workspace. Review dependencies and checks, then apply only if the destination is still the reviewed revision. Unsupported file types, ambiguous ownership and inseparable edits require manual resolution. Byte does not reverse external service or database writes.

Max includes combined-task rehearsal and bounded automatic recovery. Automation starts disabled. Enabling it requires a reviewed project grant, supported native controls and visible attempt and time limits. The defaults allow at most two attempts and fifteen minutes. Cancel or disable without losing the original workspace; applying a candidate remains a separate approval.

Hosted Byte can inspect authorized synchronized evidence and author permitted private notes. Run local checks and prepare candidates on the connected local installation. Deploy compatible server and licence metadata before upgrading collectors. Back up existing data and verify a restore before production migrations.

What 2.1.3 repairs

Collection health now distinguishes recorded live events from history. Child-agent inspection, integration-aware pricing, cost grouping, theme switching, compact density and machine setup are improved. Existing records and preferences are retained. External Codex hook delivery is still under investigation; Byte-managed execution has verified live updates. Native execution also requires the corresponding application's installation, authentication and account permissions.

What 2.1.2 repairs

Integration and machine scope now reach orchestration details and model pricing. Codex history imports in bounded pages. Review live hooks with /hooks after connecting. Settings saves zoom from 75% to 150%; existing themes and data stay in place. Cody's optional panel includes its cat companion.

What 2.1.1 repairs

Integration lists and drill-throughs keep the selected agent, host and data source together. Task attachments require matching ownership and the actual run/session link. Existing external sessions, resumed sessions and legacy IDs remain supported when they belong to the task.

Migration 34 adds missing tasks.source storage, including databases that already recorded migration 33. Existing source values, task records and execution grants stay intact. For stored imported tasks, a source is recovered only when every linked session agrees and matches the task's agent and host. Missing or conflicting evidence stays unresolved and cannot start local work.

Native cost reports distinguish measured charges, token-based estimates and missing data. A captured zero remains zero; an absent measurement stays unavailable. Lifetime totals without a usable measurement date remain undated and do not become daily chart points or period-budget spend.

Compact navigation and controls use the correct Claude Code, Codex, OpenCode and Superset logos. Integration names stay visible so the current view is easy to identify.

Connect your coding tools

Open Settings, then Integrations, to connect Codex or OpenCode on the device where it runs. Review Byte's Codex hooks in the native application. OpenCode uses a Byte-owned plugin; explicit managed runs use an authenticated local service. Superset exposes its supported workspace and underlying-agent controls separately from native chat.

Connect and managed runs check the installed CLI's required interfaces before changing configuration or starting work. A different version can be used when those interfaces are present. Reading history does not start or resume an agent.

The four workspace switches change what you inspect while connected collectors continue recording. Existing Claude Code collection stays available. Native run ownership never changes merely because you switch views, and active conversations are not transferred between agents.

Library items start private. Preview the audience and content before sharing. Budget alerts warn without stopping independent agents. Back up data before upgrading a hosted cell and deploy the compatible server before enabling new collectors.

Requires Node.js 20 or newer.

npm run setup           # dependencies, and link the byte CLI
npm run install-hooks   # forward Claude Code events to Byte
npm run dev             # server on :4820, client on :5173

# production: one process serving everything on :4820
npm run build && npm start

# something on screen straight away
npm run seed            # three demo sessions

The server installs Claude Code hooks itself when you run it directly on the host. Codex and OpenCode are connected explicitly from Settings so their native trust and profile boundaries stay visible. History reconciliation runs in the background for each supported adapter.

Did it work?

[ 05 · Run it ]

Configuration

Everything has a working default. These are the ones worth knowing; the full annotated set is in .env.example.

[ 06 · Talk to it ]

API reference

Everything the screens do, they do over this API. It is 112 paths and 136 operations, and the generated OpenAPI 3.0 document is the complete reference: parameters, schemas, field descriptions and examples. It is served live at /api/openapi.json, as Swagger UI at /api/docs, and as ReDoc at /api/redoc. The ReDoc bundle is self-hosted, so it works offline.

Responses are JSON. Errors are always { "error": { "code", "message" } }. Collections take limit and offset, and the values are clamped rather than rejected: SQLite reads a negative LIMIT as "no limit". The envelope is flat and named for its collection: { sessions, limit, offset, total }.

Route groups

The ones you will actually call

Authentication

Set DASHBOARD_TOKEN and every /api/* call and the WebSocket upgrade need it. It is read from Authorization: Bearer …, an x-dashboard-token header, or a ?token= query parameter, and compared in constant time. Four paths stay open even then: /api/health, /api/openapi.json, /api/docs and /api/hooks/*, because the local hook handler carries no token and the loopback bind is what protects it. Browsers cannot set headers on a WebSocket, so the socket accepts only the query parameter or the custom header.

WebSocket

One socket at /ws. Every frame is { type, data, timestamp }. The types are:

session_created     agent_created     new_event          alert_triggered
session_updated     agent_updated     import.progress    alert_updated
run_status          run_stream        run_input_ack      workflow_upserted
update_status       cc_config_changed remote_data.updated
remote_source.status                  subscribed

A client that says nothing receives everything. To narrow, send { "action": "subscribe", "topics": [ … ] } where each topic is a frame type and optionally a session_id; the server answers with a subscribed frame. Subscriptions replace rather than merge, and cap at 200 topics. The server pings every 30 seconds and drops a socket that misses a pong. If a client stops reading, frames are dropped past a 1 MB send buffer and the socket is closed at 8 MB: a slow reader cannot become a memory leak.

[ 07 · Talk to it ]

Beyond the browser

Six other ways into the same database.

MCP server

Thirty tools: sixteen read-only, thirteen that mutate, and one that is destructive. Mutating tools are refused unless MCP_DASHBOARD_ALLOW_MUTATIONS=true. The destructive one, dashboard_clear_all_data, additionally needs MCP_DASHBOARD_ALLOW_DESTRUCTIVE=true and a confirmation token that must read exactly CLEAR_ALL_DATA. Read-only tools never touch either gate. The remote source listing scrubs hostnames, key paths and addresses before returning, because tool results are copied into a model's context.

npm run mcp:install
npm run mcp:build
npm run mcp:start              # stdio, for MCP hosts
npm run mcp:start:http         # HTTP + SSE on 127.0.0.1:8819
npm run mcp:start:repl         # interactive, with tab completion

# register it with Claude Code
claude mcp add byte \
  --env MCP_DASHBOARD_BASE_URL=http://127.0.0.1:4820 \
  -- node /path/to/Byte/mcp/build/index.js

The HTTP transport serves streamable HTTP at /mcp, legacy SSE at /sse and /messages, and a liveness probe at /health. The dashboard URL it talks to must be a local host: the allowlist covers loopback and the container gateway names, and rejects anything else.

The byte CLI

npm run setup links it. It finds the server from CLAUDE_DASHBOARD_PORT or DASHBOARD_PORT, then ~/.claude/.byte-agent-monitor.json, then 127.0.0.1:4820. Colour turns itself off when you pipe it.

byte status                 # is the server up, and where
byte stats                  # the header counters
byte kanban                 # the board, in the terminal
byte sessions --limit 20    # box-drawn table
byte session <id>           # one session in full
byte tail --session <id>    # follow events as they arrive
byte analytics              # tokens, cost, tools, with inline bars
byte cost                   # what it has cost you
byte doctor                 # check the install
byte repl                   # interactive shell with completion

Eleven commands work with no server at all, reading the SQLite file directly: stats, sessions, agents, events, kanban, session, pricing, alerts, rules, export and doctor. Offline runs still correct a stale active session for display, using the same process-liveness probe the server uses, and footnote that they did, without writing to the database.

Desktop app

Electron. It ships as a DMG on macOS, an NSIS installer and a portable executable on Windows, and a .deb and AppImage on Linux. The .deb is the one to prefer, because the hook command written into your settings embeds an absolute path and an AppImage remounts somewhere new every run.

The server runs in a dedicated child process, not in the window's own event loop: SQLite's API is synchronous, and a free-text search that takes most of a second froze the interface when the two shared a thread. If a healthy server is already answering on 4820 the app adopts it and leaves it running on quit; otherwise it picks a free port and writes it where the hook handler will look. The tray menu carries the port, active sessions, working agents and events today, plus open, restart, logs and an Open at Login switch, macOS and Windows only, since Electron has no supported mechanism on Linux.

VS Code extension

One activity-bar view, Monitor Control Center, polling every five seconds: four stat tiles with sparklines over the last twenty samples (sessions, agents, tokens, cost), an agent-health bar, recent sessions you can click through, and quick navigation. Four commands: open the dashboard, refresh, open in a browser, clear history. There are no settings to configure; it reads the port from the environment and falls back to 4820.

Statusline

A Python script, standard library only, that reads the JSON Claude Code pipes to it and prints seven segments: model, user, working directory, git branch, a ten-cell context bar with its percentage, tokens in and out with cache reads, and session cost to four decimal places. The context bar and the cost both change colour as they climb. It reads nothing else, no server, no database, no config, and exits zero whatever it is given, so it can never block Claude Code.

Plugins

Ten Claude Code plugins (byte-analytics, byte-cost-guard, byte-productivity, byte-devtools, byte-insights, byte-sessions, byte-workflows, byte-quality, byte-config and byte-dashboard), each bundling some mix of agents, commands, skills and hooks. They live under plugins/, alongside the marketplace manifest that lists them, and load straight from the checkout:

claude --plugin-dir plugins/byte-analytics

[ 08 · Operate it ]

Deployment

One SQLite file means one writer. Byte is not a stateless pool you scale sideways; it is a cell you run more of. The Helm chart enforces that itself: it refuses to render above one replica, and CI asserts the refusal on every change.

# Docker Compose, publishes on loopback only
docker compose up -d --build

# with Prometheus and Grafana alongside
docker compose -f docker-compose.full.yml up -d --build

# Podman
CLAUDE_HOME="$HOME/.claude" podman compose up -d --build

The image's health check opens the database rather than calling /api/health: that endpoint answers ok without touching storage, which is exactly the failure you want the check to catch. Hooks must be installed from the host, not from inside the container: the installer refuses there, so it can never write a container-internal path into a bind-mounted ~/.claude.

Monitoring

GET /api/metrics is Prometheus exposition: byte_up, byte_build_info, process uptime and resident memory, byte_sessions and byte_agents by status, byte_events_total, byte_websocket_clients, byte_remote_sources, and byte_tokens_total split by input, output, cache read and cache write. Scrape configs and Grafana dashboards ship under monitoring/; npm run monitoring:verify checks the wiring.

Security

The trust boundary is the loopback bind. Everything else is a layer on top of it.

• Loopback by default. The server binds 127.0.0.1 and is not reachable from the network.
• It refuses to start on a wider bind with no token and no explicit acknowledgement.
• Token auth over every API route and the WebSocket, compared in constant time, when DASHBOARD_TOKEN is set.
• A Host header allowlist, loopback plus whatever you name in DASHBOARD_ALLOWED_HOSTS, which is what stops DNS rebinding. CORS is restricted to the same set. Both are browser defences, not authentication: neither stops curl.
• Every query is a prepared statement with bound parameters, and query parameters go through one coercion module that fails closed. It exists because ?limit=-1 used to mean "no limit" to SQLite, and an int64 overflow used to mean a 500.
• Spawning is same-origin guarded. Every /api/run route rejects a browser request whose origin is not loopback, so a web page you happen to have open cannot start processes on your machine.

Report anything you find to namaste@bytevion.com.

[ 09 · Operate it ]

Troubleshooting