Workers

See the CPU pools and the Apple GPU lane your Mac is actually using, without leaving Claude Code or Codex.

This repository is one public source tree with two read-only MCP Apps by kestudios.dev:

Both screenshots are synthetic demo data. Neither App starts, stops, signals, schedules, or otherwise mutates work.

Why this exists

Coding agents can talk about jobs they cannot see. CPU Workers names the process pools on the machine, reports CPU as logical-core equivalents and host capacity, and refuses to invent progress. GPU Workers treats a single Apple GPU as a scarce lane: one active MPS owner is the default, later work is a queue, and host-wide ioreg counters are never assigned to a PID.

Related MCP server: Claude Telemetry MCP

60-second quickstart

Requires macOS, Node.js 20 or newer, and a local Chromium or Google Chrome for the UI tests.

npm --prefix cpu-workers install
npm --prefix gpu-workers install
npm --prefix cpu-workers test
npm --prefix gpu-workers test
node cpu-workers/scripts/status-cli.mjs
node gpu-workers/scripts/status-cli.mjs

status-cli.mjs prints a live text snapshot of this Mac. npm test uses fixtures plus the synthetic demo screenshots; it does not publish telemetry.

Install and use

Claude Code

From this repository root after the npm install commands above:

claude mcp add --transport stdio cpu-workers -- node "$(pwd)/cpu-workers/scripts/server.mjs"
claude mcp add --transport stdio gpu-workers -- node "$(pwd)/gpu-workers/scripts/server.mjs"
mkdir -p "$HOME/.claude/skills" "$HOME/plugins"
ln -sfn "$(pwd)/cpu-workers" "$HOME/plugins/cpu-workers"
ln -sfn "$(pwd)/gpu-workers" "$HOME/plugins/gpu-workers"
ln -sfn "$(pwd)/cpu-workers/skills/cpu" "$HOME/.claude/skills/cpu"
ln -sfn "$(pwd)/gpu-workers/skills/gpu" "$HOME/.claude/skills/gpu"

Or skip the claude mcp add lines and open this folder as the Claude Code project: .mcp.json and .claude/skills/ already register both servers and skills.

Start a new Claude Code session, then:

• /cpu opens the CPU Workers viewer

• /cpu status returns plain text

• /gpu opens the GPU Jobs / MPS Lane viewer

• /gpu status returns plain text

The same ./install.sh script prints those commands with absolute paths after installing package dependencies.

Codex

Each package is a Codex plugin (.codex-plugin/plugin.json, .mcp.json, skill, and UserPromptSubmit hook).

1. Run npm --prefix cpu-workers install and npm --prefix gpu-workers install.

2. Add the absolute cpu-workers and gpu-workers directories to a Codex local marketplace ($plugin-creator can do this) and install cpu-workers and gpu-workers.

3. Start a new Codex task so the skill, hook, and MCP server load together.

4. Invoke /cpu or /gpu.

A plugin install does not hot-reload an already-open task. Each package can render a truthful PNG fallback with node scripts/render-live-viewer.mjs.

Features

CPU Workers

• Bare /cpu opens the live MCP App; /cpu status stays text-only.

• Generation-safe grouping: replacement PIDs are adopted only when entrypoint, output root, and immutable run binding match.

• Progress is LIVE, STALE, or UNAVAILABLE. Only LIVE is bar-eligible.

• Unregistered pools still get stable names from working directory and entrypoint.

• Registered jobs may publish shard names, receipt progress, bounded logs, retries, and handoff state.

• Large registries stay fast: unchanged manifests with no live process are retired after 24 h, reused PIDs are not mistaken for old jobs, and listings are capped with an explicit "N more" count.

GPU Workers

• Host-wide Apple GPU counters stay on the device card; jobs never inherit them.

• One active MPS owner per device is the default; overlapping exclusive owners are contention.

• Owner-published ke.gpu-job.v1 registrations add framework, lease, queue, progress, and memory facts.

• Optional adapters/gpu_job_telemetry.py publisher is write-on-the-workload-side only.

• Finished and stale history older than 24 h is retired from the view; active work is always listed first.

Configuration

No API keys, accounts, or network endpoints are required. MCP tools are local stdio, unauthenticated, and read-only.

Security and privacy

• Tools are annotated read-only. They cannot start, stop, signal, renice, restart, schedule, claim, or mutate a process or GPU job.

• Collection stays on the local Mac. The MCP UI loads no remote scripts, fonts, images, frames, or telemetry endpoints.

• Process names, paths, logs, receipts, and task IDs can still be sensitive. Do not publish a live snapshot.

• The committed screenshots and fixtures/demo-snapshot.json files are invented sample data.

See cpu-workers/SECURITY.md and gpu-workers/SECURITY.md.

Roadmap

• Public Codex Plugin Directory listing once a hosted HTTPS MCP endpoint and widget origin exist

• Claude Code plugin marketplace listing

• Richer registered-job schemas without weakening the unknown-stays-unknown contract

• Optional Nvidia NVML/CUDA telemetry remains out of scope for this Apple-silicon-first release

Credits

CPU Workers and GPU Workers are open-source MCP Apps by KE Studios (kestudios.dev). Licensed under Apache License 2.0. The K&E Studios name and Hinge mark identify the original project; see TRADEMARKS.md.