DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

wxfiveopps1102 /

wxfiveopps1102/dsh-tool-codex-computer-use

Verified

Delegate one-shot desktop and text tasks from DSH to your local Codex CLI, with model, reasoning and service-tier controls.

★ 0 Stars0 Forks0 IssuesN/A Community rating0 Confirmed installs
View on GitHubProject homepage
READMESource: main@2c2dcab4

dsh-tool-codex-computer-use

English | 简体中文

license DSH macOS | Windows validate

Delegate one-shot desktop and text tasks from DeepSeek Harness (DSH) to your local Codex CLI, with configurable models, reasoning effort and service tiers.

Preview

Live capture: computer_use_codex completed a category search on Amazon Japan.

Features

  • Desktop and text modes: use computer_use_codex for desktop automation or a one-shot text task.
  • Model controls: choose a model, reasoning effort and service tier per call or through plugin defaults; results show the effective overrides and their sources.
  • Environment inspection: computer_use_codex_status reports CLI and desktop app versions, models, authentication metadata and platform details.
  • Verifiable results: inspect returned text, screenshot paths and local logs; timeout handling attempts graceful termination before forcing the process to stop.
  • macOS and Windows validation: real desktop runs include macOS Calculator and Windows Notepad; see Compatibility.
  • Small Host bundle: no runtime dependencies; registers tools through ctx.tools and invokes the CLI selected by codexBin.
  • No automation primitives: clicking, scrolling, typing and screenshots are performed by Codex's own computer-use plugins; this plugin only delegates, applies parameters and returns results.

Each task starts a fresh codex exec process. Calls are independent and cannot continue a session or ask follow-up questions. Existing measurements suggest about 3–5 seconds of startup overhead; actual timings vary. DSH's built-in subagent_codex serves a separate role as a subagent provider; the two can coexist.

Related work

The DSH community already has several computer-use plugins. The following overview reflects research dated 2026-11-12; these projects take different approaches to desktop control.

Project Platform Approach
fangchenghao/dsh-computer-use macOS Accessibility-first; fresh observations, stale-state rejection and scoped permissions.
@wangyong1972/dsh-computer-use-macos macOS Screenshots with native mouse and keyboard control.
dsh-plugin-computer-use Windows / macOS / Linux Cua Driver's in-process Rust SDK.
MoyuDRCC/dsh-computer-use Windows Element targeting through UI Automation.
gxpppp/dsh-computer-use Windows Reuses Codex's native helper.
JHyugou/dsh-computer-use Windows Provides 25 tools.

What this plugin offers

Aspect This plugin's approach
Two modes The same computer_use_codex tool handles desktop operations with mode=desktop and text-only delegation with mode=text.
Bring your own CLI and choose model controls codexBin can select any local Codex CLI installation, independent of DSH's bundled 0.153.4 in the snapshot above. Configure the model, reasoning effort and service tier through model, reasoningEffort and serviceTier.
Environment inspection computer_use_codex_status reports the model catalog, plan metadata, CLI and desktop app versions, and an online CLI version comparison.
Cross-platform validation Both macOS and Windows 11 have been tested; see Compatibility.

Limitations

Limitation Practical impact
No accessibility tree or element targeting Control relies mainly on coordinates and visual observations, with less precision at the control level than accessibility-first implementations.
Local Codex CLI required The CLI must be installed and signed in on the host machine.
A separate process for every call Each call incurs a cold start of a few seconds; existing measurements suggest about 3–5 seconds.
No permission scopes or approval panel Security boundaries depend on securityMode and Codex's own controls.

When to choose another plugin: For element-level precision, choose an accessibility-first implementation such as fangchenghao/dsh-computer-use, or evaluate MoyuDRCC/dsh-computer-use for Windows UI Automation. For cross-platform control through an in-process SDK without a separate Codex CLI dependency, consider the Cua Driver-based dsh-plugin-computer-use.

Requirements

  • DSH in the 0.2.2 release line; recorded end-to-end validation used 0.2.2-rc.2.
  • Node.js >=20. Repository CI uses Node.js 24.
  • An installed, signed-in Codex CLI. Recorded validation used 0.167.2; the plugin uses your local installation.
  • For desktop tasks: the required computer-use/browser plugins and an available desktop session. On macOS, grant Accessibility and Screen Recording permissions to the relevant Codex/host application.
  • An existing working directory for cwd. See Compatibility for tested environments and remaining gaps.

Install

The repository root is the installable DSH bundle: package.json points to cordis.patch.yml. Choose the intended DSH profile; replace desktop below if your profile has a different name. Fresh-profile installation has not yet been verified; existing validation used a locally linked bundle.

From the Git repository

With dsh on your PATH:

dsh plugin --profile desktop add git+https://github.com/wxfiveopps1102/dsh-tool-codex-computer-use.git

After installation, enable the bundle in DSH's Plugins page. When replacing an installed version, restart the Host process to load the new module.

From the DSH Plugins page

Open Plugins → Add plugin, enter the Git installation target below, install it, and enable the bundle:

git+https://github.com/wxfiveopps1102/dsh-tool-codex-computer-use.git

Repository: wxfiveopps1102/dsh-tool-codex-computer-use. A community catalog listing is not required for this route; catalog inclusion remains planned.

By npm package name (recommended)

Published on npm as dsh-tool-codex-computer-use@0.1.0.

dsh plugin --profile desktop add dsh-tool-codex-computer-use

Confirm the version with npm view dsh-tool-codex-computer-use version. See the release record.

Usage

Once the plugin is enabled, call its tools from DSH. The JSON below contains tool arguments, not shell commands.

Desktop task — mode=desktop

Call computer_use_codex to calculate a value and request a screenshot:

{
  "task": "Open Calculator, calculate 7 × 8, and verify the result with a screenshot.",
  "mode": "desktop",
  "cwd": "/absolute/path/to/workspace",
  "timeoutSeconds": 600
}

Replace cwd with an existing directory; on Windows, for example, use C:/path/to/workspace. Desktop mode is the default. Screenshots are requested as .jpg in <cwd>/.codex-cu/ unless configured otherwise; a prompt does not guarantee that screenshots are created.

Text task — mode=text

Call computer_use_codex for a one-shot explanation:

{
  "task": "Explain what 7 × 8 means in one sentence.",
  "mode": "text",
  "timeoutSeconds": 600
}

Text mode omits desktop/screenshot instructions and screenshot-directory creation. It keeps the configured security mode and does not disable Codex plugins. mode is a call argument only, with no config or environment default.

Call parameters

Parameter Meaning / default
task Required, non-empty task description.
mode desktop (default) or text.
verify String: strict (default), final or none. strict verifies each action with a screenshot; final takes one confirmation screenshot at completion. Both first check that the page/window/category matches the task, stopping and reporting any mismatch. none requires no screenshots, for text-only or trusted tasks; forced to none in mode=text. The result object echoes the effective verify value.
ephemeral Boolean, default false. When true, adds --ephemeral to codex exec so session files are not written to disk, reducing leftover files without changing output.
cwd Existing working directory; defaults to the Host process directory.
timeoutSeconds Integer, 30–3600; call argument > config > environment > 600.
model Model ID; inherits the defaults under Configuration.
reasoningEffort Reasoning effort; follows the same precedence as model.
serviceTier Service tier; follows the same precedence as model.

Environment inspection

Call computer_use_codex_status with {}. It returns environment JSON directly, without the task result's ok/output wrapper, and does not run a desktop task or create screenshot directories.

Field Meaning
platform, platformLabel, osVersion Platform identifier, readable platform name and OS version.
codexVersion CLI version from codex doctor --json, or unknown.
latestCodexVersion Latest version from npm, or null when checking is disabled or fails.
upToDate true if the local version is at least the npm latest, false if older, or null if comparison is unavailable.
desktopAppVersion, authMode Desktop app version and stored authentication mode from doctor, or unknown.
planType Local JWT's chatgpt_plan_type claim, or null.
subscriptionActiveUntil Local JWT's chatgpt_subscription_active_until claim, or null; not a live entitlement check.
models Catalog objects containing slug, displayName, efforts and serviceTiers; defaults to [].
warnings Non-fatal source failures, bundled-catalog notices and upgrade suggestions; [] when none occur.

The sources are codex debug models, codex doctor --json and $CODEX_HOME/auth.json (default ~/.codex/auth.json). Source results are cached for five minutes per resolved CLI path and online-check setting in the current process. A source failure adds a warning while preserving other results; CLI entry resolution must succeed first. Use planType with models when selecting a model; Codex validates the final selection.

Task results

computer_use_codex returns ok, exitCode, mode, codexVersion, warnings, durationMs, output, controls, securityMode, securityNotice and, when available, logPath. ok:true means successful CLI exit, not achievement of the task objective. Review screenshots for desktop tasks and returned text for text tasks.

Output is limited to 8000 JavaScript characters. Full logs remain in a private system temporary directory in both modes; final-message files are deleted. See Security for retention and permission boundaries, and the architecture guide (Chinese) for the complete output contract.

Configuration

For model, reasoningEffort and serviceTier, each field resolves independently as call argument > plugin config > environment variable > local Codex configuration (~/.codex/config.toml). Omitting a call argument still uses any config or environment default. timeoutSeconds uses the same first three levels, then falls back to 600.

Other settings use apply(ctx, config) values before their environment defaults. Environment variables must reach the Host process; setting them only in a shell tool may not work. The online-check switches are an exception: either disabling switch takes effect, as described below.

Config Environment Default
codexBin DSH_CODEX_BIN executable codex on PATH, then $DSH_PROFILE_DIR/node_modules/@openai/codex/bin/codex.js
securityMode DSH_CODEX_SECURITY_MODE bypass
timeoutSeconds DSH_CODEX_TIMEOUT_SECONDS 600 (integer, 30–3600)
terminateGraceMs DSH_CODEX_TERMINATE_GRACE_MS 5000 milliseconds (integer, 0–30000; 0 skips graceful termination)
screenshotDir DSH_CODEX_SCREENSHOT_DIR <cwd>/.codex-cu/
model DSH_CODEX_MODEL inherit the local Codex configuration
reasoningEffort DSH_CODEX_REASONING_EFFORT inherit the local Codex configuration
serviceTier DSH_CODEX_SERVICE_TIER inherit the local Codex configuration
onlineCheck DSH_CODEX_OFFLINE enabled; config false or environment 1 disables inspection's online checks

CLI resolution is config → environment → PATH → profile. Explicit entries must be file paths, not shell commands; invalid explicit entries fail without fallback. Task calls report resolution failures as readable ok:false results. JavaScript entries use DSH_NODE_EXECUTABLE or the current runtime with ELECTRON_RUN_AS_NODE=1. Relative screenshot paths resolve against cwd.

There is no schemastery Config export or promised automatic configuration UI: workspace-linked imports failed, profile resolution is unverified, and the plugin has no runtime dependencies.

Model × reasoning effort matrix (snapshot, 2026-11-12)

This is the user-supplied snapshot of the live catalog on 2026-11-12; it was not fetched again for this documentation update.

Model Supported efforts
gpt-6.1-sol low / medium / high / xhigh / max / ultra
gpt-6-astra low / medium / high / xhigh / max / ultra
gpt-6.1-terra low / medium / high / xhigh / max / ultra
gpt-6-sol low / medium / high / xhigh / max / ultra
gpt-5.6-sol low / medium / high / xhigh / max / ultra
gpt-5.6-terra low / medium / high / xhigh / max / ultra
gpt-reserve low / medium / high / xhigh / max
gpt-6-luna low / medium / high / xhigh / max
gpt-5.6-luna low / medium / high / xhigh / max
codex-auto-review low / medium / high / xhigh / max

ultra = max reasoning + automatic task delegation, creating additional subtasks and token costs. Codex validates reasoning efforts; invalid values return HTTP 400. Actual availability varies with the subscription plan and CLI version; use models[].efforts returned by computer_use_codex_status as the source of truth.

Model and service-tier defaults

Example plugin entry in cordis.patch.yml:

- insert:
    - id: tool-computer-use-codex
      name: 'dsh-tool-codex-computer-use'
      config:
        model: gpt-6-astra
        reasoningEffort: high
        serviceTier: priority

The Fast service tier ID is priority; check the model's returned serviceTiers before selecting it. Defaults can also be set with DSH_CODEX_MODEL, DSH_CODEX_REASONING_EFFORT and DSH_CODEX_SERVICE_TIER.

The returned controls string lists effective overrides and sources, separated by spaces. With the config example above and no call overrides:

model=gpt-6-astra(config) reasoningEffort=high(config) serviceTier=priority(config)

reasoningEffort=high(config) comes from plugin config; reasoningEffort=low(environment) comes from the environment; reasoningEffort=low without a suffix comes from a call argument. Fields not listed inherit the local Codex configuration. If no fields are overridden, the entire string is inherited from Codex config; it does not report inherited values themselves.

Online checks and caching

Online checking is enabled by default. The plugin queries https://registry.npmjs.org/@openai/codex/latest; successful and failed queries are cached for six hours in the current process and shared by the task and status tools. Each status response adds the version comparison to a copy of the cached source results.

Set onlineCheck: false or DSH_CODEX_OFFLINE=1 to disable these online checks; latestCodexVersion and upToDate then return null. The model catalog normally refreshes through codex debug models; a failure falls back to codex debug models --bundled with a warning. With online checking disabled, it uses --bundled directly and adds an offline-catalog warning. These switches control inspection, not networking by delegated tasks.

How it works

DSH → ctx.tools → computer_use_codex → local codex exec → result + local evidence
  1. The bundle patch loads index.js, which registers computer_use_codex and computer_use_codex_status as Host tools.
  2. A task call validates arguments, resolves configuration and locates the chosen CLI.
  3. A preflight runs codex --version and compares it with the cached npm latest. Version probes, including failures, are cached by entry path for the current process. A failed probe returns unknown with a warning; a failed npm query leaves comparison unavailable. Neither blocks execution.
  4. A fresh codex exec runs with the selected model controls and security flags. Desktop mode adds desktop/screenshot instructions; text mode omits them.
  5. The plugin captures the final message, execution status and log path. On timeout, it attempts graceful termination, then forces termination after terminateGraceMs.

See the architecture, overview and optimization notes for technical detail (Chinese).

Security

The default securityMode is bypass. It passes --dangerously-bypass-approvals-and-sandbox, disabling CLI approvals and the sandbox so tasks can affect the local desktop and files. Use it only for tasks and environments you trust. workspace-write passes --sandbox workspace-write; real GUI behavior in that mode remains unverified and may fail. Results include securityMode and securityNotice.

Text mode retains the same security setting and available plugins. A filesystem sandbox does not guarantee containment of external GUI plugins. Timeouts cannot undo desktop effects, and descendants outside the targeted process tree or group may remain. Host cancellation through execute's exec argument is not integrated because the signal contract remains unverified; bounded timeout is implemented.

Logs and screenshots may contain sensitive data and require manual cleanup. The status tool only decodes the required JWT claims locally; it does not output or transmit tokens. Subscription metadata is a local claim snapshot, not a live entitlement check; a past timestamp alone does not establish that benefits have ended. Delegated Codex tasks use your configured authentication, plugins and network access. See the detailed safety guide (Chinese).

Compatibility

Platform mode=text mode=desktop Recorded environment / evidence
macOS Tested Tested DSH 0.2.2-rc.2 + Codex CLI 0.167.2; Calculator 3×9=27; earlier 7×8=56 evidence also exists.
Windows Tested Tested Windows 11 Pro + DSH 0.2.2-rc.2 + Codex CLI 0.167.2; Notepad contained hello, with three screenshots and a status bar showing 5 characters.
Linux Not verified Not verified; no desktop-support claim Requires separate validation. Ubuntu CI only checks syntax, manifest and packaging.

The existing cross-platform validation is dated 2026-11-12; desktop tests were not rerun for this documentation update. The macOS OS version was not recorded. Windows used DSH Desktop's desktop profile, Node v24.14.0, npm 11.9.0 and ChatGPT login (planType: prolite). Both platforms passed smoke, status, text and desktop checks; status returned 10 models with warnings: [].

Windows results correspond to commit e99d5a4: text completed in 52.3 s and desktop in 100.5 s. After manually restarting DSH, both tools succeeded on their first calls, with no must declare output warning, application: applied and warnings: []. Full evidence is in the cross-platform release record; the Windows test guide retains an earlier temporary-fix test record.

Remaining gaps include Linux desktop behavior, real GUI tasks under workspace-write, clean-profile installation and npm installation/publication. The model matrix is a dated snapshot; availability depends on the selected CLI and account.

Development

Repository layout

.
├── .github/workflows/validate.yml  # Syntax, manifest and package checks
├── .gitignore
├── index.js                        # Host tools and CLI execution
├── cordis.patch.yml                # DSH bundle loader patch
├── package.json                    # Package metadata and dsh.bundle
├── icon.svg
├── locale/
│   ├── en.json
│   └── zh.json
├── docs/
│   ├── ARCHITECTURE.md
│   ├── DETAIL.md
│   ├── OPTIMIZATION.md
│   ├── OVERVIEW.md
│   ├── PUBLISHING.md
│   ├── WINDOWS-TEST.md
│   └── assets/amazon-ranking.jpg   # Redacted preview
├── test/smoke.mjs                   # Fake-CLI smoke tests
├── README.md
├── README.zh.md
├── RELEASE.md                      # Validation and publication record
└── LICENSE

From the repository root, with Node.js 24 and npm available:

node --check index.js
node --input-type=module -e 'import fs from "node:fs"; import assert from "node:assert/strict"; const pkg = JSON.parse(fs.readFileSync("package.json", "utf8")); assert.equal(pkg.dsh?.bundle?.patch, "./cordis.patch.yml"); assert.ok(fs.statSync(pkg.dsh.bundle.patch).isFile());'
npm pack --dry-run

GitHub Actions runs these checks on Ubuntu with Node.js 24 for pushes and pull requests. The workflow does not run desktop tasks or publish a package.

For runtime changes, run the existing smoke suite separately:

node test/smoke.mjs

On macOS, the DSH-bundled runtime is another option:

ELECTRON_RUN_AS_NODE=1 "/Applications/DeepSeek Harness.app/Contents/MacOS/DeepSeek Harness" test/smoke.mjs

Smoke tests use fake CLIs and do not operate the desktop. Windows uses .js fixtures via the Node launcher; other platforms use shell fixtures. Coverage includes registration failure handling, CLI commands and three real 30-second timeout cases. POSIX checks TERM handling and KILL escalation; Windows checks bounded timeout and taskkill requests. These tests do not establish real desktop compatibility.

Troubleshooting

Symptom What to check
Tools do not appear Confirm that the bundle is installed and enabled in the intended profile; restart the Host after replacing the package.
Codex entry cannot be found Set codexBin or DSH_CODEX_BIN to a valid file path. An invalid explicit path fails without fallback; on Windows, check the actual executable or codex.js path.
Model or reasoning effort is rejected Inspect computer_use_codex_status.models, especially efforts and serviceTiers; use values available to the selected CLI and account.
CLI version or catalog appears stale Upgrade the installation actually selected by config / environment / PATH / profile, then restart the Host to clear process-local caches.
Desktop access fails Check authentication, required plugins, desktop permissions and securityMode; GUI behavior under workspace-write remains unverified.
ok:true, but the result is wrong or no screenshot exists Verify the returned text and actual screenshot evidence; successful CLI exit alone does not prove task completion.
A task times out or leaves a session behind Review logPath, timeoutSeconds and terminateGraceMs; prior desktop effects and detached descendants may remain.
npm cannot find the package npm publication is planned; use the Git repository installation route.

For a profile-local CLI installation, the recorded-version upgrade example is npm install --prefix ~/.dsh/profiles/desktop @openai/codex@0.167.2; adjust the profile path. This is a manual example, not an automatic upgrade or a claim about the latest version. An explicit CLI path or PATH entry may take precedence over that installation.

Timeout handling first requests taskkill /pid PID /T on Windows and adds /F when forced termination is needed. POSIX sends SIGTERM to the child process group, then SIGKILL. Failed tree/group termination falls back to child.kill(signal). terminateGraceMs is a plugin setting, not a call argument; setting it to 0 skips the graceful step.

Windows screenshot paths may use forward slashes; use the returned absolute path. Historical .png screenshots can contain JPEG bytes; current prompts request .jpg without renaming old files. On macOS, a virtual mouse or sharing indicator can remain after the task process exits. For manual cleanup:

pkill -f SkyComputerUseClient
killall SkyComputerUseService 2>/dev/null

This affects any ongoing Codex computer-use sessions. The plugin does not run these commands automatically.

Contributing

Issues and pull requests are welcome. Include your OS, DSH and Codex CLI versions, the task mode, expected result and redacted diagnostic output. Keep README.md and README.zh.md aligned, run the development checks, and distinguish fake-CLI tests from real desktop evidence. Do not commit authentication files, tokens, private logs or unredacted screenshots.

See RELEASE.md for validation history and publication work still pending.

License

MIT © 2026 wx5.

—/ 5

No ratings yet

Verified DSH bundle

Commit 2c2dcab48e17

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout