[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-93990":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":17,"stars30d":17,"stars90d":16,"forks30d":16,"starsTrendScore":13,"compositeScore":18,"rankGlobal":10,"rankLanguage":10,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":20,"topics":23,"createdAt":10,"pushedAt":10,"updatedAt":38,"readmeContent":39,"aiSummary":10,"trendingCount":16,"starSnapshotCount":16,"syncStatus":40,"lastSyncTime":41,"discoverSource":42},93990,"Grok-UI","joeynyc\u002FGrok-UI","joeynyc","Local-first live command center for Grok Build — runtime, ACP control, session history, and Git changes.","https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fgrok-ui",null,"TypeScript",117,27,1,4,0,9,67.74,"MIT License",false,"main",true,[24,25,26,27,28,29,30,31,32,33,34,35,36,37],"agent-client-protocol","ai-agents","dashboard","developer-tools","git","grok","grok-build","local-first","nodejs","react","self-hosted","sse","typescript","xai","2026-07-30 04:02:14","\u003Cdiv align=\"center\">\n\n\u003Cimg src=\"https:\u002F\u002Fraw.githubusercontent.com\u002Fjoeynyc\u002FGrok-UI\u002Fmain\u002Fdocs\u002Fgrok-ui-red-mark.png\" width=\"128\" alt=\"Grok UI red command mark\"\u002F>\n\n# Grok UI\n\n**Every Grok session — one living command center.**\n\nAn unofficial, local-first dashboard for Grok Build:\nwatch active agents, control sessions over ACP, inspect Git changes,\nand move through your complete local history without leaving the browser.\n\n![Node.js 22+](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FNode.js-22%2B-5FA04E?logo=nodedotjs&logoColor=white)\n![React 19](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FReact-19-149ECA?logo=react&logoColor=white)\n![Grok Build](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGrok%20Build-native-111318)\n![Local first](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fprivacy-local--first-D9FF43?labelColor=111318)\n![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-E44738)\n\n\u003Cimg src=\"docs\u002Fgrok-ui-dashboard.png\" width=\"900\" alt=\"Grok UI Event Horizon dashboard with live runtime telemetry\"\u002F>\n\n[**Watch the 24-second product tour**](https:\u002F\u002Fgithub.com\u002Fjoeynyc\u002FGrok-UI\u002Freleases\u002Fdownload\u002Fv0.5.1\u002Fgrok-ui-dashboard-tour-final-white-logo.mp4)\n· [**See what’s new in v0.10.0**](https:\u002F\u002Fgithub.com\u002Fjoeynyc\u002FGrok-UI\u002Freleases\u002Ftag\u002Fv0.10.0)\n· [**Quickstart**](#quickstart) · [**What it does**](#what-it-does)\n· [**Architecture**](#architecture) · [**Security**](#privacy-and-security)\n\n\u003C\u002Fdiv>\n\n> [!NOTE]\n> Grok UI is an independent community project. It is not affiliated with or endorsed by xAI.\n\n## What it does\n\n\u003Ctable>\n\u003Ctr>\n\u003Ctd width=\"50%\" valign=\"top\">\n\n**◉ A runtime that tells the truth**\n\nActive agents come from Grok’s real process registry. Turns, phases,\nreasoning, responses, tools, context, and cost updates flow into the\ndashboard over one live event stream.\n\n\u003C\u002Ftd>\n\u003Ctd width=\"50%\" valign=\"top\">\n\n**⌘ Native session control**\n\nCreate, resume, prompt, approve, and cancel Grok sessions through the\nAgent Client Protocol. Permission choices are rendered exactly as Grok\nprovides them—never guessed or auto-approved.\n\n\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd width=\"50%\" valign=\"top\">\n\n**◇ One Session Console per agent**\n\nOpen any recorded CLI session or managed lane in a clearly labeled Session\nConsole to chat with the agent, review its activity, inspect changes, manage\npermissions, send follow-ups, and launch a session-scoped web preview. Managed\nsessions survive dashboard restarts.\n\n\u003C\u002Ftd>\n\u003Ctd width=\"50%\" valign=\"top\">\n\n**↗ Git changes as they happen**\n\nThe selected repository is watched live. Staged, unstaged, and untracked\nfiles update automatically, with bounded diffs and no manual refresh\nrequired.\n\n\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd colspan=\"2\" valign=\"top\">\n\n**⌁ Cross-session workflow command field**\n\nGrok Build v0.2.112+ workflow updates become one live run field: phase\nprogression, per-agent token usage, models, duration, budget use, failures,\nresults, and safe Pause, Resume, or Stop controls. Searchable, paginated rosters\nstay usable as a workflow scales. Failed runs expose recovery only when Grok\nreports that the current process can resume them.\n\n\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd colspan=\"2\" valign=\"top\">\n\n**◎ Secure remote sessions**\n\nRegister trusted Grok UI host agents over managed SSH forwarding or a private\nTailscale network. The Fleet view shows identity, versions, capabilities,\nhealth, latency, last seen, freshness, and bounded telemetry. With a separate\nper-host control grant, start a managed Grok session and continue the same live\nconversation from another device, including follow-ups, Grok permission\nchoices, and interruption.\n\n\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftable>\n\n## Architecture\n\n\u003Cdiv align=\"center\">\n\u003Ca href=\"https:\u002F\u002Fraw.githubusercontent.com\u002Fjoeynyc\u002FGrok-UI\u002Fmain\u002Fdocs\u002Farchitecture.svg\">\n\u003Cimg src=\"docs\u002Farchitecture.svg\" width=\"820\" alt=\"Browser connected to a local Grok UI supervisor, local state and ACP control, plus authenticated read-only remote host agents\"\u002F>\n\u003C\u002Fa>\n\u003C\u002Fdiv>\n\nGrok UI runs as one local Express supervisor. The browser receives runtime,\ncontrol, dashboard, workspace, and fleet events over SSE; commands return\nthrough authenticated API routes. Optional host agents keep monitoring on an\nauthenticated read-only protocol and expose remote sessions only through a\nsecond, explicitly enabled control credential. Grok credentials and host-agent\ntokens never enter the browser.\n\n## Quickstart\n\n### Requirements\n\n- Node.js 22 or newer\n- A working [`grok`](https:\u002F\u002Fgithub.com\u002Fxai-org\u002Fgrok-build) installation\n- Grok Build account access\n\n### One-command launch\n\nThe packaged release checks its environment, starts the local server, and opens\nthe dashboard:\n\n```bash\nnpx --yes grok-ui\n```\n\nRun diagnostics without starting the dashboard:\n\n```bash\nnpx --yes grok-ui doctor\n```\n\nStart the read-only agent on a machine you want to monitor:\n\n```bash\nGROK_UI_AGENT_TOKEN='\u003Cseparate-long-random-token>' \\\nnpx --yes grok-ui agent\n```\n\nThe agent always requires its own token, including on loopback, and defaults to\n`127.0.0.1:4311`. Use `--host`, `--port`, `--grok-home`, or `--state-dir` after\n`agent` when that machine needs an override. The central Fleet view stores the\nmatching token server-side when you register the host.\n\nTo opt that host into secure remote sessions, provide a second, different\ntoken:\n\n```bash\nGROK_UI_AGENT_TOKEN='\u003Cmonitoring-token>' \\\nGROK_UI_AGENT_CONTROL_TOKEN='\u003Cdifferent-control-token>' \\\nnpx --yes grok-ui agent\n```\n\nIn the central Fleet editor, enter the same control token and enable Remote\nSessions for that host. A healthy, fresh host can then start Grok in a workspace\nit has already observed. The Remote Session Console streams the conversation,\naccepts natural-language follow-ups, presents Grok's exact permission choices,\nand can interrupt the current turn. It is not a remote terminal and exposes no\narbitrary shell.\n\n### Run from source\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fjoeynyc\u002FGrok-UI.git\ncd Grok-UI\nnpm ci\nnpm run doctor\nnpm start\n```\n\n`npm start` creates the production build automatically when it is missing.\nFor file-watching development, use `npm run dev`.\n\nThe versioned delivery plan is maintained in\n[`docs\u002Froadmap.md`](docs\u002Froadmap.md).\n\nThe first launch opens a live setup diagnostic that distinguishes a missing\nCLI, an unauthenticated account, and a profile that simply has not created its\nfirst session yet. Machine-specific paths are never included in those checks.\n\n### CLI options\n\n| Option | Purpose |\n| --- | --- |\n| `doctor` | Check Node, Grok CLI, authentication, and local state |\n| `agent` | Start the authenticated host agent; remote sessions are opt-in |\n| `--port \u003Cnumber>` | Override dashboard port `4310` or agent port `4311` |\n| `--host \u003Caddress>` | Override the loopback bind address |\n| `--grok-home \u003Cpath>` | Use a specific Grok state directory |\n| `--state-dir \u003Cpath>` | Use a specific private Grok UI state directory |\n| `--no-open` | Start without opening a browser |\n| `--version` | Print the installed Grok UI version |\n\n## Live runtime\n\nStart `grok` in any workspace and the session appears as soon as its live\nprocess registers. The runtime view projects:\n\n- agent state: working, waiting, idle, or needs input\n- current phase and active tool\n- structured user, assistant, reasoning, plan, and tool events\n- turns, tool calls, context usage, and reported cost\n- process identity and workspace\n\nProcess liveness is rechecked continuously, so “live now” means an open Grok\nprocess—not a recently modified history file.\n\n## Session control\n\nGrok UI supervises `grok agent --no-leader stdio` and communicates through\nthe official [Agent Client Protocol](https:\u002F\u002Fagentclientprotocol.com\u002F).\n\nIt supports new sessions, `session\u002Fload`, prompts, permission requests,\nconfirmed cancellation, and independently running managed lanes. Stop also\ncancels pending permissions, preserves final tool updates, surfaces a retry when\nGrok does not confirm, and leaves the lane ready to resume. Rename and archive\nactions are local Grok UI overlays; Grok’s own session files are never rewritten.\n\n## Session previews\n\nThe local Session Console detects `dev` or `start` scripts in the workspace\nalready associated with that session and shows the exact command before\nanything runs. Starting a preview launches a separate process without a shell,\nbinds supported frameworks to a random loopback port, and streams a bounded\noutput tail into the console.\n\nThe preview surface includes desktop, tablet, and mobile widths, reload and\nexternal-open controls, and an explicit Stop action. Preview processes are\nephemeral and terminate when Grok UI shuts down. Privacy Mode hides the embedded\napplication and redacts the displayed command and logs.\n\n## Workflow runs\n\nThe Runs view listens for Grok’s structured `workflow_updated` notifications on\nUI-managed ACP sessions and aggregates them across the command field. Each run\ncan show:\n\n- current status, objective, phase progression, and latest event\n- per-agent state, phase, model, duration, and token usage\n- active, used, reserved, and total agent allocation\n- derived run-wide token totals with explicit incomplete-usage states\n- pause context and final result summary\n- Pause, Resume, and Stop controls when the run state supports them\n\nControls use Grok’s documented `\u002Fworkflow pause|resume|stop \u003Cdisplay-name>`\ncommands and accept only validated display handles. Persisted snapshots remain\nvisible after a dashboard restart, but their controls are disabled because Grok\nonly resumes failed or paused workflows inside the process that owns them.\n\nGrok UI intentionally does not scrape the terminal dashboard or imply visibility\ninto historical CLI-only workflow runs. A run appears after a UI-managed session\nemits its first workflow update.\n\n## Usage ledger\n\nThe v0.9 Usage view extends the existing token and cost telemetry with a\ndurable local ledger. It reports by project, model, session, agent, and time\nperiod, while keeping session totals separate from workflow-agent detail.\n\nEvery value says whether it is Grok-reported, derived, incomplete, or\nunavailable. Grok UI does not substitute context-window occupancy for\ncumulative CLI token usage, and explicitly mixed observation scopes are never\npresented as precise spend.\n\nOptional token or reported-cost budgets can be scoped globally or to a project,\nmodel, session, or workflow agent. They are evaluated only against a\nnon-overlapping ledger scope, and local alerts are deduplicated at 80% and\n100%. JSON and CSV exports are capped, authenticated, and redacted on the\nserver before download whenever Privacy Mode is active.\n\n## Runtime intelligence\n\nThe Live view projects bounded process trees from active Grok and UI-managed\nprocess IDs. It discovers listening TCP ports only for that selected process\nset, classifies common databases and development services without connecting\nto them, and shows structured test status and external-call categories from the\nexisting safe tool lifecycle.\n\nInspection uses fixed timeouts, output, process-count, and tree-depth caps. Raw\ncommand arguments, tool input, credentials, headers, terminal history, and\nunrelated host processes are never included in the browser contract.\n\n## Multi-machine monitoring\n\nThe v0.10 Fleet view monitors up to 32 explicitly registered hosts. Each host\nreports a stable identity, Grok UI, agent, and Grok versions, negotiated read\ncapabilities, health, round-trip latency, last-seen time, and freshness.\nBounded tabs show remote sessions, workflow runs, runtime state, and\nprovenance-aware usage.\n\nHosts can be reached in three constrained ways:\n\n- **SSH** — Grok UI manages a fixed loopback forwarding process with\n  argument-separated `ssh` options, batch mode, no shell, and no remote command.\n- **Tailscale** — the registry accepts only `.ts.net` names or addresses from\n  Tailscale's IPv4 or IPv6 ranges.\n- **Direct** — an advanced\u002Ftest transport restricted to HTTP or HTTPS loopback\n  origins.\n\nThe monitor polls every 5 seconds with a 3.5-second request timeout and at most\nfour concurrent remote reads globally, including explicit refresh and detail\nrequests. Per-agent responses are capped at 2 MiB and the central fleet\nprojection at 4 MiB. A sample becomes stale after 15 seconds and offline after\n45 seconds. Connecting, healthy, degraded, stale, offline, incompatible,\nunauthorized, and unavailable states remain distinct in the UI.\n\nv0.10 is strictly read-only on remote machines. It cannot remotely start work,\nsend prompts, approve permissions, pause, resume, interrupt, stop, execute a\nshell, write files, or probe arbitrary endpoints. Registering, editing,\nrefreshing, or removing a host changes only the central monitor configuration\nor triggers a read.\n\n## Secure remote sessions\n\nv0.11 keeps all v0.10 monitoring routes read-only and adds a separate,\nhost-authorized control channel. It lets a user start or continue a real\nACP-managed Grok conversation from another device, send follow-ups, answer\nGrok's permission requests, and interrupt a running turn.\n\nEvery mutation carries a durable command ID and bounded delivery expiry.\nRetrying the same delivery cannot silently create duplicate work, and a host\nrestart turns an ambiguous command into an explicit reconciliation state\ninstead of replaying it. Existing CLI-observed sessions remain read-only;\nfollow-up control is limited to host-managed sessions. Controls remain\nunavailable while the host is stale, unhealthy, incompatible, disabled, or\nmissing the exact capability.\n\nThe initial scope does not add arbitrary shell access, remote workflow\nPause\u002FResume\u002FStop, team roles, or shared approvals. See\n[`docs\u002Fv0.11-secure-remote-sessions.md`](docs\u002Fv0.11-secure-remote-sessions.md)\nfor the product contract and staged decisions.\n\n## Themes\n\nThree complete visual systems ship with the dashboard:\n\n- **Operator** — carbon black, signal lime, and a precision HUD grid\n- **Event Horizon** — deep-space red, cold starlight, and glass command surfaces\n- **Minimal Calm** — quiet stone surfaces, sage signals, and restrained motion\n\nTheme selection stays in local browser storage and never changes session data.\n\n## Privacy and security\n\n- The server binds to the loopback interface by default.\n- Non-loopback binding requires `GROK_UI_TOKEN`.\n- Grok credentials never pass through the browser.\n- Local preview processes bind to loopback, receive no Grok credentials, and\n  start only after an explicit user action.\n- Persistent Privacy Mode replaces visible session names, paths, identifiers,\n  event content, file names, remote host names, and endpoints with stable\n  presentation-safe aliases.\n- Privacy Mode protects recordings and screen shares; it is not an access-control\n  boundary. Authorized browser clients can still receive the underlying local data.\n- Authentication cookies are `HttpOnly` and `SameSite=Strict`.\n- API responses are non-cacheable and include restrictive security headers.\n- Raw system prompts and durable-memory bodies are not indexed.\n- File, diff, and event reads are bounded.\n- Host-agent reads require a dedicated bearer token, reject redirects, time out\n  after 3.5 seconds, and cap responses at 2 MiB.\n- Fleet URLs are restricted by transport, and the connector accepts only fixed\n  `\u002Fagent\u002Fv1\u002F` protocol paths.\n- Diff access is restricted to workspaces associated with known sessions.\n- Grok UI contains no analytics or product telemetry.\n- Repository screenshots and diagrams use sanitized demo data only.\n\nFor remote use, set a long random token, place TLS or a private tunnel in\nfront of the server, and bind only to the interface you intend to expose:\n\n```bash\nHOST='\u003Cbind-address>' \\\nGROK_UI_TOKEN='\u003Clong-random-token>' \\\nnpm start\n```\n\nSee [SECURITY.md](SECURITY.md) for the full deployment and reporting guidance.\n\n## Configuration\n\n| Variable | Default | Purpose |\n| --- | --- | --- |\n| `HOST` | loopback | API bind interface |\n| `PORT` | `4310` | API port |\n| `GROK_HOME` | `~\u002F.grok` | Grok state directory |\n| `GROK_BIN` | `grok` | Grok executable used by the ACP controller |\n| `GROK_UI_TOKEN` | empty | Required for non-loopback binding |\n| `GROK_UI_STATE_DIR` | `~\u002F.grok-ui` | Private annotations and managed-session state |\n| `GROK_UI_AGENT_TOKEN` | empty | Required dedicated bearer token for host-agent mode |\n| `GROK_UI_AGENT_CONTROL_TOKEN` | empty | Optional, distinct token that enables secure remote sessions on the host |\n| `GROK_UI_AGENT_HOST` | `127.0.0.1` | Host-agent bind interface |\n| `GROK_UI_AGENT_PORT` | `4311` | Host-agent port |\n| `GROK_UI_AGENT_LABEL` | system hostname | Optional host label advertised by the agent |\n\n## Commands\n\n```bash\nnpm run dev       # Run API and Vite with file watching\nnpm run doctor    # Check Node, Grok CLI, authentication, and local state\nnpm run setup     # Run preflight checks and create a production build\nnpm run check     # Type-check client and server\nnpm test          # Run unit and integration tests\nnpm run test:e2e  # Run production browser onboarding and control tests\nnpm run build     # Produce client and server builds\nnpm run verify    # Check, test, and build\nnpm run release:check # Audit the exact package contents\nnpm run test:package  # Install and launch the packed artifact in isolation\nnpm start         # Build when needed, then serve the production app\nnpm run agent     # Serve the built host agent; control remains opt-in\nnpm run serve     # Serve an existing production build without rebuilding\n```\n\n## Repository map\n\n```text\nserver\u002F\n  grok-controller.ts      ACP lifecycle, prompts, approvals, cancellation\n  workflow-state.ts       workflow notification projection and safe controls\n  live-monitor.ts         active process and runtime event projection\n  usage-ledger.ts         provenance-aware durable usage reporting\n  session-projection.ts   shared local session-to-row projection\n  host-agent.ts           read-only monitoring and opt-in session control\n  remote-command-store.ts durable command reconciliation and audit evidence\n  fleet-protocol.ts       versioned parsing, caps, and host namespacing\n  fleet-registry.ts       atomic private connection registry\n  fleet-connectors.ts     bounded direct, Tailscale, and SSH transports\n  fleet-monitor.ts        polling, compatibility, health, and freshness\n  grok-store.ts           historical metadata aggregation\n  session-reader.ts       bounded conversation and tool timeline\n  session-state.ts        durable managed lanes and local annotations\n  preview-supervisor.ts   loopback web preview lifecycle and bounded logs\n  workspace-inspector.ts  live Git status and bounded diff inspection\n  security.ts             local and remote access gate\nsrc\u002F\n  views\u002FControlView.tsx   command deck and approval queue\n  views\u002FWorkflowsView.tsx cross-session workflow command field\n  views\u002FUsageView.tsx     time- and dimension-based usage ledger\n  views\u002FFleetView.tsx     fleet page coordination and registry actions\n  views\u002Ffleet\u002F            status, editor, selectors, and telemetry panels\n  views\u002FChangesView.tsx   live repository change workbench\n  views\u002FSessionWorkbench.tsx\n                            local session timeline, preview, and operations\n  views\u002FRemoteSessionWorkbench.tsx\n                            live remote conversation and safe controls\n  App.tsx                 dashboard shell and event-stream client\n  styles\u002Ffleet.css        Fleet-only presentation\n  styles\u002Fminimal-calm.css isolated quiet-theme presentation layer\n```\n\nThe longer design and trust-boundary notes live in\n[docs\u002Farchitecture.md](docs\u002Farchitecture.md). Concrete edit routing and safety\ninvariants live in [docs\u002FAGENT_GUIDE.md](docs\u002FAGENT_GUIDE.md).\n\n## Project status\n\nGrok UI is a community project. Its local monitor, control, workbench, runtime,\nusage, and Git inspection paths are functional and covered by automated tests.\nv0.10 multi-machine monitoring is released. Packed releases are installed and\nlaunched in isolation on macOS and Linux CI. Grok Build, ACP, and the fleet\nprotocol can evolve, so compatibility fixes may be needed for future releases.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",2,"2026-07-29 02:30:05","CREATED_QUERY"]