GitHub - XAIHT/Tlamatini: Tlamatini is a self-hosted AI developer assistant for local or cloud LLMs: hybrid RAG over your codebase, a 79-tool multi-turn engine, a 74-agent visual workflow designer, and ACPX, a runtime for external coding agents like Claude Code, Cursor and Gemini CLI.

The local-first AI developer assistant with a visual workflow designer — and the reach to touch hardware, 3D engines, and any external tool.
"one who knows" — it doesn't just edit code. It flashes your board, drives your engine, and orchestrates whole agent workflows on a canvas. On your machine.

💰 About $200 a YEAR — not $200 a MONTH.
Frontier plans like GPT-5.4 or Claude Opus cost about $200 per month. Tlamatini is free and open-source — your only bill is Ollama Pro (~$200 a year, paid to Ollama, not us), and on top of it she stacks 86 agent types and 75+ tools: comparable power for about one twelfth the price, all on your own machine.

🌐 Website · ▶️ One-minute teaser · 📖 Full docs · 💬 Discord

💬 Join the Tlamatini community on Discord — get help, show what you build, report bugs, and shape the roadmap.

🚀 Get started — 5 steps to a cloud-powered Tlamatini

The whole idea in one line: don't pay $200 a month for a frontier model. Tlamatini is free — your only cost is Ollama Pro (~$200 a year, paid to Ollama, not us); point Tlamatini at it and drive 86 agent types and 75+ tools from your own machine. Here's the full setup.

1 · Install Tlamatini

Pick one of two paths. Tlamatini itself is free — you never pay us; the only cost is Ollama (Step 3).

🟢 Option A — Release installer (recommended · no Python needed)

Best for most people. The installer bundles its own Python 3.12.10 and every dependency, so you install nothing else.

1. Open the Releases page and download the latest installer (.exe).
2. Run it and follow the wizard.
3. Launch Tlamatini from the Start-menu shortcut.
4. Your browser opens at http://127.0.0.1:8000/ — log in with user / changeme. (8000 is the default port; if it's taken or Windows has reserved it, set django_port in config.json — see the port note below.)

🔄 Updating later is one click: About ▸ Check for updates inside the app — it keeps your config, database, and keys.

🔵 Option B — From source (for developers)

Best if you want to read, modify, or contribute to the code. Requires Python 3.12.10 and git already installed.

git clone https://github.com/XAIHT/Tlamatini.git
cd Tlamatini
python -m venv venv && venv\Scripts\activate
pip install -r requirements.txt
python Tlamatini/manage.py migrate
python Tlamatini/manage.py runserver --noreload
# then open http://127.0.0.1:8000/   (default login: user / changeme)

--noreload is optional (since 2026-07-11): plain python Tlamatini/manage.py runserver now boots clean and auto-reloads on code edits. It used to double-start the MCP helper ports :8765 / :50051 and crash with WinError 10048; fixed by a reloader-aware gate in agent/apps.py.

netsh interface ipv4 show excludedportrange protocol=tcp

2 · Install Ollama

Install Ollama for Windows. Ollama is the engine that serves every model to Tlamatini — the local embedding model and the cloud chat models.

3 · Subscribe to Ollama Pro (~$200 / year)

Go to ollama.com, sign in, and take the Ollama Pro plan (about $200 per year). Pro unlocks the :cloud models — frontier-class models that run on Ollama's servers — for a yearly price close to what one frontier subscription costs in a single month. Then connect your machine:

4 · Download the models

Pull the small local embedding model, plus the cloud chat models Tlamatini will use:

# Local embedding model (small, runs on your own GPU/CPU)
ollama pull nomic-embed-text

# Cloud models (served by Ollama Pro) — pull, or just sign in to use
ollama pull glm-5.2:cloud
ollama pull qwen3.5:cloud

Any cloud model works — these two are the current recommended pair (older screenshots below may still show earlier model names).

5 · Point Tlamatini at the models

In the Tlamatini navbar, open the Config menu:

a) Config ▸ Models — set the Ollama model for each subsystem (each one must already exist in your Ollama catalog), then click Save:

b) Config ▸ Access Keys Wizard — whether you need an Ollama token depends on where Ollama runs:

• 🖥️ Ollama on your own machine (localhost)? Leave the token blank — a local Ollama needs no auth.
• ☁️ Ollama on a remote server (e.g. Vast.ai)? Paste the Ollama token so Tlamatini can reach it.

Add any cloud-CLI keys here too — plus the messaging keys, the Kali server URL, and the OPTIONAL ProjectDiscovery Cloud (PDCP) key under "Security Recon (ProjectDiscovery)". Blank fields keep what's already configured; click Save:

Done — tick Multi-Turn in the chat toolbar and put Tlamatini to work.

💎 The jewels — what nothing else can do

Claude Code, Codex, Cursor, Gemini — they edit text files. Tlamatini does that and reaches into the physical and creative world, then lets you wire it all together visually:

The headline no competitor can copy: Tlamatini is the only local-first AI dev assistant where you design the agent workflow visually, then have it flash firmware, drive Unreal/Blender, run security tools, and command any external MCP — all from one machine.

🔒 And it's yours alone

Embeddings and chat run on your local Ollama install. Cloud models (Claude API, Ollama Pro/Max) and delegation to cloud CLIs are opt-in, per request, never the default. Your code and firmware never leave the box unless you route them out yourself.

⚠️ CLEAR DISCLAIMER — USER CONTROL, JURISDICTION, AND RESPONSIBILITY FOR AGENTS

Every agent in Tlamatini/agent/agents/ is intentionally provided as a plain-Python program so its operating code can be read, audited, edited, restricted, or disabled by the user. This transparency is a user-control mechanism, not a warranty that an agent is secure or suitable for a particular environment. The agents do not have independent authority or jurisdiction: the user alone decides whether, where, how, and with which permissions they run.

When you enable, configure, modify, chain, or execute an agent, that agent and its execution are under your control and your jurisdiction. You are solely responsible for reviewing its code and configuration; protecting and limiting its secrets, credentials, and permissions; selecting and authorizing every file, folder, network target, browser, shell, API, external MCP server, machine, hardware device, and downstream system it can access; supervising its output; and complying with every law, policy, license, contract, and authorization that applies to your use.

BY RUNNING AN AGENT, YOU ACCEPT RESPONSIBILITY FOR ITS ACTIONS AND CONSEQUENCES. TO THE FULLEST EXTENT PERMITTED BY APPLICABLE LAW, ANY SECURITY BREACH, DATA EXPOSURE OR LOSS, UNAUTHORIZED ACTION, CREDENTIAL LEAK, UNSAFE AUTOMATION, POLICY OR LEGAL VIOLATION, SYSTEM COMPROMISE, DEVICE DAMAGE, FINANCIAL LOSS, OR OTHER HARM ARISING FROM YOUR USE, CONFIGURATION, MODIFICATION, OR EXECUTION OF AN AGENT OR AGENT WORKFLOW IS THE RESPONSIBILITY OF THE USER WHO RUNS IT. Tlamatini's orchestration, documentation, examples, and guardrails do not authorize access to third-party systems and cannot replace the user's own security review, permission controls, monitoring, or legal compliance.

📋 The full capability list

Everything Tlamatini can do, grouped:

🧩 Orchestration & design

• Visual Workflow Designer (ACP) — 85 drag-and-drop agent types wired into runnable flows; save/load .flw files; Flow Compiler validates the canvas into config.yaml.
• Multi-Turn orchestration — a tool-calling loop with 75 tools and a global execution planner; Step-by-Step mode paces hands-on setup one action at a time; self-healing model steps mean a network/model hiccup never freezes her — she retries under a watchdog, finishes gracefully from work already done, and always tells you what happened.
• FlowCreator / FlowHypervisor — let an LLM design a flow; a watchdog monitors flow health. FlowCreator is now also callable from chat (chat_agent_flowcreator): describe a flow in plain words and it writes a real, canvas-loadable .flw file to disk.
• Parametrizer / Gatewayer / Gateway-Relayer / Node Manager — chain agent outputs into the next agent's config; trigger flows from webhooks, folder-drops, or GitHub/GitLab.
• ACPX — spawn external coding-agent CLIs (Claude Code, Codex, Cursor, Gemini, Qwen, and more) as tools and relay between them.

📟 Firmware & hardware

• STM32er — zero-config STM32 build/flash/observe across the whole ST 32-bit line (Blue Pill → F7/G/L/H7/U5/WB) via a dual backend (PlatformIO ststm32 + the STM32F407VG template MCP), with a critical-mission safety preflight.
• ESP32er — direct PlatformIO build/flash/monitor, zero-config bootstrap.
• Arduiner — direct arduino-cli, auto-installs binary + core, build/upload.
• ESPHomer — ESPHome smart-home device configs (YAML, no C++), zero-config.

🎬 3D & creative engines

• Unrealer — Unreal Engine control from chat.
• Blenderer — Blender scene/object/render/code over the official MCP socket.

🛠️ Code & projects

• PDFer — the document composer: turn Tlamatini's own answer, some Markdown/HTML, plain text, a folder of images, or several existing PDFs into ONE styled PDF — with a cover page, real tables, page numbers and an optional table of contents. It is the WRITE side of the document family (File-Extractor / File-Interpreter read documents; PDFer authors them). Needs no installation — every engine it uses already ships inside Tlamatini. Modes: auto (it sniffs the content for you) / markdown / html / text / images (one-per-page, fit, or grid) / mixed (prose + embedded figures) / merge / info / validate. Optionally let an Ollama model tidy the text into clean Markdown first (off by default; a failed tidy never loses your document). PDFs land in Documents/TlamatiniPDF with a collision-proof name, and a fail-safe preflight refuses rather than write an empty or wrong file.
• Editor / Grepper / Globber — surgical find-and-replace, regex content search, filename glob (Claude-Edit/Grep/Glob equivalents).
• File-Creator / Mover / Deleter / File-Interpreter / File-Extractor — create, move, delete, read-and-interpret, extract from PDF/DOCX.
• Executer / Pythonxer — run shell commands and gated Python.
• Gitter — full git control. Googler — web search + extract.
• Hybrid RAG — FAISS + BM25 retrieval, metadata extraction, context budgeting, grounded in your codebase.
• Skills — SKILL.md packages: code-review, security-audit, kali-pentest, flow-making, skill-creator, summarize, audit/lint/refactor helpers, and integration stubs (GitHub, Gmail, Slack, Jira, Notion, Todoist, Trello, Weather).

🛡️ Security

• Kalier — authorized Kali Linux / MCP-Kali-Server offensive-security assessments.
• Discoverer — ProjectDiscovery recon suite (subfinder/httpx/naabu/katana/nuclei/cvemap — the CVE search runs ProjectDiscovery's vulnx, since cvemap's own API was retired Aug 2025) via a self-installing private Go toolchain in <install_dir>/Go; authorized recon, attack-surface mapping & vulnerability discovery. The ProjectDiscovery Cloud (PDCP) key is OPTIONAL (lifts cvemap/vulnx rate limits, enables nuclei -ai/cloud upload) — set it once in Config ▸ Access Keys Wizard ▸ "Security Recon (ProjectDiscovery)" (auto-injected into every run; redacted from .flw exports and by regen_secrets.py before a push).
• Nmapper — LOCAL, use-only nmap bridge for pentesters / CTF: runs a real nmap the user installed themselves (Nmapper NEVER bundles or redistributes nmap — nmap's NPSL forbids embedding it in a product without a paid OEM licence), resolving it from PATH → C:\Program Files\Nmap → a %LOCALAPPDATA%\Tlamatini\nmap copy; if it's absent it refuses gracefully and action='install' fetches the OFFICIAL free nmap installer (admin/UAC; also brings Npcap). The default is an UNPRIVILEGED TCP connect scan (-sT, no Npcap, no admin) so a fresh install scans immediately; SYN / -O / UDP auto-downgrade to a connect scan on Windows without Npcap. Actions: quick / full / top_ports / version / scripts (NSE) / host_discovery / udp / custom / validate / install; emits INI_SECTION_NMAPPER. Distinct from Kalier (a remote Kali box) and Discoverer (ProjectDiscovery). Authorized targets only.
• Zavuerer — Zavu unified messaging: SMS / WhatsApp / Telegram / Email / Voice from ONE API key (channel: auto smart-routes to the best channel with auto-fallback). Set the key once in Config ▸ Access Keys Wizard ▸ "Unified Messaging (Zavu)"; direct HTTP, fail-safe preflight, refuses safely when no key is set. Zavu pricing: sign-up is free (no card), but sending is pay-as-you-go — Zavu charges per message.
• security-audit / kali-pentest skills.

🔌 External integration

• Universal External-MCP client — connect to any MCP server over 4 transports, up to 5 active, with 8 supervisor tools and an MCP Doctor agent that triages a server before you wire it.
• Companion-app discovery (Tlamatini-FlowPills) — sister XAIHT apps locate Tlamatini's agent-template catalog instantly, with no Python and no drive scan: at install and on every launch Tlamatini publishes a per-user HKCU\Software\XAIHT\Tlamatini registry key + an _tlamatini_agents_manifest.json (each agent's sha256) next to the agents, and leaves a preserved-agents marker if you uninstall but keep the agents. HKCU-only, no admin, fail-open.

🖥️ Desktop & browser automation

• Playwrighter — scripted browser automation.
• Windower — Win32 window manager (focus/move/resize/tile/close).
• Shoter / Mouser / Keyboarder — screenshots, mouse, keyboard.

🎙️ Audio, video, vision & speech

• Talker (TTS) — text-to-speech via Ollama. Whisperer (STT) — speech-to-text (faster-whisper local + cloud fallback).

• Recorder / Camcorder — microphone and webcam capture.

• AudioPlayer / VideoPlayer — audio and video playback with volume/loop control.

• Image-Interpreter — triple-model vision analysis: qwen3.5:cloud + gemma4:cloud interpret each image in parallel on two dedicated Ollama connections, then glm-5.2:cloud merges both interpretations into one definitive report (mockup/GUI inventories in % coordinates, full OCR, people described exhaustively with identity clues taken from the image file name).

• Screenshot → chat (paste or drop) — hit Print Screen (or snip), Alt+Tab back to Tlamatini and press Ctrl+V — or drag image files onto the chat column. She saves the image into her own Temp folder as image_<timestamp>.jpg, shows a thumbnail above the input, and drops the full path into your message at the cursor, so you can finish the sentence — "…what's wrong in this screenshot?" — and send. The path is what Image-Interpreter reads.

📨 Messaging, bridges & platform

• Telegrammer — Telegram send/receive that can send under two identities, picked per message with provider: as the bot (provider=bot, Bot API + a @BotFather token) or as your own account (provider=user, official Telegram user session). Plain English works — say "send it as me" (→ your account) or "as the bot". auto (the default) uses your account for private @usernames/+phone and the bot for numeric ids/channels. Sending as you needs a one-time login; human configs stay readable as @username.
• Whatsapper — WhatsApp send/receive with a provider switch for which number sends: cloud (default, the official Meta WhatsApp Cloud API — business number, templates, System User) or web (say "send it as me" / "from my own WhatsApp") which sends from your own personal number by automating WhatsApp Web after a one-time QR login — no templates, no System User. The web path is unofficial (it drives WhatsApp Web) and carries Meta-ban risk; the cloud path remains the official, supported route.
• Instant Messaging Doctor — automatically diagnoses Telegrammer/Whatsapper failures and can be called directly before critical sends; validates official tokens, contacts, readable @username routing, Meta templates/webhooks, and emits Parametrizer-ready repair actions.
• TeleTlamatini — Telegram bridge into the full chat.
• Multi-model — Ollama (local), Anthropic Claude (cloud), Qwen (vision).
• Self-knowledge & self-modification — can read, modify, and rebuild her own source.
• PyInstaller packaging — ships as a standalone Windows .exe.

🧹 Your context stays clean — automatic binary detection

When you point Tlamatini at a folder (Context ▸ Set directory as context), real projects are full of files that are not text: compiled binaries, images, archives, model weights, databases, build artefacts. Feeding those into an embedding index is pure damage — it wastes VRAM and time, and it buries your real code under noise.

Tlamatini screens every file by its actual bytes before loading it, and silently skips the binary ones. It is on by default and needs no setup.

• Fast by design — at most one 8 KiB read per file, and known binary extensions are never opened at all. Screening a 4 GB video costs the same as screening a README.
• Content-based, not name-based — a PNG renamed notes.md is still caught. This works alongside Context ▸ Set file type omissions, which stays exactly as it was for the files you choose to ignore.
• Never silent — every skipped file is listed in tlamatini.log with the reason it was skipped, so you always know why something is not in your context:

--- [BINARY-GUARD] 3 binary file(s) OMITTED from the context / embedding chain
--- [BINARY-GUARD]   ✗ OMITTED C:\proj\assets\logo.png  [extension: known binary extension .png]

• Safe by default — if anything is uncertain or unreadable, the file is loaded as text rather than dropped. Your context is never removed on a guess. Accented and legacy-encoded text files (Spanish, French, cp1252 …) are always kept.

Turn it off with "binary_context_detection": false in config.json; tune it with binary_detection_control_ratio, or rescue a specific extension with binary_detection_force_text_extensions.

See it work

• ▶️ One-minute teaser · 🎬 more demos on xaiht.org.

Installation

See the full docs for complete setup — cloud models (Ollama Pro/Max, Claude API), the visual workflow designer, and building a frozen Windows distribution with PyInstaller. In short: install Ollama → clone, venv, pip install -r requirements.txt, migrate → runserver (--noreload optional since 2026-07-11) → open http://127.0.0.1:8000/.

Tech stack

Python 3.12 · Django 5.2.4 · Django Channels (Daphne ASGI) · LangChain / LangGraph · FAISS + rank-bm25 · Ollama / Anthropic Claude / Qwen vision · SQLite · PyInstaller. Platform: Windows 10/11.

Contributing

Tested it on your board, in your engine, or on the canvas? Open an issue and tell me what worked and what didn't — that feedback is the most useful thing right now. PRs welcome.

License

MIT · Built by @XAIHT · xaiht.org