Dexly Companion

Dexly Companion is the local native-messaging bridge that connects the Dexly Chrome extension to Codex, OpenCode, DeepSeek Harness, or Cursor Agent on macOS, Windows, and Linux. Codex uses its app-server protocol; the other three runtimes use Agent Client Protocol (ACP) v1 for Code and Web Assist.

Requirements

• macOS, Windows, or Linux
• Google Chrome
• Node.js 20+

The public npm install flow and repo-local Node workflow scripts are cross-platform.

Install

npx -y @dexlyai/dexly install
npx -y @dexlyai/dexly doctor
npm install -g @openai/[email protected]

The pinned Codex command installs, upgrades, downgrades, or repairs Codex to the version tested with Dexly. Update ../DexlyProtocol/src/codex-compatibility.json when Dexly moves to a different compatible Codex release; the shared protocol constants, extension guidance, and guided Companion installer all derive from it.

OpenCode is installed only after explicit consent from the extension. Dexly first reuses an exactly compatible executable from PATH or OpenCode's standard ~/.opencode/bin directory. Only when none is available does it create a private managed installation pinned to 1.18.18:

npx -y @dexlyai/dexly install-opencode
opencode auth login

On macOS, the managed fallback installs OpenCode's official native Darwin package directly instead of the cross-platform opencode-ai wrapper, whose universal npm launcher is named opencode.exe. Local models can be configured through OpenCode without provider credentials.

Alternative global install:

npm i -g @dexlyai/dexly
dexly install

Update

npx -y @dexlyai/dexly upgrade

Publish

From the companion repo:

npm run release:set-version -- 0.1.5
npm run publish:npm:latest

Other channels:

npm run publish:npm:beta
npm run publish:npm:canary

Release policy and the publishable companion version are maintained from one manifest:

• release/companion-release.json

Sync derived files without changing the version:

npm run release:sync

npm run release:set-version -- <semver> updates the manifest version and syncs the derived files. Review minimumVersion and recommendedVersion in the same manifest before publishing if the rollout policy should change with that release.

Commands

• install: install or repair the companion, launcher, and Chrome native-host manifest
• doctor: verify the install layout, launcher, manifest, and local Codex availability
• upgrade: install a newer companion version and repoint the active install
• rollback: reactivate the previous known-good companion version
• install-codex: install Codex through npm using the companion's captured tool paths
• install-opencode: reuse a compatible OpenCode when present; otherwise install and verify the pinned runtime in Dexly's agent/version-specific managed directory
• install-deepseek: install and verify the exact DeepSeek Harness package in Dexly's agent/version-specific managed directory
• host: run the native host on stdin/stdout
• version: print the companion package version

Codex

Dexly Companion does not silently install Codex during companion install. If Codex is missing, Dexly prompts from the extension after companion health succeeds.

Manual Codex install:

npm install -g @openai/[email protected]

This exact-version command is used for both installation and updates. The source of truth is ../DexlyProtocol/src/codex-compatibility.json.

OpenAI Codex CLI docs: https://help.openai.com/en/articles/11096431-openai-codex-ci-getting-started

OpenCode Beta

The Companion resolves OpenCode in this order: DEXLY_COMPANION_OPENCODE_PATH for development, a compatible managed 1.18.18 installation, then an exactly compatible executable on PATH or in ~/.opencode/bin. The consent-driven Install action checks the existing executable first and skips npm entirely when it is compatible. It verifies opencode --version and launches the executable directly with the single acp argument; no shell is involved.

On macOS, a native host launched by Chrome can propagate com.apple.quarantine to files created by the managed npm install. The pinned OpenCode Darwin binaries are not validly Developer ID-signed, so Gatekeeper otherwise reports that opencode is damaged. Dexly pins the expected SHA-256 for both supported macOS architectures, verifies the package binary and its managed copy, and only then removes quarantine from that one managed executable before the version check. A digest mismatch fails the installation without removing quarantine.

ACP JSON-RPC remains unchanged inside agent-neutral native bridge envelopes. The existing fragmentation, backpressure, bounded/redacted stderr diagnostics, crash handling, and orderly shutdown apply to both drivers. Each Chrome native-messaging port owns one agent process, so OpenCode Code and Web Assist run independently even when both select OpenCode.

Companion 1.2.0 adds the web-readonly profile. It launches OpenCode from a stable Companion-owned directory for browser-only work (or opens the exact selected workspace through ACP), redirects user/global configuration discovery into that private profile, enables pure mode, disables project config, plugins, external skills, and automatic LSP downloads, passes a deny-by-default inline policy, permits only local read, glob, grep, and LSP reads, disables all other tools, and passes no ACP MCP servers. The inline policy carries only the user's global OpenCode provider, model, and small_model settings (read from ~/.config/opencode/{config.json,opencode.json,opencode.jsonc} and OPENCODE_CONFIG), so Web Assist keeps the user's configured models, including local Ollama providers, instead of silently falling back to OpenCode's hosted default model; every other user setting is ignored and the policy keys always win. Every Companion-hosted OpenCode process (Code and Web) also runs with OPENCODE_DISABLE_FFF=1 and OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER=1: OpenCode's native fuzzy-file-finder and file-watcher libraries are extracted to the temp directory and loaded at prompt time, and under a quarantine-aware browser such as Chrome on macOS that file inherits com.apple.quarantine, which makes the load block on Gatekeeper and stalls the turn. Managed OpenCode and DeepSeek Harness installs are likewise cleared of quarantine recursively on macOS because npm install under Chrome quarantines every installed file, including native addons. The policy and environment are never included in health metadata. OpenCode Web Assist has its own minimum Companion version; the global Codex minimum is unchanged.

DeepSeek Harness Beta

Companion 1.3.0 installs exact package @deepseek-ai/[email protected], requires Node.js 22.19 or newer, and launches dsh --profile acp. Configure credentials with DEEPSEEK_API_KEY in the Companion launch environment or $DSH_HOME/.credentials.yaml; DeepSeek Harness has no dsh auth command. The Web profile launches with DSH_PERMISSION_MODE=read-only, while Code uses workspace-write.

Cursor Agent Beta

Cursor Agent is user-managed. Companion resolves only the explicit cursor-agent executable, verifies a dated release at or after 2026.05.24, and launches cursor-agent acp; it never guesses a generic agent binary or installs Cursor. Companion probes cursor-agent status without retaining account identity. The extension's Sign in to Cursor action runs Cursor's supported browser flow (cursor-agent login), waits for the CLI to finish, verifies the new status, and then performs the ACP cursor_login handshake. cursor-agent login, CURSOR_API_KEY, and CURSOR_AUTH_TOKEN remain supported external fallbacks; while sign-in is required the extension refreshes health so an external login is detected. Web Assist forces the ACP session into Cursor's read-only Ask mode and still rejects every permission request in the extension.

Development Reference

This workspace includes a sparse upstream Codex SDK TypeScript checkout at ../codex/sdk/typescript/. Use it as the local reference before changing Codex thread/turn contracts, streaming events, item shapes, image input handling, environment/config propagation, abort behavior, or the companion's assumptions about CLI communication.

Dexly's shared app-server contract lives in ../DexlyProtocol/src/codex-app-server.ts; keep that compatibility layer, the extension transport, and src/codex-host.ts aligned with the SDK reference unless an intentional lower-level JSON-RPC difference is documented in docs/DexlyCompanionTechnical.md.