codelight - coding-agent status & remote control

Live status, usage, conversation following, and remote-control prompts for supported coding agents. Watch grouped working/waiting/idle state on a desk screen, phone, GNOME panel, or in VSCode — and, when you're away from the keyboard, approve permission prompts and answer agent questions from any of them. Pick and choose whatever suits your needs:

Currently supported agents

Agent	Status	Usage	Permissions	Questions	Conversation
Claude Code	✅	✅	✅	✅	✅
Codex CLI / IDE extension	✅	✅	✅	✅	✅
GitHub Copilot / Copilot Chat	✅	✅ 1	✅	✅ 2	✅
Cursor (IDE / cursor-agent CLI)	✅	✅ 3	✅ 4	— 5	✅
Grok (xAI)	✅	— 6	— 7	— 7	✅
OpenCode	✅ 8	✅ 9	✅ 11	✅	✅ 10

<sub>1. Copilot usage is the organization's pooled monthly AI-credit meter — needs `agents.copilot.github_org` and a token.
2. Copilot answers questions only where the IDE hook path exposes them.
3. Cursor shows a monthly included-usage meter read from the local Cursor auth token (no setup); it hides if you are not signed in to the IDE.
4. Cursor remote-allow bypasses the prompt in the IDE; the `cursor-agent` CLI is deny-only (its own command allowlist still prompts).
5. Cursor exposes no agent-asks-the-user hook to intercept.
6. No Grok usage meter: the CLI runs on the SuperGrok subscription, whose weekly rate limit is not machine-readable (cookie-gated web page, and the CLI's OAuth token is rejected by the rate-limit API). xAI's separate developer-API credit pool *is* readable (opt-in via a billing management key) but the subscription-based CLI never draws on it, so it would always read ~0%. See [companion/AGENTS.md](companion/AGENTS.md) for the two-wallets detail.
7. Grok's single blocking hook cannot approve remotely, and it has no agent-asks-the-user hook.
8. OpenCode has no hooks; codelight follows its local HTTP server's event stream (run `opencode serve --port 4096`, or set `agents.opencode.server_url`).
9. OpenCode is BYOK (no provider quota), so the meter is an opt-in monthly $-budget you set (`agents.opencode.monthly_budget_usd`) against spend read from its local store — a tracking budget, not an enforced limit.
10. OpenCode conversation following reads the active session's messages from the server API (needs the server running, per note 8).
11. OpenCode remote approval works for prompts initiated via the server API — including instructions you send from codelight (remote steering). Prompts typed at OpenCode's interactive TUI raise a legacy permission the TUI handles locally and won't dismiss on an external reply (an OpenCode-side limitation, like the Cursor CLI). It can also *send* new instructions to a running agent — the first agent codelight can drive, not just observe.</sub>

Agent-specific setup, caveats, and config keys live in companion/AGENTS.md.

Component	Description	Example
companion/	Python daemon that detects supported agents, installs their hooks, polls usage where available, pushes status over WebSocket + D-Bus, and brokers remote control.
screen/	ESP8266 firmware for the GeekMagic Ultra — renders usage bars and status
android/	Responsive Android widget + Status and Conversation views, permission review, and question answering
gnome-extension/	GNOME Shell panel extension: status + approve/answer prompts from a popup
vscode-extension/	VSCode status bar + answers supported agent questions in the editor

Remote control

Run the companion with --remote-control (requires --secret) and codelight takes over supported interactive prompts, pushing them to any connected client so you can respond from wherever you are:

• Permission prompts (Allow / Deny) — from the Android app or the GNOME panel.
• Questions (multiple-choice + free text) - from the Android app, the GNOME panel, or VSCode (a themed WebView in the editor).
• Send instructions (remote steering) — for agents that expose a control API (currently OpenCode): type a new instruction to a running agent from the Android app — the first agent codelight can drive, not just observe.

Whoever answers first wins. If no capable client is connected, codelight falls through to the agent's built-in prompt. See companion/README.md; agent-specific prompt details live in companion/AGENTS.md.

Persistent folder and exact-command approvals are stored once in codelight's agent-neutral policy and enforced in the shared hook path. See Persistent folder and command approvals.

The status UIs all show the same core information:

Agent working	Waiting for user input	Ready for a new task

Architecture

flowchart LR
    A1["Supported agent"] -->|hooks| D
    A2["Supported agent"] -->|hooks| D
    A3["Hookless agent<br/>(e.g. OpenCode)"] -->|HTTP server + SSE| D

    subgraph D["codelight.py daemon"]
        SOCK["Unix socket thread<br/>receives hook events"]
        LISTEN["Background listener<br/>follows server event streams"]
        REG["Agent registry<br/>metadata + hook modes + branding"]
        USAGE["Multi-agent usage poller"]
        WS["WebSocket server :8765"]
        DBUS["D-Bus service<br/>se.sensnology.codelight"]
    end

    WS -->|status| SCREEN["GeekMagic Ultra<br/>(mDNS)"]
    WS -->|status + questions + remote control<br/>+ conversation| ANDROID["Android app<br/>(mDNS)"]
    WS -->|status + questions + remote control| VSCODE["VSCode extension"]
    DBUS -->|status + questions + remote control| GNOME["GNOME extension"]

    REG -.-> USAGE
    USAGE -.-> WS
    SOCK -.-> WS
    SOCK -.-> DBUS
    LISTEN -.-> WS
    LISTEN -.-> DBUS

Loading

The ESP8266 screen and Android app use WebSocket (discovered via mDNS). The GNOME extension uses D-Bus on the session bus — no network socket or configuration needed. With --remote-control, permission and question prompts are pushed to the clients that subscribe to them (the screen and older apps never see them). See companion/README.md.

Quick start

1. Flash the screen firmware (or grab a pre-built .bin from the Releases page): see screen/README.md.

2. Run the companion daemon on your computer:

   python3 companion/codelight.py --name my-laptop

   Add --secret mypassword --remote-control to enable remote approval and question answering. Installed supported agents are detected automatically and their hooks are managed together. Full setup: companion/README.md.

3. (Optional) Install the Android app: android/README.md.

4. (Optional) Install the GNOME extension: gnome-extension/README.md.

5. (Optional) Install the VSCode extension: vscode-extension/README.md.

More screenshots

Adaptive multi-agent widget	Conversation following	Permission review

VS Code status	VS Code permission review	Companion dashboard