<p align="center">
  <img src="cpu-workers/assets/ke-studios-hinge-dark.png" width="88" alt="K&E Studios Hinge mark" />
</p>

# 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](https://kestudios.dev):

| Package | What it shows | Command |
|---|---|---|
| [cpu-workers](cpu-workers/) | Local multiprocessing pools, registered job shards, generation-safe progress | `/cpu` |
| [gpu-workers](gpu-workers/) | Apple GPU / Metal / MPS lane ownership, queue, and owner-published job facts | `/gpu` |

![CPU Workers showing six local process shards](cpu-workers/assets/screenshot.png)

![GPU Workers showing the Apple GPU, one active MPS owner, queued work, and a stale registration](gpu-workers/assets/screenshot.png)

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.

## 60-second quickstart

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

```sh
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:

```sh
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`](.mcp.json) and [`.claude/skills/`](.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

| Variable / path | Package | Purpose |
|---|---|---|
| `~/.ke/cpu-workers/jobs/*.json` | CPU | Registered `ke.cpu-job.v1` / `v2` / `v3` manifests |
| `KE_CPU_JOBS_ROOT` | CPU | Override the jobs directory |
| `KE_CPU_RETENTION_HOURS` | CPU | Retire unchanged manifests with no live process after this many hours (default `24`, `0` keeps all) |
| `KE_CPU_MAX_POOLS` | CPU | Pools listed per snapshot, live first (default `50`, `0` lists all) |
| `KE_CPU_SOLO_PATTERN` | CPU | Optional regex for detached single-process jobs to surface (off by default) |
| `~/.ke/gpu-workers/jobs/<job-id>.json` | GPU | Owner-published `ke.gpu-job.v1` records |
| `KE_GPU_RETENTION_HOURS` | GPU | Retire finished or stale records older than this many hours (default `24`, `0` keeps all) |
| `KE_GPU_MAX_JOBS` | GPU | Jobs listed per snapshot, active first (default `50`, `0` lists all) |
| `CPU_WORKERS_PLUGIN_ROOT` | CPU | Renderer / CLI fallback root |
| `GPU_WORKERS_PLUGIN_ROOT` | GPU | Renderer / CLI fallback root |

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](cpu-workers/SECURITY.md) and [gpu-workers/SECURITY.md](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](https://kestudios.dev)). Licensed under [Apache License 2.0](LICENSE). The K&E Studios name and Hinge mark identify the original project; see [TRADEMARKS.md](TRADEMARKS.md).