# Use a coding agent

Claude Code, Codex, OpenCode and other agents can make and edit Textmock conversations directly. Browser agents use the `window.textmock` API on [textmock.com](https://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

For a fictional, text-only conversation, the [Textmock link helper](https://textmock.com/integrations/textmock-link.mjs) runs locally with Node.js 24 or later. Save the script as `textmock-link.mjs`, then run:

```sh
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](https://textmock.com/integrations/textmock.json) contains their source and license. Textmock's application terms still apply.

## The `textmock` command (Mac)

[Textmock for Mac](https://textmock.com/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`.

```sh
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.

### Importing from Messages

```sh
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.

## In a browser: `window.textmock`

Open the editor at [textmock.com](https://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:

```js
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

The [conversation UI fixture pack](https://textmock.com/conversation-ui-fixtures) 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

`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](/docs/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

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.
