Drive Morphy from your tools

Any program on your computer can drive your chats in Morphy: start a chat in a folder, send it a message, wait for its answer and read it, stop it. A build script can hand a review to Claude, an editor extension can send a file to a chat, your own app can run a team of agents. It's the same bridge Morphy's own chat uses to run your other chats.

Morphy has to be running. The bridge only works on the computer Morphy runs on: there's no network port, and cards can't use it.

The command toolCopy Anchor Link

Morphy keeps a small command tool in its data folder, and writes it again every time it starts:

• Windows: %APPDATA%\Morphy\assistant\scripts\morph-ctl.mjs
• Mac: ~/Library/Application Support/Morphy/assistant/scripts/morph-ctl.mjs
• Linux: ~/.config/Morphy/assistant/scripts/morph-ctl.mjs

Run it with Node.js:

node "$HOME/Library/Application Support/Morphy/assistant/scripts/morph-ctl.mjs" status

On Windows: node "%APPDATA%\Morphy\assistant\scripts\morph-ctl.mjs" status. Don't change the file: Morphy replaces it at its next start.

--provider takes claude, codex, grok, copilot, opencode, antigravity, openrouter-agent, ollama, or custom, custom-2… for your own providers. The AI has to be connected in Morphy first.

What to knowCopy Anchor Link

• Morphy's own chat is main. Other chats have ids like chat-k3x9p2ab: spawn prints the new one, and status lists them all.
• A message shows in the chat as if you'd typed it, and you can take over at any time.
• A chat that's working answers busy. Wait until status shows it done, then send again. A chat that's asleep wakes up for the message. A chat open as a terminal takes no messages from here.
• New chats start like any new chat: the model, effort and permission mode you set for new chats in Settings → General, unless you name a model.
• Tags keep a batch together. Spawn several chats with --tags review and read all their answers with results --tag review.
• On Freemium, only 3 agents work at a time. A message for a fourth waits its turn by itself.

An exampleCopy Anchor Link

Ask Claude and Codex to review the same change, then read what they said:

CTL="$HOME/Library/Application Support/Morphy/assistant/scripts/morph-ctl.mjs"
ASK="Review the last commit for bugs. Don't change anything."

node "$CTL" spawn --provider claude --cwd ~/code/shop --title "Claude review" --tags review --prompt "$ASK"
node "$CTL" spawn --provider codex --cwd ~/code/shop --title "Codex review" --tags review --prompt "$ASK"

# a few minutes later
node "$CTL" results --tag review --full

To compare models of one AI instead, models lists their ids and spawn --models a,b,c starts one chat per model.

From any languageCopy Anchor Link

The command tool is a thin layer over files, so a program in any language can use the bridge directly. Everything is in the .morph folder of Morphy's data folder.

Send commands by writing a JSON file into .morph/agent-ipc/:

{ "ops": [ { "op": "send", "id": "main", "text": "Summarise today's commits" } ] }

1. Write it as <name>.tmp, then rename it to <name>.json, so Morphy never reads half a file. Pick a name nothing else uses.
2. Morphy runs the commands in order, deletes the file and writes <name>.result.json: { "ok": true, "results": [ … ] }, one result per command, each with its own ok (and an error when it failed).
3. Read the result and delete it. If none comes, Morphy isn't running (the command tool gives up after 20 seconds).

The commands:

create places the chat at x, y in canvas pixels (the command tool puts new chats to the right of everything). Give w and h too, for example 420 × 520.

Watch chats without asking: .morph/chats-live.json is rewritten whenever a chat changes. For each chat it has running, asleep, waiting (for a free agent on Freemium), title, provider, model, cwd, tags, latestPrompt, lastDone (ok and when) and lastResult (the first 600 characters of its last answer; result gives the whole of it). A chat has finished a turn when running goes false and lastDone changes.

SafetyCopy Anchor Link

Any program running under your user account can use the bridge, the agents in your chats included. That's the same set of programs that can already read and change your files, so it adds no new way in, but only run tools you trust. A chat started this way does what its permission mode allows, so keep chats for folders you can't easily restore in Ask first. See Security.