CCUH

The Problem

Computer Use depends on the intended app and window matching what Codex actually observes and where its input goes. CCUH was motivated by sessions where that connection was unreliable:

• Selecting an app could still bind observations and input to the wrong window.

• Switching windows during normal Mac use could disrupt the expected target.

• Repeated attempts continued silently, hiding targeting failures.

CCUH's goal is dependable Computer Use while you keep using your Mac. The intended target should be maintained and verified, and targeting failures should be surfaced promptly rather than silently retried.

Related MCP server: agent-prompt-capture

How It Works

The CCUH plugin bundles a local MCP server, Codex hooks, and a companion skill to make tool-call behavior observable:

• Observe: hooks record metadata before and after supported Computer Use calls.

• Pair: records are grouped by session and tool-call identifiers, keeping incomplete or conflicting pairs visible.

• Inspect: MCP tools expose connection diagnostics and recent call records inside Codex.

• Guide: the bundled skill provides app and window targeting guidance, including when to surface failures.

The MCP server runs as a local Node process on your Mac. No external server deployment or OpenAI API key is required.

CCUH's hooks and companion skill apply only to bundled Computer Use tasks. Coding, terminal commands, web search, and other MCP tools do not trigger observation. Codex may keep the MCP connection available while idle; this does not start window control or background monitoring.

Get Started

You need macOS, Node.js 24 or later, and Codex App or Codex CLI with Computer Use configured. Node.js must be available to the Codex process; CCUH uses your installed Node.js and does not bundle it.

1. Add the marketplace

codex plugin marketplace add Package-KR/CCUH

2. Install the plugin

Open Plugins in Codex App, or enter /plugins in Codex CLI. Find CCUH in the ccuh marketplace and install it.

The plugin provides the MCP server, Computer Use hooks, and companion skill together. You do not need to edit MCP server or user hook configuration files.

3. Review and restart

If Codex prompts for hook review, review and trust the CCUH hooks in your client. In Codex CLI, open /hooks.

Restart Codex App or start a new Codex CLI session, depending on which client you use. Then use CCUH during your Computer Use task.

Use one registration route. Do not enable the native plugin and manual registration at the same time.

If you cannot use the native plugin, run:

npx --yes github:Package-KR/CCUH setup

This installs a persistent local runtime in ~/.codex/ccuh/runtime, registers the MCP server and Computer Use hooks, and backs up configuration before changing it. Existing MCP servers and hooks are preserved.

Review the CCUH hooks when Codex prompts you. In Codex CLI, open /hooks. Then restart the Codex client or session you use.

Usage

Ask Codex:

While carrying out my app task with Computer Use, use CCUH to verify the intended window and report targeting failures.

An MCP response confirms connectivity. Real hook records show whether automatic observation is running.

Updates

After changes reach main, GitHub Actions validates the build and github-actions[bot] publishes the next patch version, version commit, tag, and GitHub Release. Users do not need a development checkout or a rebuild.

Codex handles marketplace refresh and installed plugin updates. CCUH does not add a background updater or modify its installed cache. If an update has not appeared, refresh the marketplace:

codex plugin marketplace upgrade ccuh

Codex may request review of changed hooks. If your client still uses the previous version after refreshing, start a new chat or restart the app.

Develop on dev and merge reviewed changes into main. CI runs on dev pushes and pull requests to dev or main, checking types, building the runtime, and checking the native Swift sources. Release calls the same CI workflow before publishing from main.

The Release workflow proceeds only after shared CI succeeds and checks out the exact verified commit. It keeps the package, lock file, plugin manifest, and runtime version in sync, rebuilds after incrementing the version, and publishes with the repository's GITHUB_TOKEN. Allow GitHub Actions to write to main and release tags.

For a minor or major increment, run Actions → Release → Run workflow with the desired bump. If the version commit and tag succeeded but GitHub Release publication failed, rerun the failed publish job or set repair_tag to the existing tag. This publishes the same version without another increment.

Concurrent pushes can be included in one release: CI checks the latest main, then the release uses that verified commit. A conflicting branch update stops publication without a force push.

Data

Records are stored in ~/.codex/ccuh/state/events.jsonl by default. They contain metadata such as timestamps, tool names, input-field types, and hashed identifiers.

Raw code, chat content, screenshots, and credentials are not stored.

Collection accepts only mcp__cua_repl__js and mcp__cua_repl__js_reset. Unknown tool names are excluded. Existing files are preserved; entries outside this scope are ignored when reading records.

The observed pre/post time difference includes hook, process, and storage overhead. It is not an app or window acquisition benchmark.

License

CCUH is distributed under the MIT License.