1   What is TealKit?

TealKit is a mobile AI agent powered by the Model Context Protocol (MCP). Connect it to any compatible LLM (OpenAI, Anthropic Claude, Google Gemini, Mistral, Ollama …) and your own data sources — documents, emails, websites, files — then let the AI work through multi-step agents automatically.

Everything runs on your device. No data is sent to TealKit servers.

Key concepts

• Playground — interactive chat with live tool use
• Agents — saved, reusable automation workflows
• MCP Tools — capabilities the AI can call (web search, email, documents …)
• Data Sources — your personal data connected to the agent

2   Platform Notes

3   First-Time Setup

Provider details & API key registration

LLM Provider and Model Settings

When configuring an LLM, you will find several advanced settings. Not all parameters shown in certain models or external guides apply to TealKit, but here is a quick helper for the ones available:

• Temperature: Controls how creative or focused the AI is. Use lower values (e.g., 0.0 – 0.3) for precise, factual agents to avoid hallucinations. Use higher values (0.7 – 1.0) for more varied, natural language.
• Max Tokens: The maximum length of a single AI response. Increase this if the AI cuts off long data summaries. Reduce it to save costs on simple queries.
• Max Tool Output Size (chars): Limits how many characters a single tool result can return to the LLM. Set to 0 for unlimited. Reduce this to prevent very large tool outputs (e.g. a huge web page) from consuming the context window.
• Token Warning Threshold: When the session token count reaches this number, TealKit suggests cleaning up the chat history to prevent context overflow. Default: 1,500,000. Adjust based on your model's context window.
• Top-K: Limits the AI to choosing from the top K most likely next tokens. Lower values (e.g., 10–40) make output more focused; higher values allow more variety. Leave blank to use the provider’s default. Most effective with Ollama and local models.
• Top-P (nucleus sampling): The AI picks tokens whose cumulative probability reaches P. Values like 0.9 keep output diverse but coherent. Set to 1.0 to disable. Leave blank for provider default.
• Repeat Penalty: Penalises the model for repeating tokens it has already used. Values above 1.0 (e.g., 1.1) reduce repetition; 1.0 means no penalty. Useful for long-form outputs. Leave blank for provider default.
• Seed: A fixed integer that makes generation deterministic — the same prompt and seed will produce the same output. Useful for reproducible test runs. Leave blank for random / provider default.

LLM 2 — Secondary Model

TealKit lets you configure a second, independent AI model dedicated to code generation. This is useful for keeping a powerful (but more expensive) primary model for reasoning and agent execution, while using a faster or cheaper model for writing shell scripts and JavaScript tools.

Configure LLM 2 under Settings → LLM Settings → LLM 2 tab. The same providers and parameters are available as for the primary model.

• Shell Script Wizard — tap the model picker in the wizard to generate the script with LLM 2 instead of your primary model
• JavaScript Tool Wizard — same: pick LLM 2 in the wizard’s model picker
• Agents — select LLM 2 (from settings) as the agent’s LLM provider to run an entire agent with the secondary model

Use Case Examples

Here are some examples of what you can accomplish in the Playground or build as automated Agents:

• Semantic Document Search: “Search semantically for ‘setup new sensors in wsca’ in any document files.”
• Emails: “Search my emails containing the text ‘TaskAI’ from the last 24 hours, and summarize them.”
• Calendar: “Fetch each next calendar events for the next 1 week and save them into the PDF document.”
• Shell Script: “Generate a shell script that inputs a directory and lists the 20 biggest files.”
• Weather + Chart: “Get the weather forecast for my location for the next 24 hours, then create a statistics summary chart from the temperature data.”
• Agent Chaining / Automation: Create an SSH agent with Stop after tool call enabled — it runs script disk_usage and the raw output becomes ${task_result}. Add a conditional trigger: “if ${task_result} > 65 %” → route to following agent diskusage_alert.

4   Playground

The Playground is an interactive chat where you experiment with the AI and its tools in real time.

Setting up a session

1. Select tools (web search, email, documents …). Enable the Generate system prompt checkbox to let the AI automatically create a tailored prompt based on your tool selection.
2. Review or edit the system prompt (or tap ✨ to regenerate it manually).
3. If you selected Website Search or Documents, tap Start Indexing to build the local index. A red Stop button appears during indexing — tap to cancel anytime.
4. Optionally set an initial message sent automatically on start.
5. (Optional) Chat mode — enable the orange Chat mode checkbox to send your message directly to the LLM with no system prompt and no tools. All tool checkboxes are ignored. Ideal for SLMs doing translation, formatting, summarisation, or any pure text agent where tool overhead adds latency without benefit.
6. (Optional) Stop after tool call — enable the purple Stop after tool call checkbox to make the session execute one tool call, capture the raw output, and stop immediately — no further LLM processing. The raw tool output becomes ${task_result} for a chained agent. Useful when you want unmodified tool output (e.g. SSH command result, web scrape, document search) to flow directly into a downstream agent.
7. If you have configured a second LLM (Settings → LLM Settings → LLM 2), a LLM 1 / LLM 2 selector appears above the Start button. Use it to switch models without leaving the Playground — ideal for comparing a powerful cloud model against a local SLM on the same prompt.
8. Tap Start Playground (disabled while indexing is active).

During chat

• Tool calls appear as collapsible cards — tap to expand inputs/outputs.
• Use the attachment button to add images or files to your message.
• Tap Reset Chat to start fresh with the same setup.
• Save as Agent PRO — after a successful session, use the save button to convert the current Playground configuration (tools, system prompt, LLM) into a reusable automated Agent.

5   Agents

Agents are saved automation workflows. Each agent packages an LLM, tools, a system prompt, and an initial message — ready to run with one tap. Free tier: up to 3 agents. PRO removes the limit.

Creating a agent

1. Go to Agents → + New Agent.
2. Give it a name and description.
3. Configure the LLM (can differ from your global default — or select LLM 2 (from settings) to run the agent with your secondary model).
4. Select tools and configure each one (website URLs, document folder, etc.).
5. Enable Generate system prompt in the Basis / Built-in Tools panel to let the AI auto-generate a prompt from your tool selection, then review or edit it.
6. Write the system prompt and initial user message.
7. Tap Save.

Execution modes

• ▶ Run — executes the agent immediately with a progress dialog.
• Interactive / Try-Out — opens the agent's configuration as a live Playground chat. Perfect for testing or refining a agent interactively before scheduling it.

Cron scheduling PRO

Automate any agent to run on a schedule:

• Hourly — every hour
• Daily — once per day at a chosen time
• Weekly — on a chosen day and time
• Custom cron expression — full cron syntax (e.g. 0 8 * * 1-5 for weekday mornings)

Run statistics

Tap a completed run entry to view detailed stats:

Output format

Control the output format through your system prompt or initial message:

• Ask for Markdown (.md), HTML, JSON, or plain text
• Ask the excel server to produce a .xlsx spreadsheet from any structured data
• Ask the chart or mermaid servers to produce .png diagram or chart images
• TealKit saves the raw result plus a rendered HTML preview automatically

Output channels PRO

Agent results can be delivered automatically to one or more channels when a run finishes. Each channel has its own send condition and can optionally attach the output files. Global credentials are configured once in Settings → Data Sources; per-agent overrides are set on the agent's Output tab.

Any generated file can be attached — not just the Markdown log. This includes .xlsx spreadsheets (from the excel server), .png charts and diagrams (from chart / mermaid), .html previews, and .md result files. Enable the Include output files toggle on the agent's Output tab to have all generated files forwarded to every active delivery channel.

✉ Email output PRO

Have the agent result emailed automatically when done. Configure in the agent's Output section:

• Recipient — one or more email addresses
• Subject — static text or dynamic (can reference agent name / date)
• Condition — always, only on success, or only if output is non-empty
• Include output files — attach all generated files as email attachments: .md result, .html preview, .xlsx spreadsheets, .png charts and diagrams, and any other files the AI created during the run

💬 Slack output PRO

Post the agent result to a Slack channel automatically. Creating a Slack App is free — create one at api.slack.com. Two auth modes are supported:

• Incoming Webhook — simplest option, no bot needed. To get the URL:
  1. Go to api.slack.com/apps and create a free app (From scratch).
  2. Under Add features & functionality, click Incoming Webhooks and activate them.
  3. Click Add New Webhook to Workspace, pick a channel, and allow access.
  4. Copy the Webhook URL shown — it starts with https://hooks.slack.com/services/…
  5. Paste it into Data Sources → Slack → Webhook URL in TealKit.
  Text attachments are embedded as code blocks in the message.
• Bot Token (xoxb-…) — enables real file uploads. Steps:
  1. In your Slack App, open the left sidebar → OAuth & Permissions.
  2. Scroll to the Scopes section → Bot Token Scopes.
  3. Click Add an OAuth Scope and add: chat:write, files:write, files:read.
  4. Scroll back up and click Install to Workspace (or Reinstall).
  5. Copy the Bot User OAuth Token that starts with xoxb-…
  6. Also invite the bot to your target channel: in Slack type /invite @YourBotName.

Per-agent options on the Output tab:

• Send condition — Always / Only on success / Only on error
• Override channel — leave blank to use the global default channel
• Include output files — attach all generated output files: .md result log, .html preview, .xlsx spreadsheets, .png charts & diagrams, and any other files produced during the run (or the ZIP if ZIP output is enabled). Bot Token required for native file uploads; Webhook mode embeds text content inline.

📲 WhatsApp output PRO

Send the agent result to a WhatsApp number via the Meta Business Cloud API. Registration is free and includes 1,000 conversations / month at no cost. Requires a Meta Business account with a verified phone number.

1. Create or open a Meta app at developers.facebook.com → WhatsApp Cloud API Get Started.
2. Add the WhatsApp product and note your Phone Number ID.
3. Generate a System User access token with whatsapp_business_messaging permission.
4. Enter both values in Settings → Data Sources → WhatsApp.

Per-agent options on the Output tab:

• Send condition — Always / Only on success / Only on error
• Override recipient — E.164 phone number (e.g. +49170…); leave blank to use the global default
• Include output files — all generated files (.xlsx, .png, .md, .html, …) are uploaded via the WhatsApp Media API and sent as separate document messages after the text summary. Meta Cloud API only — CallMeBot (text-only) lists file names in the message instead.

📂 SFTP output PRO

Upload agent results and generated files to a remote server automatically via SFTP when a run finishes. Configure SSH/SFTP credentials once in Settings → Data Sources → SSH.

Per-agent options on the Output tab:

• Remote directory — defaults to the normalised agent name slug; override per agent if needed
• Send condition — Always / Only on success / Only on error
• Include output files — uploads all generated files (.md, .html, .xlsx, .png, …) to the remote directory

ZIP output PRO

Bundle the full output folder (result + logs + attachments) into a single ZIP file. Combine with Email output to receive the archive by mail after every run.

Agent chaining PRO

Chain agents so the output of one feeds into the next. Wherever ${task_result} appears in a chained agent’s system prompt or initial message, it is replaced with the triggering agent’s output.

Following agent mode

Enable Following agent mode on an agent (Basic tab) to mark it as a chained follow-up. Following agents only run when triggered by another agent — they are hidden from standalone agent lists and scheduling.

With condition & unconditional

When setting up a trigger on an agent, choose between:

• With condition — the LLM evaluates a condition expression (e.g. “disk usage exceeds 80 %”). A match routes to the on-match following agent; a non-match can optionally route to a separate on-no-match agent.
• Unconditional (no condition) — the result is always forwarded to a single following agent — no LLM evaluation, lower latency.

Stop after tool call

Enable Stop after tool call on an agent (Basic tab) or in Playground setup. When set, the agent executes one tool call, captures the raw output, and stops immediately — the raw tool output becomes ${task_result} for the next chained agent with no further LLM processing. Ideal for data-extraction agents where you need the exact, unmodified tool response (e.g. SSH output, search result, document snippet) to flow into a downstream agent.

✏️ Multi-step System Prompt Editor

The system prompt field in the agent editor supports multi-step prompts using the ++#++ separator. TealKit visualises each section as a separate collapsible tile, making it easy to read and edit individual steps without scrolling through a single large text block.

• Tap + Add section to append a new step tile.
• Tap a tile header to expand and edit its content inline.
• Tap the 🗑 delete icon on a tile to remove that step.

For the full syntax, placeholder reference, and worked examples, see Section 5.1 — Prompt Splitting.

👁️ Preview Full Prompt

The agent editor shows a Preview button (👁 eye icon) next to the System Prompt header. Tapping it assembles the complete effective prompt that will be sent to the LLM at runtime — including the date/time header, toolbox guidance, tool capability hints, and any auto-injected tool skills — and displays it in a scrollable, editable dialog.

• Editable — adjust the final text directly in the preview.
• Apply to prompt — writes the edited text back to the agent’s system prompt field, replacing the current content.
• Close — dismiss without changes.

5.1   Prompt Splitting

Prompt Splitting lets you break a single agent or Playground prompt into sequential steps using the ++#++ separator (on its own line). Each step runs as a complete, independent LLM call — the model handles one focused task at a time instead of trying to do everything in one long prompt. Use the ${tool_result} placeholder in a later step to inject the raw tool output (or LLM response text) from the previous step.

Syntax

First step prompt
++#++
Second step prompt that uses ${tool_result}
++#++
Third step ...

• Steps are separated by ++#++ on its own line (the separator must appear as a standalone line).
• In step N, ${tool_result} is replaced with the raw tool output of step N−1, or with step N−1’s final LLM response if no tool was called.
• If a step fails (e.g. tool error), the chain stops at that step.
• Tokens, tool calls, and run statistics accumulate across all steps and are reported as a single run.

Example — fetch, format, and summarise with a small model

Fetch the disk usage report by calling the check_disk_usage tool.
++#++
Here is the raw disk data:
${tool_result}
Format this as a Markdown table. Highlight any partition above 80 % in bold.

In this example the first step calls the tool; the second step receives the raw tool output and formats it. Each step is simple enough for a 7–14 B local model to handle reliably.

When to use Prompt Splitting vs Agent Chaining

5.2   Tool Skills

Tool Skills are concise usage hints stored per MCP server tool and automatically injected into the effective system prompt at runtime. They help the LLM understand when and how to call each tool correctly, without you having to write this guidance yourself in the system prompt.

Automatic injection by model size

TealKit adjusts how much skill text is injected based on the active model:

Auto-generating skills

Skills can be generated automatically for any MCP server with a single tap:

1. Open the Playground or an Agent editor and switch to the Tools tab.
2. Find the MCP server card for the server you want to enrich.
3. Tap the ✨ (sparkle) icon on the server card.
4. TealKit calls the LLM to analyse the server’s tool list and write concise skill descriptions — both full and compact (SLM) versions — for each tool.
5. The Skill Editor opens automatically with the generated skills for review.
6. Tap Save to store the skills.

Editing skills manually

You can also write or adjust skills by hand at any time:

1. On any MCP server card in the Tools tab, tap the 🧠 (brain / psychology) icon.
2. The Skill Editor opens showing all tools for that server. Each tool has two fields:
   • Full skill — for large models. Describe the tool’s purpose, key parameters, and usage tips in a few sentences.
   • Compact skill (SLM) — for small models. One or two short sentences maximum.
3. Edit, clear, or rewrite any skill entry. Tap Save to apply.

6   Data Sources

Configure data sources in Settings → Data Sources. Each source can be toggled on/off per agent independently.

📧 Email (Gmail / IMAP)

Connect Gmail via OAuth or configure any IMAP server. The AI can search, read, and optionally send emails.

🔍 Web Search

Choose DuckDuckGo (free, no key needed), Serper.dev, or SerpAPI. Enter your API key for premium providers.

📄 Documents

Point to one or more local folders. TealKit indexes all documents into a local DuckDB database using hybrid semantic + keyword search. See Document Search for details.

🌐 Website Search

Add seed URLs and let TealKit crawl and index them locally into a full-text search index. Index before starting the Playground or Agent — crawling can be stopped at any time.

• Free tier: up to 3 seed URLs
• Pro: up to 10 seed URLs PRO

Indexing can be scheduled automatically on a cron schedule (minimum 1-hour intervals: hourly, daily, weekly, or monthly). A Last indexed timestamp is shown and a manual Index Now button is always available. Scheduled re-indexing runs in the background without any user interaction. PRO

📍 Location

Optionally save GPS coordinates. They are injected into every agent so queries like "weather at my location" resolve automatically. Coordinates never leave your device.

☁ Google Drive

Connect via OAuth to search and read files from your Drive.

🖥 SSH

Connect to a remote SSH server. See the SSH section for full details.

🏠 Home Assistant

Control your smart home via Home Assistant. Configure the Base URL and a Long-Lived Access Token once in Settings → Data Sources → Home Assistant and the AI can query and control any entity. See the Home Assistant section for full details.

💬 Slack

Configure Slack credentials for automatic agent output delivery. Creating a Slack App is free — create one at api.slack.com. Two modes:

• Incoming Webhook URL — in your Slack App go to Incoming Webhooks → Add New Webhook to Workspace, pick a channel, then copy the URL that starts with https://hooks.slack.com/services/… Text results are posted as formatted messages; attachments are embedded as code blocks.
• Bot Token — paste an xoxb-… token and set a default channel. Enables native file uploads. In your Slack App go to OAuth & Permissions → Scopes → Bot Token Scopes and add chat:write, files:write, files:read; then reinstall the app and copy the xoxb-… token. Invite the bot to the channel with /invite @YourBotName.

📲 WhatsApp

Configure Meta Business Cloud API credentials for WhatsApp output delivery. Registration is free and includes 1,000 conversations / month at no cost — get started on Meta Developers.

• Phone Number ID — from your Meta app's WhatsApp product page
• System User Access Token — long-lived token with whatsapp_business_messaging permission
• Default Recipient — E.164 phone number used when a agent does not specify one (e.g. +49170123456)

7   MCP Servers

TealKit ships with a set of built-in MCP servers and supports external servers from the broader ecosystem.

Built-in servers

💡 Three ways to extend the AI with tools

TealKit gives you three distinct and complementary ways to add tools to the AI. Understanding the difference helps you pick the right approach for each agent:

☁️ Remote MCP Servers — cloud / hosted (all platforms)

Connect to any MCP-compatible server running in the cloud over HTTP Streaming or SSE — no local installation needed. Go to Settings → Remote MCP Servers and choose a catalog source:

Each configured server exposes its tools directly in the Playground and Agents tool selector. Remote servers work on all platforms including Android and iOS.

📥 MCP Server Registry — installable local servers PRO (desktop only)

On desktop (Windows, Linux, macOS) TealKit can download and run MCP servers locally. These are real Node.js and Python servers installed on your machine with one click — no terminal needed. Go to Settings → MCP Server Registry and browse four public catalogs:

Tap Install on any entry — TealKit runs npm install -g, uvx, or pip in the background. The installed server appears immediately in the tool selector. Uninstall removes the package and cleans up the entry.

🔧 Scripts & tools as mini MCP servers

Every script or tool you create in TealKit is exposed to the AI as a local MCP server tool — the AI calls it in exactly the same standardised way it calls any cloud server. This means you can build powerful agent automation without writing MCP server boilerplate:

The LLM sees a clean tool name and input schema — it never knows (or cares) whether the tool is a cloud endpoint, an npm package, or a 20-line PowerShell script you wrote yesterday. All three share the same MCP protocol.

🔧 Custom Tools PRO

TealKit lets you build your own tools without writing any native code. Two wizards are available — accessible from the Tools tab in Playground settings or when editing a Agent. Free tier: 1 Shell script, 1 JavaScript tool, and 1 Python tool. PRO gives unlimited tools of each type.

📜 Shell Script Wizard

Describe what you need in plain language and the AI writes a ready-to-use shell script. The script type is chosen automatically based on the target platform:

• Windows — generates a .ps1 PowerShell script
• Linux / macOS — generates a .sh Bash script

Saved scripts are auto-discovered by the SSH server and can be referenced by name in any agent.

Tips for a good shell script prompt:

• Name the target platform and environment: “PowerShell on Windows”, “Bash on Ubuntu”, “Bash on macOS”
• Describe inputs and outputs: “takes a folder path as argument, writes CSV to stdout”
• Mention error handling: “exit with code 1 on failure, print error to stderr”
• Example: “List files modified in the last 24 hours in a given directory and save the result to report.txt”

🧩 JavaScript Tool Wizard

Write a custom MCP tool as a small JavaScript snippet. The snippet runs in a secure on-device sandbox and can call REST APIs with fetch(). Saved tools appear immediately in the tool selector for Playground and Agents.

Tips for a good JavaScript tool prompt:

• Define input schema and output clearly: “input: { from, to, amount }, output: { rate, converted }”
• For REST APIs include the full URL pattern: “GET https://api.example.com/v1/data?key={param}”
• Mention error cases: “return an error message if the currency code is invalid”
• Example: “Fetch the current Bitcoin price in EUR from the Coinbase public API and return price and timestamp”

🧠 Tool List Export for Model Training

Export the complete tool list of any MCP server in a machine-readable format — ideal for fine-tuning LLMs on tool-use data or for documenting your available tools.

The export icon (🧠 model_training) appears in multiple places:

• Playground — tap the icon on any internal MCP server chip in the tools selector
• Agent editor — tap the icon next to the tool count chip on any server tile
• Available Tools viewer — tap the icon in the viewer header (opened from Settings → Remote MCP Servers)
• Discover Tools sheet — tap the icon in the sheet header when browsing a server's tool list

Choose from four export formats:

Tap Copy to copy the output to the clipboard, or Save to file to write it directly to disk (desktop platforms).

8   Document Search

TealKit's document search uses a local DuckDB database with hybrid semantic embedding + BM25 keyword search for high-quality results — no cloud dependencies.

Adding folders

1. Tap + Choose Directory in the Documents data source settings.
2. Use the quick-access chips (Downloads, Documents, Desktop) to add common folders in one tap.
3. Add multiple folders — all are indexed together into a single unified index.

File type filter

Select which file types to include using the chip selector. Supported types:

pdf docx doc txt md html htm csv json xml xlsx xls pptx ppt rtf odt ods odp epub mobi log

Use All to select every type or Reset to deselect all.

Indexing

• Tap Start Indexing to build or refresh the index.
• A red Stop button replaces the index button while indexing is active — tap to cancel.
• The index is stored locally; re-index only when your files change.

9   SSH

The SSH server gives the AI the ability to run shell commands on a remote host. Configure the connection in Settings → Data Sources → SSH:

• Host, port, username, password or private key path
• Optional default working directory

What the AI can do via SSH

• Run arbitrary shell commands and capture their output
• Check system status, disk usage, running processes
• Read log files and diagnose issues
• Start or stop services
• Execute custom scripts stored on your device

LLM-generated scripts

Ask the AI to write and immediately execute a script. Example prompt:

Connect to the server, write a bash script that gathers CPU usage every 5 seconds
for 1 minute and saves the results to /tmp/cpu_report.txt, then show me the summary.

The AI writes the script, uploads it via SSH, executes it, and returns the full output — all in one agent run.

Stored local scripts

Place your own .sh or .ps1 scripts in the Scripts Directory (set in Settings → General → Scripts Directory). The AI auto-discovers all scripts and you can reference them by name in prompts:

Run the "backup_db.sh" script on the server and tell me if it completed successfully.

Script Library & built-in samples

The Shell Script Library (accessible from the SSH configuration panel) lets you save, manage, and reuse scripts. Tap the 🔬 Load Samples button in the toolbar to instantly add three ready-to-use examples:

• Disk Usage — all mounted filesystems sorted by usage percentage
• Biggest Files in /usr/lib — top 20 largest files
• Top 10 Processes — highest CPU-consuming processes

10   Home Assistant

The Home Assistant MCP server lets the AI query and control any entity in your smart home via the Home Assistant REST API.

Setup

1. Open Settings → Data Sources → Home Assistant.
2. Enter your Base URL — e.g. http://homeassistant.local:8123 for local installs or your Nabu Casa cloud URL (https://<id>.ui.nabu.casa).
3. Create a Long-Lived Access Token:
   In Home Assistant open your Profile (bottom-left avatar) → scroll to Long-Lived Access Tokens → tap Create Token, give it a name (e.g. “TealKit”), and copy the token.
4. Paste the token into the Long-Lived Access Token field and tap Save.

What the AI can do

• Turn lights, switches, and plugs on or off
• Read sensor values (temperature, humidity, motion, energy usage …)
• Set thermostat target temperatures
• Lock and unlock doors
• Get the state of any entity (e.g. “Is the front door locked?”)
• List all entities in a domain (e.g. all light.* entities)
• Call any Home Assistant service action

Example prompts

Turn off all lights in the living room.

What is the current temperature in the bedroom?

Set the thermostat to 21 degrees and lock the front door.

Which lights are currently on?

11   Output Files

TealKit saves core files per agent run to a timestamped subfolder:

• output_log.md — the main result in Markdown
• execution_log.md — step-by-step tool call log
• output.html — rendered HTML version of the result

In addition, any file the AI generates during the run is saved automatically:

• .xlsx — Excel spreadsheets created by the excel server (e.g. “Export the data as an Excel file”)
• .png — charts generated by the chart server or Mermaid diagrams rendered by the mermaid server
• Any other .md, .html, .csv, .json files the AI writes via the file server

Configuring the output directory

Go to Settings → General and tap Output Directory to choose a folder. Defaults to an internal app folder if left blank.

Automatic cleanup

Use the Keep files for (days) setting (1–60 days, default 3) to automatically delete old runs. Cleanup runs on app start and every hour.

12   Settings

• LLM Settings — AI provider, model, API key, temperature, and advanced parameters (top-k, top-p, repeat penalty, seed)
• Data Sources — email, search, documents, websites, location, SSH, Home Assistant, Slack, WhatsApp
• Remote MCP Servers — connect to remote HTTP/SSE MCP servers (PulseMCP, Smithery, or Custom URL)
• MCP Server Registry PRO — (desktop) browse and install local Python/Node.js MCP servers from GitHub, Glama, PulseMCP, and Smithery catalogs
• General → Output Directory — where agent output files are saved
• General → Scripts Directory — local script library for SSH agents
• General → Keep files for (days) — output retention period
• General → Background check interval — how often the app wakes up in the background to check for due agents (5 / 10 / 15 min; default 10 min). A shorter interval is more responsive; a longer one saves battery.
• Language — English or German
• Theme — System / Light / Dark
• Backup & Restore PRO — export all agents, settings, and tool configurations to an encrypted vault file; restore on any device

13   FAQ

Does TealKit store my API keys on a server?

No. All API keys are stored exclusively in the device's OS secure keychain (iOS Keychain / Android Keystore) and never leave your device.

Can I use TealKit offline?

Local Ollama models work fully offline. Cloud AI providers and web search require an internet connection.

How do I delete all my data?

Uninstall TealKit. All local databases, keys, and settings are removed automatically.

The indexing is slow or stuck

Large document folders or websites with many pages take time. Tap the red Stop button to cancel at any point.

Where is the output folder on Android?

By default, files go to internal app storage. Set a custom path in Settings → General → Output Directory to use a visible folder (e.g. Downloads).

What is the difference between Prompt Splitting and Agent Chaining?

Prompt Splitting (++#++) breaks a single agent’s prompt into sequential steps within the same agent. All steps share the same model, tools, and settings. Use ${tool_result} in a later step to inject the raw tool output from the previous step. No Pro required — works in Playground, scheduled agents, and Server Mode. Best for small/local models that struggle with long multi-step prompts: split the work into focused single-purpose steps that each model can handle reliably.

Agent Chaining PRO connects separate agents: each agent has its own model, tools, schedule, and output configuration. The previous agent’s full output is injected as ${task_result} into the next agent’s prompt. Supports conditional routing — different follow-up agents depending on the LLM’s evaluation of a condition expression.

Short rule: use Prompt Splitting when you want to break a complex task into micro-steps within one agent; use Agent Chaining when you need different models, conditional logic, or independent schedules across steps. See Section 5.1 for a full comparison table.

How does agent chaining work?

Each chained agent starts after its predecessor finishes. The predecessor’s output is injected as ${task_result} into the chained agent’s prompt. Chaining can be unconditional (always runs the next agent) or conditional (the LLM evaluates an expression and routes to different agents depending on the outcome). Enable Stop after tool call on an agent to capture the raw tool output directly as ${task_result} without further LLM processing.

What is the difference between Run and Interactive mode?

Run executes the agent autonomously and saves the result to disk. Interactive opens a full chat with the same LLM and tools, so you can guide the AI step by step — useful for exploration or debugging a agent.

What is the advantage of using a European AI provider?

If GDPR compliance or data sovereignty is important to you — for example in a business or regulated environment — choose Mistral AI, a provider headquartered in France that processes all data within the European Union. TealKit is fully compatible with Mistral out of the box: enter your API key under Settings → LLM 1 and select Mistral AI as the provider. Your prompts and data stay in EU infrastructure at all times.

Can I run models directly on my device without the internet?

Yes. Go to Settings → Embedded Models to download GGUF models and run inference fully on-device — no API key, no cloud connection. Browse the built-in HuggingFace catalog or paste any direct GGUF URL. Choose CPU-only, partial GPU, or full GPU offloading per model. Embedded models work best for text formatting, translation, and summarisation in Chat Mode. For agentic tool calling you need both a model explicitly trained for function calling (e.g. Qwen2.5-3B-Instruct) and enough GPU VRAM to load it fully — otherwise inference is too slow or tool schemas are ignored. See Section 19 — Embedded Models for the full hardware and capability guide.

Can TealKit run with smaller models on limited hardware?

Yes. TealKit supports Small Language Models (SLMs) through Ollama, LM Studio, or any OpenAI-compatible local endpoint — no cloud costs, no data sent externally. Keep in mind that every model has different strengths: a prompt that works perfectly with one model may need adjustment for another. Use the Playground to experiment with prompts across different models and find the best fit for each agent before turning it into an automated workflow. For pure text agents (translation, formatting, summarisation) enable Chat mode in Playground or agent settings to skip all tool overhead and send your prompt directly to the LLM — the fastest path from prompt to response for SLMs.

My scheduled agent with an embedded model did not run on Android when the app was closed

This is expected behaviour. Embedded (on-device) GGUF models require the app to be open (foreground or background-alive). When Android fully kills the app, the background alarm wakes a lightweight isolate that cannot load the on-device model — doing so would risk a crash or out-of-memory kill. TealKit skips the task and sends a 📱 “Open TealKit to run ‘…’” notification instead. Tapping the notification opens the app and the missed run is caught up automatically.

For reliable unattended execution, switch the agent’s LLM to a cloud provider (Gemini, OpenAI, Anthropic, Mistral) or your own Ollama server. Cloud- and Ollama-based agents run fully in the background regardless of whether the app is open. On Desktop (Windows, Linux, macOS) the app always stays alive in the system tray, so embedded-model agents run normally there. The upcoming Server Mode also keeps a persistent scheduler running 24/7 without the mobile app needing to be open.

Scheduled agents don’t run reliably on iOS / iPad

On iOS, Apple’s BGAppRefreshTask system controls when background work is allowed. Unlike Android’s exact AlarmManager wakeup, iOS decides the timing itself based on battery level, network conditions, and recent app-usage patterns. Tasks may be delayed by minutes to several hours and will not fire at all when Low Power Mode is on or the app has not been used recently. TealKit registers a best-effort periodic background task; keep the app in the foreground or background (not fully closed / force-quit) for the most reliable scheduled execution on iOS.

14   JavaScript Tool PRO

The JavaScript Tool Wizard lets you create lightweight custom MCP tools using pure JavaScript — no native code or external packages required. Tools run in a secure on-device sandbox (QuickJS / JavaScriptCore) and are available immediately in Playground and Agents after saving.

Tool structure

Every generated tool must define exactly one object named generatedTool:

const generatedTool = {
  name: "bitcoin_price",
  description: "Fetch the current Bitcoin price from CoinGecko",
  inputSchema: {
    type: "object",
    properties: {
      currency: { type: "string", description: "Target currency code, e.g. usd" }
    },
    required: ["currency"]
  },
  execute: async (args) => {
    try {
      const cur = String(args?.currency ?? "usd").toLowerCase();
      const res = await fetch(`https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=${cur}`);
      const data = await res.json();
      return JSON.stringify({ ok: true, price: data.bitcoin[cur], currency: cur });
    } catch (error) {
      return JSON.stringify({ ok: false, error: String(error?.message || error) });
    }
  }
};

Runtime rules & limits

• execute(args) must return a JSON string via JSON.stringify(…) or a plain string
• fetch() is available for HTTP/REST calls
• console.log() output is captured and shown in test results
• Forbidden: require, import, process, fs, path, net, child_process
• Max script size: 64 KB  •  max response payload: 256 KB  •  default execution timeout: 8 s (max 15 s)
• ES6 syntax only — no top-level await outside execute()

Creating a tool step by step

Calling saved tools via MCP

When the js_bridge server is selected, the AI can discover and call your tools automatically:

• list_js_tools — returns all saved tools with their schemas
• run_js_tool — call by name: { "toolName": "bitcoin_price", "args": { "currency": "eur" } }
• Dynamic direct call — active tools are also registered as js_<name> tools (e.g. js_bitcoin_price)

Example prompts for generation

• “Fetch today’s EUR/USD exchange rate from the free Frankfurter API and return rate and date.”
• “Calculate compound interest. Input: principal, annualRate, years. Return: finalAmount, totalInterest.”
• “Look up a city name using the Open-Meteo geocoding API and return latitude, longitude, and country.”
• “Convert a Unix timestamp to a human-readable date string in a given timezone.”

15   Token & Cost Statistics

TealKit tracks token consumption and estimates API cost per session and per agent run. No data is sent to TealKit — all calculations use built-in pricing tables on your device.

Playground — live session stats

During a Playground chat, a token counter appears at the bottom of the chat area showing the cumulative tokens consumed and characters sent in the current session. The counter turns amber when approaching the model’s configured token warning threshold.

Tap the token counter to open the full detail sheet:

Agents — run statistics

Every completed agent run records full statistics. Tap any run entry in the agent history to view:

Supported providers for cost estimation

Cost estimates are calculated from built-in pricing tables for:

• OpenAI — GPT-4o, GPT-4, GPT-3.5-turbo & variants
• Anthropic — Claude 3.x & Claude 3.5 family
• Google Gemini — Gemini 1.5 & 2.0 series
• Mistral — Mistral Small, Medium, Large
• Azure OpenAI — same pricing tables as OpenAI

Playground stats example

Cumulative Tokens : 4 820
Prompt Tokens     : 4 210
Completion Tokens :   610
Last Request Cost : $0.0062
Session Cost      : $0.0241

16   Useful Tips

Quick practical suggestions to get the most out of TealKit.

🧩 Generate a JavaScript function

Open the JS Tool editor and describe the function precisely, including inputs, outputs, and the API to call:

Fetch the current Bitcoin price in EUR and USD from the free CoinGecko API.
Input: { currency: string }. Return: { price, currency, lastUpdated }.

Tap Generate, inspect the code, then Test Run it in the sandbox before saving. The tool is instantly available in any session.

📜 Write a shell script

Open the Shell Script Wizard and state the target environment, inputs, and expected behaviour:

Bash on Ubuntu. The script takes a folder path as argument,
finds all .log files older than 7 days, deletes them,
and prints a summary (count and freed space) to stdout.
Exit code 1 on error, error message to stderr.

After generation, tap Test Run to execute via SSH and verify the output before saving to the script library.

▶ Test a agent before scheduling

Before activating a cron schedule, open the agent with Interactive / Try-Out mode. This loads the agent’s configuration into a live Playground chat so you can step through the AI’s tool calls and refine the system prompt — without creating any scheduled run history.

☑️ Register a remote MCP server (custom)

Go to Settings → Remote MCP Servers → Custom tab and fill in:

• Name — a friendly label for the server
• Server URL — the HTTPS base URL of the cloud MCP server
• MCP Endpoint — typically /mcp (default)
• API Key / Password — only if the server requires authentication

Tap Test to validate connectivity and list the tools, then Add. The server’s tools appear immediately in the tool selector.

💰 Check current session costs

In the Playground: tap the token counter at the bottom of the chat → the detail sheet shows last-request cost and cumulative session cost.

For Agents: open the agent → tap a completed run entry → the Last Run Statistics card shows Last price and Total price.

↺ Reset a session (cleanup)

Tap the Reset Chat button (↺ icon in the toolbar, or the button below the last message) to:

• Clear all conversation history from the current session
• Reset the token counter and session cost to zero
• Keep the system prompt, tools, and configuration intact

The AI starts fresh with no memory of the previous conversation — useful when switching topics or when context has grown too large.

🖥 Pro unlocks the Windows & Linux desktop apps

Purchasing TealKit Pro on Android or iOS includes the Windows and Linux desktop versions at no extra cost — one purchase, all platforms. The Windows app is on the Microsoft Store; the Linux build is downloadable from GitHub Releases. macOS support is coming in a future release.

🔒 What Pro unlocks

TealKit includes a 31-day free trial with full Pro access. After the trial expires without Pro, TealKit stays available in a local manual mode: you can still run agents manually, save results to local files, and use the basic local bridges. Pro unlocks the advanced automation and integration features:

• Scheduled agents and recurring background automation
• Advanced output channels: Email, Slack, WhatsApp, and SFTP
• Remote MCP servers and hosted MCP catalogs
• Website and document auto-index schedules
• PDF writer, Mermaid PNG generation, and Excel export
• Save Playground chat as a reusable agent
• Task chaining and follow-up agents
• Home Assistant integration
• Backup and restore vault

17   Desktop Features PRO

The Windows desktop app is available on the Microsoft Store. The Linux version is downloadable from GitHub Releases. macOS support is coming in a later release. Buying any single TealKit mobile version unlocks the desktop app at no extra cost.

📜 Script Generation — Shell & PowerShell PRO

Generate ready-to-run scripts directly on your local machine. Describe your agent in plain language and the AI writes the complete script, which you can run immediately or save to your script library. The script type is chosen automatically based on your platform:

• Windows — generates a PowerShell script (.ps1)
• Linux / macOS — generates a Shell script (.sh)
• Scripts are saved locally and auto-discovered for use in Agents and SSH sessions
• Tap Test Run to execute the generated script and verify the output before saving
• Name the target environment in your prompt: “PowerShell on Windows Server” or “Bash on Ubuntu”

🧪 Shell Script Library — built-in samples PRO

The Shell Script Library retains all your generated and saved scripts. Tap 🔬 Load Samples to add three ready-to-use examples:

• Disk Usage — all mounted filesystems sorted by usage percentage
• Biggest Files in /usr/lib — top 20 largest files
• Top 10 Processes — highest CPU-consuming processes

🐍 Python MCP Tool Generator PRO

Create custom MCP server tools written in Python directly from within TealKit. Describe what you need in plain language and the AI generates a complete, runnable Python MCP tool including input schema and execute function.

• Tools run locally in a sandboxed Python environment
• Full access to standard Python libraries (json, datetime, math, re, urllib …)
• HTTP calls via urllib.request or the bundled requests library
• Generated tools are saved and auto-discovered by TealKit
• Available immediately in any Playground session or Agent on Windows

🧪 Python Tool Library — built-in samples PRO

The Python Tool Library keeps all your generated Python MCP tools. Tap 🔬 Load Samples to add three starter examples:

• System Info — CPU, memory, and disk usage via psutil
• Fetch Web Page — download any URL and return its text content
• List Directory — list files and folders in a given path

🪟 PowerShell Tool Library PRO (Windows only)

On Windows, a dedicated PowerShell Tool Library lets you create, manage, and reuse .ps1 scripts executed locally by the AI via the ps_bridge MCP server. Tap 🔬 Load Samples to add three ready-to-use examples:

• Windows System Info — OS version, hostname, CPU, memory, and uptime
• Last Windows Updates — 10 most recently installed Windows Updates
• Fetch Website Status — HTTP status code and response time for any URL

📦 MCP Server Registry PRO (desktop)

The MCP Server Registry lets you install Python and Node.js MCP servers locally with a single tap — no terminal, no package manager commands. Go to Settings → MCP Server Registry. TealKit automatically runs npm install -g, uvx, or pip in the background and registers the server.

Installed servers run locally on your machine and are started automatically by TealKit when needed. Their tools appear in the same tool selector as built-in and remote servers.

Installing a server (example: Filesystem)

18   Best Practices

💸 1   Reduce tokens, network calls, and cost

The most expensive part of any automated agent is the back-and-forth between the LLM and the outside world. Every tool call round-trip uses tokens and time. A simple optimisation: delegate the heavy lifting to a script or MCP tool and let the LLM only interpret the final result.

Example — listing recent uploads via SSH:

Instead of asking the LLM to run multiple SSH commands to filter files by date, format sizes, and build a table, create a single shell script in the Script Library (e.g. check_uploads) that does all of that and returns a clean CSV with column headers. Your agent prompt then becomes simply:

Call script check_uploads /uploads 48
Create an Excel file from the returned CSV list.

The LLM makes two tool calls (run script, create file) instead of ten. Fewer tokens, faster execution, lower API cost, and a more reliable result.

🧪 2   Use the Script/JS wizards — but always test first

The Shell Script Wizard and JavaScript Tool Wizard can generate working code from a plain-language description. A clear prompt that specifies inputs, outputs, and edge cases gives the best results. However:

• Always tap Test Run after generation. The first attempt may not work if the prompt was ambiguous or the model is less capable — refine and regenerate.
• For code generation, small models (Ollama / LM Studio running locally, or Ollama on your own server) are often sufficient and cost nothing. Configure them as LLM 2 and use the Playground LLM selector to run code-generation prompts through LLM 2 while keeping your main agents on LLM 1.
• Embedded models are now available: go to Settings → Embedded Models to download GGUF models and run inference directly on your device — no external server or API key required. Select CPU / Partial GPU / Full GPU offloading per model. Best for simple text tasks (Chat Mode); see Section 19 for hardware and tool-calling limitations.

🖥 Desktop scripting environments

On desktop, three scripting environments are available — each with its own wizard and library:

🪟 PowerShell tips (Windows)

• Start prompts with “PowerShell 5.1 on Windows” or “PowerShell 7 on Windows Server” to target the right version.
• Ask for param() blocks so the AI can call the script with named arguments.
• Request output to stdout as plain text or CSV so TealKit can capture it as a tool result.
• Example prompt: “PowerShell on Windows. Param: folder path. List files modified in the last N hours with name, size (KB), and last-modified date. Output CSV to stdout with header row.”

🐍 Python tips (all platforms)

• TealKit runs Python tools inside a managed virtual environment. Specify required packages in your prompt: “use pandas and openpyxl” — TealKit installs them automatically on first run.
• Python is the best choice for data manipulation (CSV/Excel/JSON), calling REST APIs with requests, or anything that needs a third-party library.
• Example prompt: “Python 3. Param: csv_path. Read the CSV with pandas, compute min/max/mean for every numeric column, return the result as a JSON string. Requires: pandas.”
• On macOS, specify “macOS Bash” or “Python 3 on macOS” in shell prompts — some paths and commands differ from Linux (e.g. gdate vs date -d).

🧠 3   Match model to agent complexity

Not every agent needs the same model. As a rough guide:

• Complex reasoning, multi-step planning, long documents → use a full LLM (GPT-4o, Gemini 2.5 Pro, Claude Sonnet, Mistral Medium …)
• Short, deterministic actions (run a script, format a CSV, send a notification) → an SLM may handle these reliably and at a fraction of the cost. Enable the SLM mode checkbox in LLM Settings to activate a compact system prompt that makes small models call tools immediately rather than explaining their plan.
• Keep in mind that SLMs may not complete complex agents reliably on every run, or may take several minutes. Test thoroughly in the Playground before scheduling.
• Embedded (on-device) models follow the same rules as SLMs but with additional hardware requirements — see Section 19 for a full guide. Short version: without a dedicated GPU, CPU-only inference on a 3 B+ model can take minutes per response; most small GGUF models were not fine-tuned for tool calling and will ignore or hallucinate tool schemas even with GPU acceleration.
• Android background limit: Embedded-model agents require the app to be open. If Android kills the app, the background alarm skips embedded tasks and sends a tap-to-open notification (the run is caught up when you reopen the app). Use a cloud or Ollama provider for agents that must run fully unattended. On Desktop and in Server Mode this limitation does not apply.

Use the LLM 1 / LLM 2 selector in the Playground to run the same prompt through different models side-by-side. Also experiment with the Temperature setting — lower values (e.g. 0.1–0.2) produce more deterministic, reproducible tool calls; higher values add creativity but reduce reliability for automation agents.