CLI, MCP and A2A integration

Local agents such as Codex and WorkBuddy can use OpenFiles through MCP or CLI + Skill. Both share file capabilities and task management with A2A. For everyday use, install the CLI and run setup below. A2A is for custom clients: /a2a is not an MCP URL, and the calling process must run on the same computer as OpenFiles.

Install the CLI

You need Node.js 22 or later and an OpenFiles desktop build containing resources/agent. The CLI ships with the desktop app; install it once from that local directory. For the default macOS installation:

npm install -g "/Applications/OpenFiles.app/Contents/Resources/agent"

On Windows, use PowerShell and replace the example with the resources\agent directory in your actual installation:

npm install -g "C:\path\to\OpenFiles\resources\agent"

For source development, run npm run build in the repository, then npm install -g ./dist/agent. You can then use the openfiles command without remembering the script path.

Connect Codex

Run the following command. It starts or connects to OpenFiles, registers MCP through the Codex CLI, and installs the companion skill in ~/.agents/skills/openfiles. The codex command must be available. Restart Codex afterward to load the configuration.

openfiles setup codex

Connect WorkBuddy

Run the following command. It starts or connects to OpenFiles and merges the server into ~/.workbuddy/mcp.json, preserving other servers and backing up the previous configuration. Restart WorkBuddy afterward. For CLI + Skill, optionally import the printed skillArchive ZIP through the skill upload entry. MCP is already ready to use.

openfiles setup workbuddy

The first setup creates and grants access to ~/OpenFilesAgent, with output in its output subdirectory. Put input files there and ask your agent to use OpenFiles, for example to export a CDR as a ZIP of all SVG pages, wait for completion and report the output location. Add --workspace DIR to use an existing directory and --output DIR to choose an output directory. --dry-run only previews setup paths.

Directory grants and the desktop path are saved in ~/.openfiles/agent/setup.json. Subsequent CLI, MCP and installed skill calls start the desktop using that setup and read the current address and token automatically. No fixed port or token goes into client configuration. To change the grants of a running gateway, quit OpenFiles and retry setup; existing tasks are never forcibly interrupted.

Official configuration references: Codex MCP · WorkBuddy MCP

Check the connection and troubleshoot

doctor checks connectivity without starting the app; capabilities starts a configured desktop. schema describes tool arguments offline. An MCP connected indicator only confirms the adapter is running: call capabilities to verify the file service is available.

openfiles doctor
openfiles capabilities
openfiles schema openfiles_convert

If the desktop is not found, use setup codex --app /absolute/path/to/OpenFiles to specify its executable, substituting workbuddy for that client. After moving Node.js or the app, reinstall the CLI and run setup again. Check readRoots / outputRoots for directory errors. Use tasks before resubmitting a write with an uncertain result.

Enable the gateway manually (optional)

Use a desktop build that includes resources/agent/openfiles.cjs (inside OpenFiles.app/Contents/Resources on macOS), with Node.js 22 or later for the client. Start the OpenFiles executable with --agent-read-root=/absolute/input --agent-output-root=/absolute/output. Both directories must already exist; repeat flags for multiple grants. The gateway is disabled by default. Quit and restart the desktop to change grants. A source checkout provides these client commands:

npm run build-electron
npm run agent -- capabilities
npm run agent -- mcp-config
npm run agent -- skill

Discover and run operations

Read capabilities first: conversionFormats lists exact conversion pairs and metadata.formats lists editable fields. openfiles_inspect returns per-file conversion targets. Rendering accepts HTML, Markdown or SVG and produces PNG or PDF, with scripts and external resources disabled. CDR conversion produces a ZIP containing every page as SVG. Run saved .ofw files with openfiles_workflow; sourcePaths replaces file-input nodes, while saved batch folders and masks must also be authorized. PDF/OFD metadata uses metadata.edit or metadata.remove nodes. AI nodes require installed runtimes and may download model weights. Save the following arguments as request.json, replacing the paths:

JPEG and radiometric JPEG share extensions: when inspection returns contentDetectionRequired, the targets are candidates and the renderer validates file content during execution.

{"sourcePaths":["/input/design.cdr"],"outputDir":"/output","format":"zip"}

node dist/agent/openfiles.cjs call openfiles_convert --input request.json --wait

Track and recover tasks

Writes preserve originals and create a new openfiles-* directory below outputDir. Poll until completed, failed or canceled, then check result.paths and per-file errors. --wait defaults to 300 seconds; --timeout changes it. A timeout leaves the task running. Use tasks to recover its ID before resubmitting. Task lists accept --json or --input with state, contextId, pageSize and pageToken. Results omit artifacts; fetch the task for outputs. The gateway keeps up to 100 tasks and runs up to eight concurrently; restarting clears task history. Cancellation retains completed output.

node dist/agent/openfiles.cjs tasks
node dist/agent/openfiles.cjs task TASK_ID --wait
node dist/agent/openfiles.cjs cancel TASK_ID

Connect MCP and install the skill

mcp-config prints client configuration without changing settings. Register its command and arguments in the external client. mcp uses newline-delimited JSON-RPC over stdio; skill prints the bundled OpenFiles instructions. The default descriptor is ~/.openfiles/agent/connection.json. A custom descriptor pairs desktop --agent-connection=PATH with client --connection PATH. Keep its bearer token private. In source examples below, replace dist/agent/openfiles.cjs with the packaged client path when needed. Outbound MCP servers configured in Chat are separate from this external gateway.

Call A2A

The descriptor gives the loopback base URL. Fetch /.well-known/agent-card.json; its securityRequirements declares bearer authentication. POST the JSON below to /a2a with Content-Type: application/json, A2A-Version: 1.0 and Authorization: Bearer <token>. Reuse the same message ID and message on a transport retry. Poll GetTask with { "id": "TASK_ID" }, or use CancelTask. ListTasks supports contextId, status, statusTimestampAfter, pagination and includeArtifacts. Streaming, push notifications and natural-language planning are unavailable. Paths refer to this computer; screenshot editing and plugin installation remain desktop actions.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "unique-request-id",
      "role": "ROLE_USER",
      "parts": [{"data": {"name": "openfiles_capabilities", "arguments": {}}}]
    },
    "configuration": {"returnImmediately": true}
  }
}