Use a coding agent
For agents
Give your agent this page’s Markdown link, or choose a collection.
- Documentation indexFind a guide and its Markdown link.
- Full documentationRead all curated guides in one text file.
- Machine manifestFind page metadata, Markdown URLs and checksums.
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.
Make an editable text link
Section titled “Make an editable text link”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:
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."}]}JSONOpen 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.
The textmock command (Mac)
Section titled “The textmock command (Mac)”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.
textmock help # every method, the conversation format and the limitstextmock status # Pro, how many conversations, which is opentextmock create '{"name": "Robin", "messages": [{"text": "you up?"}, {"text": "always"}]}'textmock send <id> '{"text": "omw"}' # `from` alternates when left outtextmock react <id> -1 ❤️ # a tapback on the latest messagetextmock render <id> --out robin.png # the image, as Save Image makes ittextmock render <id> '{"format": "mp4"}' --out robin.mp4Each 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 listshows where things stand. - render: writes the file to
--outand prints its path, size, and whether it carries the badge. A file given to--outis 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.
Importing from Messages
Section titled “Importing from Messages”textmock chats '{"search": "Robin"}' # conversations in Messagestextmock import <chat> # a new conversation that follows that chattextmock sync <id> # pick up what's new since thenMessages 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.
In a browser: window.textmock
Section titled “In a browser: window.textmock”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.
Reusable inputs
Section titled “Reusable inputs”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.
Methods
Section titled “Methods”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.
Textmock Pro
Section titled “Textmock Pro”Agents follow the same rules as people:
- Without Pro: there is one conversation. Images and videos carry the “textmock.com” badge.
createandimportfail withpro_required. The error’s details include the price.- An untouched starter (the conversation Textmock made, never edited) doesn’t count:
createandimportreplace it. renderstill works and reportsbadge: truewith 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.