DocsPlugins

Command scripts

A command is a function your plugin runs in the background. Both the UI and AI can call it. It runs in a separate Node process in the desktop app.

Write a command

Declare it under commands in the manifest, with handler pointing to the script:

JSON
{
  "id": "transform",
  "title": "Transform JSON",
  "description": "Validate JSON, then format, minify or sort it by key.",
  "handler": "scripts/transform.mjs",
  "params": {
    "type": "object",
    "properties": {
      "text":   { "type": "string", "description": "JSON text to process" },
      "action": { "type": "string", "enum": ["format", "minify", "sort"] }
    },
    "required": ["text"]
  }
}

The script default-exports a function:

JavaScript
// scripts/transform.mjs
/** @param {{ text: string, action?: string }} input */
export default async function (input, ctx) {
  if (!input?.text) throw new Error('text is required')
  const data = JSON.parse(input.text)
  if (input.action === 'minify') return { result: JSON.stringify(data) }
  return { result: JSON.stringify(data, null, 2) }
}
Description
input For AI calls, the arguments the model generated from params; for UI calls, the input passed to commands.run.
ctx plugin (key / name / version), command, dir (plugin folder, use it to read packaged files), haozi.request(method, path, body) (calls DeepDoer APIs as the logged-in user; payment and credential APIs are blocked).
Return value Plain data (structured-cloneable). Keep what you return to AI short.
Throwing The call fails and the error message is returned as-is to the UI or AI.

Runtime rules

  • You can use all of Node, including node:fs, fetch and child_process. Ship third-party dependencies with the package, ideally bundled into one file.
  • If you use the network, files or child processes, declare it truthfully in permissions; see permissions.
  • The default timeout is 30 seconds. UI calls to commands.run can pass timeoutMs (1 second to 5 minutes).
  • A timeout, cancellation or manual stop ends that plugin's command process, and other running commands of the same plugin fail too. Handlers must be safe to retry.
  • Each plugin has one long-lived process, reclaimed after 60 seconds idle. Module top-level setup runs once, but do not keep state only in memory.
  • console.* output goes to the desktop app log (plugin:<key>).

Becoming an AI tool

  • Every command with a handler is registered as the tool plugin__<key>__<id> (invalid characters become _, total length within 64).
  • The model decides when to call it from description, so say clearly what it does and when to use it.
  • Write params and a description for each field. Without params, the model can only pass a single string { input }.
  • Users can set each tool to allow, ask or deny.