Skip to main content

AI Assistant

The AI Assistant lets you describe work in plain language and have TikMatrix queue it for you. It reads your devices, accounts and task history, shows you exactly what it would create, and waits for your approval before anything is written.

Requires Pro

The assistant is available on the Pro plan or higher, the same requirement as the local automation API.

What it is (and is not)​

The assistant does not touch your phones directly. It works the way you do: it looks at what you have, then queues tasks, which the normal task runner picks up and executes. Anything it creates appears in the task list like any other task, tagged with the source assistant.

It also cannot write anything on its own. Every action that changes state stops the conversation and asks you first — see Nothing runs without your approval.

Setting it up​

You supply your own model. TikMatrix does not ship one and does not proxy your requests — the app talks to the endpoint you configure, directly from your machine.

  1. Click Assistant in the left navigation rail.
  2. Click Model settings.
  3. Fill in:
FieldWhat to put in it
EndpointThe full chat-completions URL, e.g. https://api.openai.com/v1/chat/completions
ModelThe model id, e.g. gpt-4o or claude-sonnet-4-5
API keyYour key for that provider
API formatLeave on Detect from endpoint unless it guesses wrong
Task limit per confirmationThe most tasks one approval may create (default 200)
  1. Click Save.

The status line at the top of the panel shows the model in use once the settings are accepted, so you can tell at a glance which endpoint a conversation is going to.

Which endpoints work​

Two wire formats are supported:

  • OpenAI-compatible — any endpoint that speaks POST /v1/chat/completions. This covers OpenAI itself and most self-hosted servers: vLLM, LocalAI, Ollama's OpenAI shim, DeepSeek, OpenRouter, and similar.
  • Anthropic — endpoints that speak POST /v1/messages.

API format is normally left on Detect from endpoint: a URL containing api.anthropic.com or /v1/messages is treated as Anthropic, everything else as OpenAI-compatible. Set it explicitly only when you run a proxy whose URL does not reveal the dialect.

Pick a model that can use tools

The assistant works entirely through tool calls. A model without reliable tool support will chat with you but never manage to plan anything.

Choosing a model​

If you wantUse
The most reliable planning, least babysittingA current frontier model from OpenAI or Anthropic
Lower cost on routine "queue this across my rack" workA mid-tier model from the same providers
Nothing leaving your machineA local server (Ollama, vLLM, LocalAI) running a model with solid tool-calling

Small local models are the common source of "it chats but never plans". Before concluding the assistant is broken, try the same request against a hosted model once — if that works, the model was the problem, not the configuration.

Where the settings are stored​

Your endpoint and key are written to assistant_settings.json in the app's data directory, and read by the backend when it makes a request. They are not sent anywhere except to the endpoint you configured.

One setting lives only in that file: max_tokens, the reply budget sent to the model. It defaults to 8192 and is clamped to the range 1024–64000. Raise it by hand if long answers are being cut off.

Asking for work​

Type what you want in plain language. Some examples:

  • Warm up every account for 20 minutes
  • Why did my last tasks fail?
  • Post to all devices at 09:00 tomorrow
  • Follow these five accounts from the phones in the Marketing group

A request normally goes through three steps:

  1. It looks things up. Which devices are online, which accounts are logged in, what parameters the script takes.
  2. It plans. It works out exactly how many tasks the request produces, and shows you the totals — how many tasks, across how many devices and accounts.
  3. You confirm. Only then are the tasks written.

If a request is ambiguous in a way that changes how many tasks get created, the assistant asks rather than guessing.

What a request looks like end to end​

You: warm up every logged-in account for 20 minutes, starting at 9am tomorrow

Assistant: (calls get_script_schema, list_devices, list_accounts, then plan_tasks) 34 warmup tasks across 12 devices and 34 accounts, 20 minutes each, starting 2026-08-27 09:00. Two accounts are not logged in and were left out.

A confirmation card appears listing every row it is about to create — device, account, and target where the script takes one — plus the exact script_config that will be written. You press Confirm, and 34 tasks appear in the task list.

Saying when​

Tasks can be queued for later: mention a time and the assistant puts it in the plan as the task start time, which the card shows before you approve. This is also the right answer when a request is large — spreading a rack's worth of follows across a day looks much less automated than firing them all at once, and the assistant will suggest it on requests that look risky.

On builds that drive both apps​

A TikMatrix build configured for both TikTok and Instagram cannot guess which one you mean, and it will not try — a request without a platform comes back asking for one. Say "post to TikTok on the Marketing group" rather than "post on the Marketing group" and it goes straight to planning. Single-platform builds never ask.

Nothing runs without your approval​

This is enforced in code, not by asking the model nicely.

When the assistant reaches for anything that changes state, the conversation stops and a confirmation card appears showing what is about to happen. The call runs only after you press the confirm button.

Four actions are gated this way:

ActionWhat it does
create_tasksQueue the planned tasks
stop_taskStop a running task
retry_taskRe-queue a failed task
create_custom_scriptWrite a new script file and register it

Task creation carries a second lock on top of that: the confirm button can only execute the plan you were shown. The assistant cannot revise the parameters between the preview and your approval — a plan is single-use and expires after 15 minutes, so a preview you walked away from cannot be confirmed later against a device list that has since changed.

The card is not a summary written by the model, either. It renders the plan's actual rows and the actual script_config, so what you approve is what gets written.

Declining is a normal answer, not an error: the model is told you said no, and can offer something else instead of retrying the same call.

The task ceiling​

One confirmation may create at most 200 tasks by default. This is a brake against a misread request — "warm up my accounts" turning into a thousand tasks you discover in the morning. Larger runs are still possible: the assistant splits them into batches you confirm one at a time.

You can change the limit in Model settings → Task limit per confirmation. Values above 2000 are clamped.

What the assistant can see​

These it can use freely, without asking:

ToolWhat it reads
list_devicesConnected devices, whether each is online or busy, group membership
list_accountsAccounts, the device each lives on, and whether it is logged in
list_groupsDevice groups and their sizes
get_script_schemaEvery script this build can run and the exact parameters it takes
list_tasksThe task list, filterable by status, device or script
get_task_logThe log of one task — the usual place a failure explains itself
get_activity_logRecent account activity
device_screenshotWhat is on a device's screen right now
list_custom_scriptsYour registered custom scripts
get_custom_script_guideHow to write a custom script
plan_tasksWorks out what a request would create, without creating it
Screenshots go to your model provider

device_screenshot sends a picture of the phone's screen to the endpoint you configured. If a screen might show something you would rather not send to a third-party provider, avoid asking for screenshots, or point the assistant at a model you host yourself.

What leaves your machine​

Everything the assistant reads is sent to your model endpoint as part of the conversation — that is how the model sees it. In practice that means device serials and group names, account usernames and their login state, task rows and task logs, and any screenshot you ask for. API keys, proxy credentials and account passwords are not among the things it can read, so they are never in the payload.

If that list is more than you want to hand a third-party provider, point the endpoint at a model you run yourself; nothing else about the feature changes.

Writing custom scripts​

If no built-in script covers what you need, the assistant can write one. Ask for the job in plain language; it reads the scripting guide, drafts a program, and shows it to you.

The confirmation card for this makes a point of saying so: the script is written to disk and registered so it can be run like any built-in one. Read it before approving. Scripts land in an assistant_scripts folder in the app's data directory, so you can audit, edit or delete everything it has written in one place.

Some limits the app enforces on whatever the model proposes:

  • Only python, python3, node, bun and deno may be registered as the interpreter — nothing that would run a shell with a payload after it.
  • The file name must be a plain name: no path separators, no .., no leading dot, at most 64 characters.
  • The source is capped at 200 KB, and the platform must be generic, tiktok or instagram.

A registered script is an ordinary custom script from then on: you can open it under Devices → Custom Scripts, edit the command, change the timeout, or disable it. See Custom Scripts for what a script can do once it is registered.

Limits worth knowing​

  • One request, twelve steps. If the assistant has not finished after twelve tool calls it stops and reports what is unresolved, rather than spending your tokens in a loop.
  • The conversation is not an archive. It is held in memory — the eight most recent conversations, and the last 120 turns of each — and is lost when the app restarts. Anything worth keeping ends up as a task, and tasks are in the database.
  • Navigating away is safe. The thread and any outstanding confirmation are restored when you come back.
  • Stop ends the loop at its next checkpoint. It cannot interrupt a model call already in flight, so the current step finishes first.
  • You pay for the tokens. Every request carries the script catalog and the conversation so far, so a long thread costs more per message than a fresh one. Starting a new conversation for an unrelated job is cheaper than continuing an old one.

Troubleshooting​

API access requires Pro or higher plan Your licence is Starter or inactive. Check Settings → License.

The app is still starting up. Try again in a moment. The panel opened before the background services finished starting. Wait a few seconds and send again.

No model endpoint configured / No API key configured / No model configured Open Model settings and fill in all three of endpoint, model and API key.

Could not reach the model endpoint The app could not open a connection. Check the URL, and check that a local endpoint is actually listening on that port.

The model replies but never plans anything It is probably not calling tools. Try a model with solid tool-use support, and check that API format matches your endpoint's dialect.

Every reply is cut short Some OpenAI-compatible servers cap output low by default. Raise the limit on the server, or raise max_tokens in assistant_settings.json.

It keeps asking which platform This build drives both TikTok and Instagram. Name the one you mean in the request.

A confirmation card will not confirm Plans expire after 15 minutes. Ask for the same thing again to get a fresh one.

Tasks were created but nothing runs The Auto WakeUp Agent is probably switched off — the assistant warns about this before you confirm. Re-enable it in Settings.

Next steps​