Skip to content

Use a coding agent

View Markdown
For agents

Give your agent this page’s Markdown link, or choose a collection.

Claude Code, Codex, OpenCode and other agents can make and edit Textmock conversations directly. Browser agents use the window.textmock API on textmock.com. Textmock for Mac 1.0.14 and later also include a textmock command. Both expose the same methods and return the same JSON, and both follow the same Textmock Pro rules as a person using the app.

For a fictional, text-only conversation, the Textmock link helper runs locally with Node.js 24 or later. Save the script as textmock-link.mjs, then run:

Terminal window
node textmock-link.mjs - <<'JSON'
{"name":"Mira","messages":[{"from":"them","text":"Did you bring the telescope?"},{"from":"me","text":"Yes. You bring the clear sky."}]}
JSON

Open the printed link and choose Make a Copy to edit the conversation and save an image or video. Creating the link and viewing its preview change no saved conversation. Making a copy adds it if there is room; an untouched starter can be replaced, while an existing edited conversation is preserved when the free conversation limit is reached.

The helper accepts name, messages, optional dark and optional clock. Each message has from (me or them) and text. It supports one-to-one conversations, up to 120 messages and 4,000 characters per message, within a 180 KB JSON document limit. Replies are off in the new copy. It refuses unknown fields, photos and private notes. Use the APIs below for the app’s broader editing and rendering features.

The helper encodes the conversation in the fragment after #, which browsers omit from navigation requests. Anyone with the full link can read it, so avoid putting private links in logs or public output. The helper and the coding-agent skill are MIT-licensed; the integration bundle contains their source and license. Textmock’s application terms still apply.

Textmock for Mac includes the command from version 1.0.14. To put it on your PATH, open the app and choose Textmock › Install Command-Line Tool…. It links /usr/local/bin/textmock, or ~/.local/bin/textmock when /usr/local/bin isn’t writable, to the copy inside the app, so each update brings a new version of the command too. You can also run it in place at /Applications/Textmock.app/Contents/Helpers/textmock.

Terminal window
textmock help # every method, the conversation format and the limits
textmock status # Pro, how many conversations, which is open
textmock create '{"name": "Robin", "messages": [{"text": "you up?"}, {"text": "always"}]}'
textmock send <id> '{"text": "omw"}' # `from` alternates when left out
textmock react <id> -1 ❤️ # a tapback on the latest message
textmock render <id> --out robin.png # the image, as Save Image makes it
textmock render <id> '{"format": "mp4"}' --out robin.mp4

Each command runs one method in the app and prints its result as JSON: pretty in a terminal, one line when piped. If the app isn’t running, the command starts it in the background. Changes show up in the app’s window right away. Changes to the open conversation can be undone with ⌘Z; creating, deleting, and changing a conversation that isn’t open can’t.

  • Arguments: an argument that parses as JSON is used as JSON (a number, an object, or a "quoted string"). Anything else is passed as a plain string. - reads one JSON value from stdin. After --, nothing is read as a flag.
  • Sent once: the command sends a request again only while the app isn’t ready to run it. If the connection drops after the app has it, the command fails rather than risk running it twice; textmock list shows where things stand.
  • render: writes the file to --out and prints its path, size, and whether it carries the badge. A file given to --out is replaced if it exists. A folder, or a path ending in /, which is created if needed, gets the name the app suggests, numbered (Robin 2.png) rather than replacing a file. Without --out, the same goes for the current folder.
  • Errors: an error prints {"code", "message", "details"} to stderr and exits with a status for its code:
Exit Code Meaning
2 invalid The arguments or document don’t validate. details lists each problem, for example Message 2: replyTo must name an earlier message.
3 not_found No conversation or message has that id or index.
4 pro_required Only Textmock Pro allows more than one conversation.
5 full The library is at its limit.
6 unavailable or denied The app isn’t installed or Pro isn’t on sale (unavailable), or the person declined, or Textmock lacks Full Disk Access (denied).
1 anything else Any other failure.

The command connects to the app through a socket that only your user account can open, at ~/Library/Application Support/Textmock/agent.sock. Each request is one line of JSON, {"method": "send", "params": [...]}, and each answer is one line, {"ok": true, "result": ...} or {"ok": false, "error": {...}}. An agent that prefers to can speak this protocol to the socket directly.

Terminal window
textmock chats '{"search": "Robin"}' # conversations in Messages
textmock import <chat> # a new conversation that follows that chat
textmock sync <id> # pick up what's new since then

Messages is protected by Full Disk Access, which belongs to Textmock and not to the terminal. So the first time in each launch that an agent lists, imports or syncs, Textmock asks the person whether to allow it. If they decline, or Textmock doesn’t have Full Disk Access, the command fails with denied. Imports run one at a time, and importing a chat that’s already imported syncs it instead. Imported conversations stay on the Mac.

Open the editor at textmock.com, or the editor bundled into the iPhone or Mac app. Marketing pages and /docs explain the product; they do not define window.textmock. The editor defines the API once it loads and knows what Textmock Pro allows, waiting at most five seconds for the account check. It then fires textmock:ready on window.

Check for an API that is already ready before listening for the event. This example runs in the editor’s page context and stops with an error if that page does not become ready within ten seconds:

await new Promise((resolve, reject) => {
if (window.textmock) return resolve();
const ready = () => { clearTimeout(timeout); resolve(); };
const timeout = setTimeout(() => {
window.removeEventListener("textmock:ready", ready);
reject(new Error("Open the Textmock editor and wait for it to load."));
}, 10_000);
window.addEventListener("textmock:ready", ready, { once: true });
});
const { id } = await textmock.create({ name: "Robin", messages: [{ text: "you up?" }, { text: "always" }] });
await textmock.send(id, { from: "me", text: "omw" });
const png = await textmock.render(id, { format: "png" }); // { mime, base64, width, height, badge }

Calls that change conversations, and render, run one at a time in the order they’re made, so calls started together behave as if each waited for the one before. The methods throw an Error with code, message and details. textmock.call(method, params) never throws: it returns { ok, result } or { ok: false, error }, the same shape the socket uses. chats, import and sync require the Mac app’s Messages bridge and the person’s permission; on the website and in the iPhone app they fail with unavailable. Check textmock.status().platform before choosing a platform-specific workflow.

The conversation UI fixture pack provides four complete fictional conversation documents, exact preview links and suggested layout checks. Use one individual JSON document or a pack entry’s doc field with the broader editing API; the outer pack is an index, and the text-only link helper above accepts neither the pack nor these full documents. No private notes or imported messages are included.

textmock help (or textmock.help()) is the full reference. It is generated from the code, so it always matches the version you have.

Method What it does
status() The platform, whether Pro is active, the conversation count, whether there’s room for another, and which conversation is open.
list(), get(id?) Summaries, or one conversation’s document with private memory notes omitted. Without an id, get returns the open conversation.
create(doc?, {open}), set(id, doc), update(id, fields) Make a conversation, replace one, or change its top-level fields. A partial document is filled in.
send(id, messages), insert(id, at, messages) Add messages at the end or at a position.
edit(id, ref, fields), remove(id, ref) Change or remove one message. ref is its id or its index; -1 is the latest.
react(id, ref, emoji | null, from?) Add a tapback, or remove one with null.
open(id), delete(id) Show a conversation, or delete it.
render(id?, {format, scale, dark, video}) The PNG or MP4 that Save Image or Make Video would produce. dark overrides the conversation’s appearance. The suggested file name is the conversation’s name.
upgrade(reason?) Show the Textmock Pro offer to the person, for more conversations ("conversations", the default) or for saving without the badge ("badge"). Fails with unavailable when Pro isn’t on sale.
chats(), import(chat), sync(id) Bring in conversations from Messages (Mac only).

Messages accept names: a from of "Robin" resolves to the contact or group member with that name. Photos accept data: URLs. A document that doesn’t validate is refused whole, and the error lists every problem. The conversation format describes the document.

Notes the owner creates under What They Remember stay in the local editor. They are omitted from agent reads, share links and excerpts. create, set and update reject a supplied memories field. Ordinary edits, including replacing a conversation with set, preserve the owner’s current notes.

Agents follow the same rules as people:

  • Without Pro: there is one conversation. Images and videos carry the “textmock.com” badge.
    • create and import fail with pro_required. The error’s details include the price.
    • An untouched starter (the conversation Textmock made, never edited) doesn’t count: create and import replace it.
    • render still works and reports badge: true with a note.
  • Upgrading: upgrade() shows the offer in the app. Only the person can subscribe, from that sheet. An agent can’t subscribe for them.
  • Signing in: in the Mac app, the command uses the account the person signed in with. There’s nothing for the agent to sign in to.

Documentation drafted with AI and checked against the product source.