Tlamatini – Local-first AI dev assistant with 68 agents and hybrid RAG

Tlamatini, a locally-deployed AI developer assistant named after the Nahuatl word for "one who knows," now features 68 drag-and-drop agents following its v1.9.0 release. The tool combines a hybrid RAG pipeline with a multi-turn orchestration layer and ACPX delegation to external coding agents, operating local-first by default with cloud LLMs as opt-in only. The latest update introduces the STM32er agent, a zero-config firmware bridge that scaffolds, builds, flashes, and observes STM32 microcontrollers while refusing to produce or flash mis-targeted firmware.

"one who knows" — a locally-deployed AI developer assistant Tlamatini Nahuatl for "one who knows" is a locally-deployed AI developer assistant that pairs a hybrid RAG pipeline 82-rag FAISS + BM25, metadata extraction, context budgeting with a Multi-Turn 35-tutorial-the-multi-turn-toggle tool-orchestration layer, ACPX 5-acpx--external-coding-agent-clis-as-tools delegation to external coding-agent CLIs Claude Code https://docs.anthropic.com/en/docs/claude-code/overview , Cursor https://cursor.com , Codex https://github.com/openai/codex , Gemini https://github.com/google-gemini/gemini-cli , Qwen https://github.com/QwenLM/qwen-code , … , and a visual workflow designer 4-visual-workflow-designer-agentic control panel with 68 drag-and-drop agents . Local-first by default: the full RAG pipeline, the Multi-Turn execution loop, and every workflow agent run on your machine — embeddings and chat are driven by your local Ollama install. Cloud LLMs Claude API, Ollama Pro/Max and ACPX delegation to cloud CLIs are opt-in per-request, never the default. Sensitive code never leaves the box unless you explicitly route it out. Latest — v1.9.0 2026-05-26 : STM32er, zero-config firmware bridge.A newSTM32eragent canvas node + Multi-Turn tool chat agent stm32er brings the catalog to68 agents. It bridges the STM32 Template Project MCP to scaffold, build, flash, observe serial / SWD , and reset STM32 firmware.Zero-config auto-bootstrapmeans the user only installs STM32CubeIDE + Tlamatini — STM32er downloads, installs, and validates the MCP server on first use. Acritical-mission safety preflightvalidates the toolchain and a positively-confirmed connected ST-LINK probe before flashing, andrefusesrather than producing or flashing mis-targeted firmware. Three new catalog demos ship in migration 0103 STM32 GENESIS / BLINKY / HIL OBSERVATORY . See §3.15 . 🌐 Website https://xaiht.org · · https://www.youtube.com/watch?v=4MyRXBahHuU&t=41s ▶️ One-minute teaser · /XAIHT/Tlamatini/blob/main/BookOfTlamatini.md 📖 Long-form docs · /XAIHT/Tlamatini/blob/main/VERSIONING.md 🏷️ Versioning 🎬 More demos 1. Overview 1-overview 2. Quickstart source mode 2-quickstart-source-mode 3. Using the Chat 3-using-the-chat-agent /agent/ 3.1. Chat layout in 30 seconds 31-chat-layout-in-30-seconds 3.2. Setting code as context 32-setting-code-as-context 3.3. Tutorial: a one-shot question no toggles 33-tutorial-a-one-shot-question-no-toggles 3.4. Tutorial: the 34-tutorial-the-internet-toggle internet toggle 3.5. Tutorial: the 35-tutorial-the-multi-turn-toggle Multi-Turn toggle 3.6. Tutorial: the 36-tutorial-the-exec-report-toggle Exec Report toggle 3.7. Tutorial: the 37-tutorial-the-acpx-toggle ACPX toggle 3.8. From chat to flow: the 38-from-chat-to-flow-the-create-flow-button Create Flow button 3.9. Why Chat-created flows are safer now 39-why-chat-created-flows-are-safer-now 3.10. The 310-the-db-menu--backup-set-db-and-the-start-up-swap-in DB menu — Backup, Set DB, and the start-up swap-in 3.11. The 311-the-acpx-skills-menu--browse-configure-diagnostics-reload ACPX-Skills menu — Browse, Configure, Diagnostics, Reload 3.12. Tutorial: command a window from chat 312-tutorial-command-a-window-from-chat-chat agent windower chat agent windower 3.13. Tutorial: drive a browser from chat 313-tutorial-drive-a-browser-from-chat-chat agent playwrighter chat agent playwrighter 3.14. Tutorial: run Kali Linux tools from chat 314-tutorial-run-kali-linux-tools-from-chat-chat agent kalier chat agent kalier 3.15. Tutorial: build and flash STM32 firmware from chat 315-tutorial-build-and-flash-stm32-firmware-from-chat-chat agent stm32er chat agent stm32er 4. Visual Workflow Designer 4-visual-workflow-designer-agentic control panel /agentic control panel/ 4.1. Canvas anatomy 41-canvas-anatomy 4.2. Tutorial: your first flow 3 agents 42-tutorial-your-first-flow-3-agents 4.3. Saving and loading 43-saving-and-loading-flw-files .flw files 4.4. Validate and Start now compile the live canvas 44-validate-and-start-now-compile-the-live-canvas 4.5. Pause, Resume, Stop 45-pause-resume-stop 4.6. FlowHypervisor watchdog 46-flowhypervisor-watchdog 4.7. FlowCreator let an LLM design the flow 47-flowcreator-let-an-llm-design-the-flow 4.8. Parametrizer chain outputs into the next agent's config 48-parametrizer-chain-outputs-into-the-next-agents-config 4.9. Gatewayer external triggers 49-gatewayer-external-triggers 5. ACPX — External Coding-Agent CLIs as Tools 5-acpx--external-coding-agent-clis-as-tools 6. Unreal MCP — Driving Unreal Engine 5 from Tlamatini 6-unreal-mcp--driving-unreal-engine-5-from-tlamatini 6.1. What Unreal MCP is 61-what-unreal-mcp-is 6.2. The MCP plugin source the 62-the-mcp-plugin-source-the-mcp-git-location MCP git location 6.3. Installing and enabling the plugin inside your UE5 project 63-installing-and-enabling-the-plugin-inside-your-ue5-project 6.4. The command catalog up to 53 commands across 9 categories 64-the-command-catalog-up-to-53-commands-across-9-categories 6.5. Using Unreal MCP from the chat 65-using-unreal-mcp-from-the-chat-chat agent unrealer chat agent unrealer 6.6. Using Unreal MCP on the canvas the visual 66-using-unreal-mcp-on-the-canvas-the-visual-unrealer-node Unrealer node 6.7. What the agent actually does, end-to-end 67-what-the-agent-actually-does-end-to-end 6.8. Exec Report integration 68-exec-report-integration 6.9. Bullet-proof checklist for Unreal Engine users 69-bullet-proof-checklist-for-unreal-engine-users 6.10. Troubleshooting Unreal MCP 610-troubleshooting-unreal-mcp 7. Building a Frozen Distribution 7-building-a-frozen-distribution 8. Configuration 8-configuration-tlamatiniagentconfigjson Tlamatini/agent/config.json 9. Architecture at a Glance 9-architecture-at-a-glance 10. Embedding-Memory Pre-Flight Guard GPU hosts 10-embedding-memory-pre-flight-guard-gpu-hosts 11. Orphan-Process Cleanup 11-orphan-process-cleanup-conhostexe-reaper conhost.exe reaper 12. Troubleshooting 12-troubleshooting 13. Versioning 13-versioning 14. Contributing & License 14-contributing--license Tlamatini Nahuatl for "one who knows" is a Django/Channels app you run on your own machine. It packages a hybrid RAG pipeline, a Multi-Turn tool-calling LLM loop, an ACPX runtime that spawns external coding-agent CLIs as child processes, an Unreal MCP client that drives Unreal Engine 5 from chat or canvas, and a drag-and-drop workflow designer with 68 agent types — into one local install. Backends: Ollama local , Anthropic Claude cloud , Qwen vision Ollama . License: GPL-3.0 · Repo: https://github.com/XAIHT/Tlamatini.git https://github.com/XAIHT/Tlamatini.git · Platform tested: Windows 11 cross-platform for source mode . Real RAG over your code — FAISS + BM25 hybrid retrieval, code-aware metadata extraction, Reciprocal Rank Fusion, context budgeting, OOM fallback. Multi-Turn mode — the LLM becomes an operator : shell, Python, APIs, SQL, file ops, screenshots, keyboard/mouse automation, email, Telegram, WhatsApp, STM32 firmware build/flash — chained in one conversation. ACPX — delegate sub-tasks to external CLIs claude , cursor-agent , codex , gemini , qwen-code , plus 8 more and relay output between them. Visual workflow designer — design .flw flows once, run them unattended, schedule with Croner, watch them with FlowHypervisor. Self-aware — a first-person self-knowledge map Tlamatini.md is injected into the LLM's prompt on every chain, so Tlamatini can answer accurately about her own architecture, runtime modes, ports, and pages. Builds packaged with --self-modify ship her own source tree TlamatiniSourceCode/ so she can read, inspect, and modify herself. Everything runs locally. The whole app packages into a one-click Windows .exe distribution Part §7 7-building-a-frozen-distribution . First system-usage walkthrough https://www.youtube.com/watch?v=CkvDPSd c-g Loading a complete project and summarizing its source code https://www.youtube.com/watch?v=Lrpbt dPIXw Installing OpenCV end-to-end in Multi-Turn https://www.youtube.com/watch?v=bBlqbZVK-Wk Uninstalling Poco — Exec Report and matching flow https://www.youtube.com/watch?v=E5vi0q5FxXQ Implementing a FlowCreator-aided agentic flow https://www.youtube.com/watch?v=3Pno6s4xVsE A complete Cybersec enhancement with Tlamatini https://www.youtube.com/watch?v=4MyRXBahHuU&t=41s This is the fastest way to be productive: clone, install, run. No installer, no admin, no frozen build. Five minutes. | Requirement | Recommended | Notes | |---|---|---| | Python | 3.12.10 | The only version Tlamatini is fully tested on. | | OS | Windows 11 | Linux/macOS work for chat + designer; Mouser/Keyboarder are Windows-leaning. | | RAM | 16 GB+ | 32 GB comfortable for bigger embedding models. | | Disk | ~10 GB | Most is local LLM models. | | LLM server | Ollama | Default. Cloud Claude/Gemini also supported. | You do not need administrator rights for any of the steps below. Open PowerShell normally do not Run as Administrator , then: $env:OLLAMA INSTALL DIR = "$env:LOCALAPPDATA\Programs\Ollama" irm https://ollama.com/install.ps1 | iex Close the window, open a fresh PowerShell, and verify: ollama --version ollama serve leave running in its own window if it's not already up Invoke-WebRequest http://127.0.0.1:11434/api/tags -UseBasicParsing Tlamatini expects Ollama at http://127.0.0.1:11434 . ollama pull Nomic-Embed-Text:latest ollama pull glm-5:cloud ollama pull qwen3.5:cloud ollama pull gpt-oss:120b-cloud ollama pull qwen3.5:397b-cloud ollama pull llama3.2-vision:11b | Tag | Used for | |---|---| Nomic-Embed-Text:latest | RAG embeddings default — small VRAM footprint, ~600 MB resident | glm-5:cloud | Default chat + Multi-Turn unified-agent + MCP file-search | qwen3.5:cloud | Default vision Image-Interpreter | gpt-oss:120b-cloud | Several workflow-agent templates Monitor-Log, Notifier, Prompter, Summarizer, … | qwen3.5:397b-cloud | Default FlowCreator | llama3.2-vision:11b | Local vision fallback | You can substitute any tag — just edit Tlamatini/agent/config.json see §8.1 81-llm-and-unified-agent or the relevant agent's config.yaml . Optional: swap to a higher-detail embedding model.If your retrieval quality on dense, technical corpora is not good enough with the default, you can switch to qwen3-embedding:8b from theConfig → Modelsmenu inside the app or by editing embeding-model in config.json and reconnecting .Use with caution: qwen3-embedding:8b is roughly10× heavier in VRAMthan Nomic-Embed-Text:latest ~6.24 GB resident vs ~600 MB on a Q4 K M quant and will trip the embedding-memory pre-flight guard see §10 on 8 GB consumer GPUs. Pull it first with ollama pull qwen3-embedding:8b . Four of the six default model tags in §2.3 23-pull-the-default-models carry the :cloud suffix — glm-5:cloud , qwen3.5:cloud , gpt-oss:120b-cloud , and qwen3.5:397b-cloud . Those are Ollama Cloud models: they live on Ollama's servers, not on your machine, and ollama pull only registers a stub that proxies inference to the cloud. Reaching that cloud requires a logged-in Ollama account and a subscription tier that allows the workload you intend to run. The plan structure prices are deliberately omitted from this README because they change — check https://ollama.com/pricing for the current numbers : | Plan | Cloud-model access | Why it matters for Tlamatini | |---|---|---| Free | 1 cloud model concurrently, light usage. Local open-weights models are unlimited. | Enough to try a single cloud model for a one-shot chat. Not enough for Tlamatini's default config, which pins different cloud models for chat glm-5:cloud , FlowCreator qwen3.5:397b-cloud , several workflow agents gpt-oss:120b-cloud , and vision qwen3.5:cloud — so a real Multi-Turn run typically needs 2–3 cloud models loaded at once. | Pro | 3 concurrent cloud models, ~50× the Free monthly quota, access to the larger cloud-only models, ability to upload / share private models. | The realistic minimum for running Tlamatini out-of-the-box with its shipped cloud-model defaults — Multi-Turn + Exec Report + occasional Image-Interpreter calls. | Max | 10 concurrent cloud models, ~5× the Pro quota, designed for sustained heavy agentic workloads. | Recommended for long-running ACPX relays, FlowHypervisor-supervised flows, and Croner-driven unattended runs that chain many cloud calls per hour. | If you do not want to subscribe , you can run Tlamatini entirely on local open-weights models. Edit Tlamatini/agent/config.json chained-model , unified agent model , mcp file search model , flow creator model , image interpreter model and every agent config.yaml that names a :cloud tag, and swap them for a model you have pulled locally for example, llama3.1:8b , qwen2.5-coder:14b , mistral-nemo:12b . Performance and quality will scale with your GPU/CPU — Multi-Turn and ACPX both work fine on a sufficiently large local model. API keys are separate. This subscription only governs :cloud Ollama models. The ACPX runtime can additionally spawn external coding-agent CLIs that bring their own credentials Anthropic API key for claude , OpenAI key for codex , Google key for gemini , etc. — those are configured in Tlamatini/agent/config.json under acpx.agents.<id .env and are unaffected by your Ollama plan. See §5.6 56-api-key-setup-the-easy-button for the easy-button setup. Unreal MCP is not part of ACPX — it's its own MCP surface, documented in §6 6-unreal-mcp--driving-unreal-engine-5-from-tlamatini . git clone https://github.com/XAIHT/Tlamatini.git cd Tlamatini python -m venv venv Windows: venv\Scripts\activate Linux/macOS: source venv/bin/activate pip install -r requirements.txt python Tlamatini/manage.py migrate python Tlamatini/manage.py createsuperuser python Tlamatini/manage.py collectstatic --noinput python Tlamatini/manage.py runserver --noreload --noreload is important: Daphne's auto-reloader does not coexist well with the wrapped-runtime subprocess pool. The console title becomes Tlamatini and stdout/stderr are tee'd into Tlamatini/tlamatini.log truncated on every start . When debugging, tlamatini.log is the first thing to read. Open http://127.0.0.1:8000/ and log in with the superuser you just created. Then: /agent/ — the chat Part §3 3-using-the-chat-agent /agentic control panel/ — the visual designer Part §4 4-visual-workflow-designer-agentic control panel /admin/ — Django admin change passwords, manage users If you used the installer Part §7 instead of cloning, the default credentials are user / changeme . Change them at first login via /admin/ . ┌───────────────────────────────────────────────────────────────────────────────┐ │ Tlamatini Context ▼ Open in… ▼ MCPs ▼ Tools ▼ Agents ▼ Config ▼ DB ▼ │ ← top nav ├───────────────────────────────────────────────────────────────────────────────┤ │ Multi-Turn ☐ Exec Report ☐ ACPX ☐ internet ☐ Clear ⌫ │ ← four toggles ├───────────────────────────────────────────────────────────────────────────────┤ │ ┌──── chat ────────────────┐ ┌──── code canvas ────────────────┐ │ │ │ conversation history │ │ syntax-highlighted, with copy │ │ │ └──────────────────────────┘ └─────────────────────────────────┘ │ ├───────────────────────────────────────────────────────────────────────────────┤ │ Type your prompt here… Send │ └───────────────────────────────────────────────────────────────────────────────┘ The four toolbar toggles are independent. Tick whatever combination fits the task — each one is its own tutorial section below. Newer builds also expose a Config dropdown in the same navbar. Config - Models edits the most common model-name fields, and Config - URLs edits the Ollama / unified-agent / MCP endpoint values through validated dialogs instead of hand-editing JSON. The chat/canvas divider was also tightened so resizing the right-hand canvas feels more predictable during long editing sessions. The newest entry in that navbar is the DB dropdown: DB - Backup database snapshots the live SQLite file to a directory you pick, and DB - Set DB stages a db.sqlite3 file of your choice for the next session — Tlamatini swaps it in before Django opens the database, archives the previous one under DB/Older/<timestamp / , then continues normal start-up. Full walkthrough in §3.10 310-the-db-menu--backup-set-db-and-the-start-up-swap-in . Click Context in the top nav: | Menu entry | What it does | |---|---| Set directory as context | Loads a folder. Tlamatini reads every text file, splits, embeds, builds FAISS+BM25, grounds answers in your code. | Set file as context | Single-file scope. | Set canvas as context | Use the code currently shown in the canvas handy for iterative editing . | Clear context | Drops the loaded context. | Set directory as context now loads a project at any depth under the app root. The old browser showDirectoryPicker only exposed the leaf folder name, so deeply-nested projects could not be reached; it was replaced by a backend native Win32 folder picker views.pick context directory view , route pick context directory/ that returns the real absolute path. path guard.is within application root then accepts the application root or any descendant of it, and agent page init.js falls back to manual path entry on non-Windows hosts. A green banner at the top shows the current context path. If embedding runs out of memory, Tlamatini packs the source files as a fallback context — retrieval quality drops, access to your code does not. If you refresh the browser and Tlamatini restores a saved context automatically, the input now stays disabled until the contextual RAG chain has actually finished rebuilding. That closes the old "restored banner arrived before the context was really ready" race on the first load stage. Leave every checkbox unticked. Type: "Write a Python function that validates an email address with a regex. Just the function." The bot answers in one shot. Code lands in the right-hand canvas with copy/save buttons. This is the legacy chat path — fast, no tools, no internet. Tick internet when the question genuinely needs fresh web data: "What is the latest stable version of FastAPI right now?" Tlamatini classifies the prompt with a small LLM call "does this need the web?" , then DuckDuckGo-searches, summarizes the top results, and inlines the summary into the LLM's context. Leave it unticked for everything else the round-trip adds latency . This is the big one. Multi-Turn turns Tlamatini from answerer into operator : - The planner picks the relevant subset of Tlamatini's 75 Multi-Turn tools — 20 core Python tools execute command , agent starter , googler , the image-analysis pair, the chat agent run lifecycle helpers, … , 43 wrapped chat-agent tools, and 12 ACPX/Skill tools — binding at most max selected tools per request default cap: 20 . - The unified-agent loop runs up to 4096 iterations the unified agent max iterations default — call tool, see result, decide next, chain. - Wrapped sub-agents run in headless background runtimes no console pop-ups . Try this: tick Multi-Turn , send "Take a screenshot of my desktop and save it to C:\Tlamatini-test\shot.png ." Watch the chat. The LLM picks chat agent shoter , calls it with the right args, reads the JSON result, and replies "Done — saved to C:\Tlamatini-test\shot.png." Open the file. The screenshot is there. | Symptom | Fix | |---|---| | LLM says "Tool X is not available" | The planner did not bind it. Check Planner. select console lines; add matching keywords to your prompt or raise max selected tools . | | Same tool fired twice with identical args | Suppressed by the dedup guard — the second call returns "skipped — duplicate". | | 4096 iterations exhausted | You probably hit a polling loop. Use chat agent sleeper instead of busy-polling. | Multi-Turn stacks with Set-Context: the LLM reasons over your code and runs tools on the result. Below the prose answer, Tlamatini appends per-agent execution tables — one HTML table per kind of state-changing agent that fired. Each row = one real tool call + ✓/✗. Tick Multi-Turn + Exec Report and send: "Create C:\test\hello.txt with Hi from Tlamatini , then read it back and tell me its size." After the prose, you see: ─── List of File Creator Operations ─── │ Command │ ✓/✗ 1 │ filepath='C:\test\hello.txt' content='Hi …' │ ✓ ─── List of Executer Operations ─── │ Command │ ✓/✗ 1 │ type C:\test\hello.txt │ ✓ What gets a table: state-changing tools only execute command , execute file , unzip file , decompile java , every chat agent that touches the system, all five acp lifecycle tools — merged into one "List of ACPx Operations" — and invoke skill . Read-only tools Crawler, Googler, Prompter, Summarizer, File-Interpreter/Extractor, Image-Interpreter, Shoter, Sleeper, monitor , run , window present are intentionally absent. Tables persist into chat history — reload the page and they are still there. ACPX lets the chat delegate to external coding-agent CLIs running on your box. Picture it: You ─► Tlamatini chat ─► acp doctor → acp spawn claude → acp send and wait │ ▼ subprocess.Popen claude CLI / gemini / cursor / codex / qwen / … When ACPX is ticked , the planner sees the 12 ACPX/Skill tools. When unticked , those tools are filtered out — the chat behaves like legacy Multi-Turn. Implemented in agent/acpx/ init .py::filter acpx tools . Prereq: at least one external CLI on PATH . The simplest: npm install -g @anthropic-ai/claude-code claude --version Then drop your key in Tlamatini/agent/config.json or use the setup-new-acpx-key skill 56-api-key-setup-the-easy-button — much easier . Tick Multi-Turn + ACPX + Exec Report and send: "Use ACPX to spawn the claude CLI in C:/Development/Tlamatini , ask it to summarize CLAUDE.md in 5 bullet points, harvest the answer, and kill the session." You see: acp doctor always first → acp spawn agent id="claude", task=… → acp send and wait → acp kill . The 5 bullets land in the prose, and the Exec Report shows a "List of ACPx Operations" table with all four rows. ACPX deep dive in Part §5 5-acpx--external-coding-agent-clis-as-tools . When a Multi-Turn run succeeds and used at least one state-changing tool, Tlamatini renders a Create Flow button on the message header. Click → download a .flw JSON file mirroring the exact tool sequence, laid out left-to-right, ready to load in the visual designer: Starter ─► Crawler ─► File Creator ─► Ender You can re-open it in /agentic control panel/ and run it as an unattended workflow. The LLM is no longer in the loop. The button gates on four conditions: Multi-Turn was on, ≥1 mappable tool succeeded, an LLM-based classifier marked the answer SUCCESS fails open on internal error , and the user is logged in. Older Chat-created .flw files were generated almost entirely in the browser. That worked for simple chains, but it meant the browser had to remember many backend facts: - what each agent is called on disk; - which config field means "my input"; - which config field means "my output"; - which agents are special, like Ender or Parametrizer; - which values are safe to save into a portable .flw file. That is a lot of responsibility for a button. Now the browser still builds the first draft, but the backend normalizes it through the Agent Contract Registry before the file is downloaded. In plain English: Tlamatini checks the flow against the same agent rules that ACP uses to run it. What this means for you: - Repeated tools stay repeated. If Multi-Turn ran Executer five times, the flow contains five Executer nodes, not one overwritten node. - Agent names are normalized. Names like Kyber-KeyGen , kyber keygen , and Kyber Keygen are resolved to the right template. - Secrets are protected where the contract knows about them. Remote chat super-agents such as TeleTlamatini and WhatsTlamatini have credential-like fields redacted on export. - The .flw file stays portable. It does not store C:/Development/... or the installed app path beside Tlamatini.exe . If backend normalization is temporarily unavailable, the old browser generator remains as a fallback so the button does not become useless. The whole of Tlamatini — chat history, agents, Tool/MCP toggles, sessions, your user — lives in a single SQLite file. The DB dropdown gives you a safe, GUI-first way to handle that file: a read-only Backup path, a destructive-but-deferred Set DB path, and a built-in audit trail under DB/Older/ . Opens a dialog with one input — the target directory . The path is live-validated 350 ms debounce : the page asks GET /agent/check backup directory/?path=… as you type and colors the status line green / amber / red: | State | Status | Meaning | |---|---|---| | 🟢 | Directory exists. db.sqlite3 will be saved here. | Ready to back up. | | 🟠 | A filename was specified — please specify the directory only. | You typed a file path; the output is always named db.sqlite3 so it can be loaded back later. | | 🔴 | Directory does not exist. | Missing on disk. | Click Backup → Tlamatini calls POST /agent/backup db/ , resolves the live database path via settings.DATABASES 'default' 'NAME' so source / frozen behave identically , and shutil.copy2 s it to <your-dir /db.sqlite3 . The live database stays open and unchanged. The opposite direction: replace the database on the next start-up . Same dialog idiom, stricter validation. The input is the full path to a db.sqlite3 file ; the page asks GET /agent/check set db file/?path=… as you type:| State | Status | Meaning | |---|---|---| | 🟢 | File exists. It will be loaded on the next start-up. | Real db.sqlite3 with a valid SQLite header. | | 🟠 | File found, but its name is not "db.sqlite3". Tlamatini will still stage it as db.sqlite3. | Snapshot-style names db 2026-05-14.sqlite3 work — the staging step renames. | | 🟠 | Specify the full path to a db.sqlite3 file, not a directory. | You typed a directory; Set DB needs a file. | | 🔴 | The selected file does not look like a SQLite database. | First 16 bytes don't match the SQLite format 3\x00 magic. | | 🔴 | File does not exist. | Missing on disk. | Click Set → POST /agent/set db/ copies your file into <base /DB/ToLoad/db.sqlite3 where <base is the executable directory in frozen mode, the inner Django project directory in source mode . The live database is not touched — SQLite is held open by Django, so the actual replacement must wait for a process restart. Immediately after staging succeeds, the dialog is replaced by a yellow ⚠ warning panel with a single OK button: The selected database will be loaded the next time Tlamatini starts. If you want it loaded immediately, you must restart Tlamatini completely so the swap-in can run BEFORE Django opens the live database. If you click Cancel instead of Set , the staging dialog closes and nothing is written. The actual replacement lives at the very top of Tlamatini/manage.py , in apply pending db swap . It runs before any Django import so Django's SQLite connection pool is never holding a stale file descriptor at the moment of the swap: manage.py main │ ▼ apply pending db swap │ ▼ DB/ToLoad/db.sqlite3 exists? │ ├─ NO ──► return no-op, normal start-up continues │ └─ YES ──► 1 mkdir DB/Older/<YYYY-MM-DD HHMMSS / 2 shutil.move live db.sqlite3 → Older/<timestamp /db.sqlite3 3 shutil.move DB/ToLoad/db.sqlite3 → live db.sqlite3 4 return │ ▼ from django.core.management import execute from command line ← only NOW Django wakes up Three guarantees: A Reconnect from the navbar is NOT enough. The swap window is only open before the Django process opens its SQLite pool. You must fully restart Tlamatini close the console / kill the exe, then launch again . Atomic moves, no copies. Both legs use shutil.move filesystem rename when possible, copy+delete across mounts . A second launch with DB/ToLoad/ empty is automatically a no-op — no "stuck flag" to clear. Mode-correct path resolution. Frozen mode reads <exe dir /DB/ToLoad/db.sqlite3 where you can browse to it in Explorer ; source mode reads <repo /Tlamatini/DB/ToLoad/db.sqlite3 next to manage.py . The live db.sqlite3 path is computed the same way Django does — MEIPASS/db.sqlite3 under PyInstaller, <manage.py dir /db.sqlite3 in source — so the swap-in always writes to exactly the path Django will open. If anything fails inside the swap-in locked file on Windows, corrupt source, permission error , the function catches the exception, prints --- DB SWAP Skipped due to error: … to tlamatini.log , and lets Tlamatini start normally with the previous database. A bad ToLoad file must never lock you out of your own database. Every successful swap-in leaves a complete record under <base /DB/Older/<YYYY-MM-DD HHMMSS /db.sqlite3 . Because Set DB moves not copies the prior live database, this archive is the only built-in recovery path: DB/ ├─ ToLoad/ ← empty most of the time; momentary home of next-session pick │ └─ README.md └─ Older/ ├─ 2026-05-14 153022/db.sqlite3 ← was live before swap 1 ├─ 2026-05-14 164410/db.sqlite3 ← was live before swap 2 └─ README.md To roll back, drop the archived db.sqlite3 back into ToLoad/ and restart — the swap-in will archive the current live database under a fresh timestamp and promote your roll-back pick. Tlamatini never auto-deletes anything from Older/ ; prune by hand when the tree gets noisy, but remember each file is a full snapshot of chat history + agents + sessions + your user. Both directories must exist on day one the swap-in opens them with os.makedirs exist ok=True , but having them pre-seeded with docs prevents user confusion : Source / dev mode : Tlamatini/Tlamatini/DB/{ToLoad,Older}/README.md are checked into the repo. The README files are the "git keepers" — without them, git would silently drop the empty directories. Frozen mode : build.py extends its empty dirs tuple with "DB/ToLoad" and "DB/Older" . The PyInstaller post-build step creates both under dist/manage/ , the pkg.zip packager preserves them via explicit zip entries, and end-users get the tree from the very first launch. Tlamatini ships with 24 skills — markdown SKILL.md packages under agent/skills pkg/ that the LLM can invoke through invoke skill '<name ', '{...args...}' . They cover everything from the canonical acp-router pick the right external CLI for an intent and summarize compress text faithfully to setup-new-acpx-key , skill-creator , code-review senior-engineer git-diff review with an APPROVE/REQUEST CHANGES verdict , security-audit multi-scanner SAST/secret/dependency sweep and kali-pentest an authorized Kali Linux assessment runbook that drives the Kalier agent / MCP-Kali-Server , the tlamatini audit/lint/refactor helpers, and integration stubs for GitHub / Notion / Slack / Gmail / Jira / Todoist / Trello / Weather. Before 2026-05-17 the only way to interact with them was through the LLM list skills to enumerate, invoke skill to run . The ACPX-Skills navbar dropdown — added next to Agents and Config in the chat toolbar — gives you an operator-grade admin surface that does NOT require the LLM. Four entries: Opens a two-pane modal: a left-side list of all 24 skills with a green/red dot for enabled / disabled and a runtime tag and a right-side detail pane that shows the selected skill's full identity — description, runtime in-process / acpx , acpx agent if any, budgets max iterations · max seconds · max tokens , trigger keywords, requires tools and requires mcps , inputs and outputs with required-field markers , and the full markdown body. A search box at the top filters by name or description as you type. Pure read — nothing is written back. Backed by GET /agent/skills/ list payload and GET /agent/skills/<name / deep detail . Use it when you want to know what a skill actually does before you ask the LLM to call it, or when you've just authored a new SKILL.md and want to confirm it parsed correctly. A checkbox grid — one row per skill — that mirrors the existing MCPs and Agents dialogs exactly. Toggle a checkbox off, click Continue , and the row's Skill.enabled flips to false . Two consequences immediately: list skills the LLM's enumeration tool filters that skill out of its returned array. invoke skill '<name ', ... returns {"ok": false, "code": "SKILL DISABLED"} instead of running. Toggling back to enabled restores the skill. This is the right knob when a you want to hide an unfinished skill from the planner, b you don't have the API key for an integration skill e.g. notion without NOTION TOKEN and don't want the LLM to keep trying, or c you're running a demo and want a minimal tool surface. The toggle goes over the same WebSocket channel as set-mcps / set-tools / set-agents — payload encoding name=description=true/false,name=description=true/false,... . Backend handler is in consumers.py::receive and calls save skill name, enabled which touches only the enabled column. A cross-check report that catches drift between the skill catalog and the rest of the system. Sections: Missing tool dependencies — for each skill whose requires tools lists a tool that's currently disabled in the Tools dialog, lists the skill + the unmet tools. A disabled tool means the skill would fail at runtime — Diagnostics surfaces it before the LLM tries. Missing MCP dependencies — same idea against disabled Mcp rows. Unknown ACPX agents — for skills with runtime: acpx , flags any acpx agent value that isn't in the AcpAgent table typo, removed CLI, etc. . Orphan DB rows — Skill rows whose SKILL.md file no longer exists on disk. Usually a sign that someone deleted a skill directory without running Reload. Each section is collapsed when clean ✓ green and expanded with red ⚠ counts when something's wrong. Run it after editing SKILL.md files or after toggling tools/MCPs to confirm nothing is silently broken. Backed by GET /agent/skills/ /diagnostics/ — pure read, no writes. A single-click button that re-runs the registry boot pipeline: rescan agent/skills pkg/ , refresh every Skill DB row's metadata description, runtime, frontmatter json, body sha256 , prune any DB row whose SKILL.md is gone. The user-toggled enabled field is preserved across reload. Use this after you've authored or edited a SKILL.md on disk — no server restart needed. The success toast tells you the new skill count. By design, the Skill DB table stays at "enumeration + enable/disable" only, exactly the way the Tool and Mcp tables work. Per-skill permissions filesystem read/write globs, allowed shell commands, network deny/allow , budgets max iterations / max seconds / max tokens , and the skill's body all live in the SKILL.md frontmatter on disk and are the only source of truth. The admin UI deliberately does NOT let you override them from the browser — if you want to change a permission, edit the SKILL.md and click Reload. This keeps git diff honest: every behavioural change to a skill shows up in a file, not in a database row that the next backup would silently archive. - HTTP endpoints: agent/views.py list skills view , skill detail view , reload skills view , skills diagnostics view — wired in agent/urls.py . - WebSocket toggle: agent/consumers.py::receive set-skills branch → save skill name, enabled . The connect path also calls skill establishment for every row so the frontend's skills = cache hydrates on session start, mirroring how tools and agents hydrate. - Tool-surface gating: agent/acpx/tools.py:: disabled skill names — fails open on DB exception so a broken admin layer never silently hides skills. - Frontend dialogs: agent/static/agent/js/skills dialog.js the Configure / Browse / Diagnostics / Reload dialogs + agent/static/agent/css/skills dialog.css . - Coverage: 14 tests in agent/tests.py SkillsAdminEndpointTests , SkillsToolSurfaceGatingTests , SkillsNavbarTemplateContractTests . Windower is the desktop window manager of the chat surface — the third member of the desktop-UI trio: where Mouser clicks inside a window and Keyboarder types into one, Windower commands the window itself . It is implemented self-contained on the Win32 API pywin32 win32gui / win32con / win32process + ctypes , porting the window-management subset of Microsoft's Windows-MCP https://github.com/CursorTouch/Windows-MCP — including the cross-process AttachThreadInput focus-transfer dance that lets a background process reliably raise a foreground window. It is Windows-only and state-changing , so it appears in the Exec Report. Tick only the Multi-Turn checkbox Windower is a normal Multi-Turn tool — it is not behind the ACPX/Skill surface, so the ACPX checkbox is not required . Then ask, for example: "Open Notepad, bring it to the front and maximize it, then tell me its size." Tlamatini will launch the app chat agent executer , confirm it is up chat agent window present , then call chat agent windower with action='maximize' and window title='Notepad' — and you will watch the window come to the foreground and fill the screen . The tool promotes its result fields action , window title , matched , match count , state , left , top , width , height to the top level of its JSON return, so the answer can report the live geometry without parsing logs. action can be any of: list enumerate every open window with its geometry + state , focus , minimize , maximize , restore , move , resize , move resize , close by title , topmost / untopmost always-on-top , or arrange snap/tile to left/right/top/bottom halves, the four quadrants, center, or full . Matching is by match mode ∈ substring default / exact / regex , with match index to pick among same-titled windows. Use Windower — not Mouser — whenever the goal is the window as a whole bring to front, tile, resize, close by title . Two ready-made showcases live in the chat Prompts dropdown the Catalog of Prompts : WINDOW SPOTLIGHT basic — maximize + list + close and WINDOW CHOREOGRAPHY medium — restore → tile left → tile right → top-left quadrant → move/resize → list → close, so a single window visibly dances around the screen . Pick one, send, and watch. Playwrighter drives a real browser Playwright — Chromium / Firefox / WebKit through a scripted, interactive, stateful flow. Where Crawler does a one-shot static fetch and the googler tool only searches, Playwrighter clicks, fills forms, waits for elements, extracts text/attributes, screenshots, asserts, and downloads — so it can log into a site, submit a multi-step form, click through a wizard, or scrape a JavaScript-rendered single-page-app behind a login. It needs Playwright installed pip install playwright && playwright install ; set headless=false to watch it drive, and alias hold open seconds=N hold open ms to keep the browser visible for N seconds after the last step before it closes — that's the "wait a few seconds before closing so I can see it" knob; just ask Tlamatini to wait and it passes it for you. Tick only the Multi-Turn checkbox Playwrighter, like Windower, is a normal Multi-Turn tool — ACPX is not required . Then ask, for example: "Open Wikipedia in a visible browser, search for ‘Nahuatl’, and tell me the first paragraph of the article." Tlamatini calls chat agent playwrighter with start url , headless='false' and hold open seconds if you asked it to keep the browser open , and the whole script as a single JSON string in the flat steps json key=value request grammar cannot express a list-of-dicts, so the script is passed as JSON and the agent json.loads it . Each step is {"action": <verb , ...} ; supported verbs are goto , click , dblclick , fill , type , press , select , check / uncheck , wait for , wait , extract text , extract attr , screenshot , assert visible , assert text , and download . The run reports status , final url , steps run , assert result , and the extracted values, so a downstream step or a Forker, on the canvas can branch on the verdict.Two ready-made showcases live in the Prompts dropdown: BROWSER SPOTLIGHT basic — open example.com with a visible browser, extract the heading, assert the link, screenshot and BROWSER WIZARD medium — a visible multi-step Wikipedia search: fill → click → wait → extract → assert → screenshot . The canvas counterpart is the visual Playwrighter node see §4 and §9.5 ; the YAML steps list is its authoring form. Kalier bridges Tlamatini to Kali Linux offensive-security tooling through the MCP-Kali-Server https://www.kali.org/tools/mcp-kali-server/ . That project runs a small Flask API server server.py on the Kali box exposing /api/command , /api/tools/<tool and /health ; Kalier talks to it directly over HTTP Python-stdlib urllib , no extra packages in the agent pool , so it is the canonical tool for AI-assisted penetration testing, recon, and CTF solving . It is state-changing , so it appears in the Exec Report. First, get the MCP-Kali-Server server.py running on your Kali machine and reachable from Tlamatini. Tlamatini is the embedded client — you no longer need Claude Desktop's client.py ; instead you set the Kali box URL once in Config ▸ URLs → Kali server Kalier the kali server url key in config.json , default http://127.0.0.1:5000 . That default already works when Kali runs in WSL2 with localhost forwarding or when you SSH-tunnel the port ssh -L 5000:localhost:5000 user@KALI IP ; for a LAN Kali box set it to http://<KALI LAN IP :5000 . See for the full zero-client walkthrough. /XAIHT/Tlamatini/blob/main/Tlamatini-Kali-Setup.md Tlamatini-Kali-Setup.md Authorized targets only — run Kalier solely against systems you own or are explicitly authorized to test engagement, lab, CTF . Tick only the Multi-Turn checkbox Kalier is a normal Multi-Turn tool — not behind the ACPX/Skill surface . Then ask, for example: "Scan 10.0.0.5 with an nmap -sCV on ports 1-1000 and summarize the open services." Tlamatini calls chat agent kalier with action='nmap' , target='10.0.0.5' , scan type='-sCV' , ports='1-1000' — and auto-injects your configured from server url kali server url , so you never repeat the Kali box address in a prompt the LLM only passes server url= explicitly to hit a different one-off box . The action field selects the capability: command any shell command on the Kali box , nmap , gobuster , dirb , nikto , sqlmap , metasploit , hydra , john , wpscan , enum4linux , or health probe the server and which tools are installed — a good first call when you are unsure the API is reachable . The tool returns the Kali tool's stdout/stderr verbatim and captures an INI SECTION KALIER block action , endpoint , subject , return code , success , timed out , server url for the Exec Report and Parametrizer.On the canvas the same capability is the visual Kalier node see §4 and §9.5 : chain Starter → Kalier nmap → Parametrizer → Kalier gobuster → Forker → Ender to build a fully unattended, branch-on-result assessment pipeline. The visual node and the chat tool share the same MCP-Kali-Server contract. STM32er bridges Tlamatini to STM32 microcontroller firmware development through the STM32 Template Project MCP https://github.com/XAIHT/STM32TemplateProjectMCP — a FastMCP server that exposes project scaffolding, build, flash, serial / SWD observation, and reset. It is state-changing it compiles firmware and writes to hardware , so it appears in the Exec Report. The visual canvas counterpart is the STM32er node see §4 and §9.5 ; both surfaces share the same MCP contract. Zero-config auto-bootstrap — you only install STM32CubeIDE + Tlamatini.With no on-disk server script configured the new default , STM32erdownloads the MCPfrom its git repo a shallow git clone , or a GitHub-zip fallback when git is absent into a per-user cache %LOCALAPPDATA%/Tlamatini/STM32TemplateProjectMCP ,pip-installs its deps mcp + pyserial if they are missing, andvalidatesthe server — all on first use. Nothing to clone by hand, no path to set. A bootstrap action triggers this explicitly; auto bootstrap default true does it lazily before the first real action. ⚠️ Critical-mission safety preflight.Before it compiles or flashes anything, STM32er runs a validate preflight that checks the environment: arm-none-eabi-gcc , STM32CubeIDE, make / cmake , STM32 Programmer CLI , the ST-LINK USB driver,a positively-confirmed connected ST-LINK probe, and the target device family. If the environment is wrong — or the request would target the wrong STM32 family — STM32errefusesrather than producing or flashing mis-targeted firmware. Hardware isconditional: compile-only actions build , list artifacts , clean , create project , write source needno board; hardware actions flash , erase , reset , serial , SWD reads, live requirea connected ST-LINK. The bundled MCP template isSTM32F407VG-specific, so a cross- STM32F -family device mismatch is refused a multi-family MCP fork is future work . Tick only the Multi-Turn checkbox STM32er is a normal Multi-Turn tool — not behind the ACPX/Skill surface . Then ask, for example: "Scaffold a blinky project for the STM32F407, build it, and flash it to the connected board." Tlamatini calls chat agent stm32er — bootstrapping the MCP if needed, running the safety preflight, then driving the build and flash. The action field selects one of 23 MCP tools project scaffold / build / flash / erase / reset / serial / SWD / observe / … , 2 composites serial session , live monitor , or 2 meta-actions bootstrap , validate . The tool captures an INI SECTION STM32ER block for the Exec Report and Parametrizer.On the canvas the same capability is the visual STM32er node: chain Starter → STM32er validate → Forker → STM32er build → STM32er flash → STM32er serial session → Ender to build a fully unattended, validate-gated firmware pipeline. Three ready-made catalog demos 35-tutorial-the-multi-turn-toggle ship in migration 0103 : STM32 GENESIS bootstrap + validate + compile, no board needed , STM32 BLINKY validate + build + flash , and STM32 HIL OBSERVATORY a validate-gated real-hardware flash + SWD + serial + reset . The zero-config end-to-end path download → build → flash → reset is verified on a real STM32F407G-DISC1 , with 122 automated tests in agent/test stm32er agent.py . 📟 Serial output on a Discovery board needs a wire — the VCP is not bridged to the MCU's UART.This matters specifically for the3rd STM32er demo, STM32 HIL OBSERVATORY, whose serial session step reads the firmware's BOOT tlamatini hil count=… banner. The on-board ST-LINK on theSTM32F4-Discovery family including the STM32F407G-DISC1 provides debug SWD but —unlike ST— doesNucleoboardsnotinternally route its USBVirtual COM Portto any of the target STM32F407's USART pins. A firmware that prints overUSART2 PA2 = TX, PA3 = RX therefore showsnothingon the ST-LINK VCP regardless of baud or timeout: on the PCB those bytes have nowhere to go. To actually read that stream you mustbridge the port yourself with an external USB-to-UART USB-TTL adapter— cross-wire adapterRX ← PA2, adapterTX → PA3,GND ↔ GND— and point serial session atthat adapter'sCOM port not the ST-LINK VCP . No wiring is needed for the demo'sprimaryhardware proof: the live monitor step samples the live g blink count counter from the running MCU over theSWD debug channel, so it works on a bare, unwired board — which is exactly why STM32er treats anempty VCP read on a Discovery board as, and why the HIL demo proves the firmware is alive over SWD first and treats the serial banner as a bonus.expected, not a failure The chat is great for one-off tasks. The designer is for jobs you want scheduled , unattended , or identically reproducible . ┌────────────────────────────────────────────────────────────────────────┐ │ ▶ Start ⏸ Pause ⏹ Stop ⚠ Hypervisor 💾 Save 📂 Load ✓ Validate │ ├──────────────────┬─────────────────────────────────────────────────────┤ │ Sidebar │ │ │ ─ Control │ │ │ Starter, Ender │ CANVAS canvas-content │ │ ─ Routing │ draggable agents, typed connections, │ │ Forker, Asker │ green-running / red-down / yellow-paused │ │ ─ Logic Gates │ LEDs │ │ AND OR Barrier │ │ │ ─ Action / etc. │ │ └──────────────────┴─────────────────────────────────────────────────────┘ - The canvas scrolls : viewport is submonitor-container , content layer is canvas-content . New canvas-level features should be children of canvas-content . Connections are typed : green = "start the target after this finishes" target agents , blue = "monitor this source's log" source agents . Double-click an agent to edit its config. Right-click for description / log / explore-dir / open-cmd / restart. Goal: run a shell command, take a screenshot, end. - Drag Starter onto the canvas top-left . - Drag Executer to its right. - Drag Shoter further right. - Drag Ender at the far right. - Connect: Starter → Executer → Shoter → Ender drag from the right edge of one to the left edge of the next . - Double-click Executer , set command to dir C:\ or ls /tmp . - Double-click Shoter , set output dir to a writable folder. - Leave Ender wiring to Tlamatini. Validate/Start will calculate Ender's target agents kill list from the arrows. - Click ✓ Validate — Tlamatini compiles the visible canvas, then runs structural checks no orphans, no self-connections, terminal agents reachable . - Click ▶ Start . LEDs go green, then gray. Open output dir — there's a screenshot. 💾 Save — pick a name. You get a JSON file with positions, configs, and connections. Distribute to colleagues; they 📂 Load the same file and run the same flow. .flw is also what the chat's Create Flow button emits. A .flw file is meant to describe the idea of the flow , not the exact machine it was created on. A good .flw says: - "There is a Starter here." - "There is an Executer there." - "Starter connects to Executer." - "Executer uses this script." It should not say: - "This flow only works from C:/Development/Tlamatini/... ." - "This flow only works from the install folder on Angel's PC." - "This Parametrizer mapping exists somewhere in a temporary pool directory, good luck." Saved flows now carry a small schemaVersion plus an artifacts section. The most important artifact today is Parametrizer mappings. When you save a flow with a Parametrizer, Tlamatini keeps the mapping in the .flw . When you load the flow later, Tlamatini recreates interconnection-scheme.csv for that Parametrizer in the current session pool. For a beginner, the practical rule is simple: if you configured Parametrizer with the mapping dialog, Save/Load should remember that mapping. This is the most important reliability change in the visual designer. Before, Validate mostly read whatever agent configs already existed in the pool directory. That could become stale: - You drag nodes around. - You load a .flw . - You edit a config. - You reconnect an edge. - The pool directory still contains an older config.yaml . - Validate or Start reads that older file and acts confused. Now ACP takes a fresh snapshot of the canvas before validation and start. The snapshot includes: - every visible node; - each node's position; - every connection; - input and output slot numbers; - current in-browser config; - Parametrizer mappings. The backend then compiles that snapshot into real pool config.yaml files using the Agent Contract Registry. In beginner terms: the picture on the screen becomes the source of truth. Another important nuance: if you opened an agent dialog and manually edited wiring-sensitive fields such as source agents or an Ender kill list, those dialog edits now survive compilation. Canvas edges still contribute their live connections, but a deliberate dialog override is no longer silently discarded by Validate or Start. What happens when you click ✓ Validate : - Browser captures the live canvas. - Backend compiles it in dry-run mode. - Frontend validates the compiled configs. - Nothing is written to disk just for validation. What happens when you click ▶ Start : - Browser captures the live canvas. - Backend compiles it in write mode. - Pool folders/configs are updated. - Logs are cleared. - Starter agents launch. This removes a whole class of "I swear I connected it correctly, why is it running the old thing?" problems. | Button | What happens | |---|---| ⏸ Pause | Saves running agents into paused agents.reanim , kills them, leaves logs and reanim state files intact. LEDs go yellow. | ▶ Resume after pause | Reanimates each saved agent with AGENT REANIMATED=1 . Each agent reads its reanim files and continues from where it stopped. | ⏹ Stop | Hard stop. Ender runs termination logic; reanimation files are cleared. | This is why long-running workflows Crawler scraping 10k URLs, Parametrizer iterating segments survive pauses. Stop is also safer in mixed flows now: the ACP cleanup path is better at terminating leftover session processes before the next run begins, so partially mixed ACP sessions are less likely to leave orphaned agents behind. Click ⚠ Hypervisor — a system FlowHypervisor agent starts watching every running agent. It is an LLM that reads each agent's log, builds an NxN connection matrix from the canvas wiring, and emits exactly OK or . If it raises, the browser pops an alert. Add custom rules to ATTENTION NEEDED { explanation } user instructions in its config.Drag FlowCreator , double-click, and type a natural-language objective: "Every hour, crawl our status page; if it shows ERROR, email the on-call engineer." Click Generate . FlowCreator reads agentic skill.md its design playbook , produces a JSON flow description, and renders agents + connections onto the canvas. Tweak and run. Tlamatini agents communicate through log files and config.yaml . Parametrizer is the bridge: it reads structured segments from a source agent's log, injects mapped values into a target agent's config.yaml , runs the target, restores the config, advances the cursor, repeats.The unified output format every Parametrizer-friendly agent emits: INI SECTION <AGENT TYPE <<< key1: value1 key2: value2 multi-line body content becomes 'response body' END SECTION <AGENT TYPE 25 source agents support this format: Apirer, Gitter, Kuberneter, Crawler, Summarizer, File-Interpreter, Image-Interpreter, File-Extractor, Prompter, FlowCreator, Kyber-KeyGen/Cipher/DeCipher, Gatewayer, Gateway-Relayer, Googler, Playwrighter , ACPXer , Shoter, Mouser, Windower , Unrealer , Reviewer , Analyzer , Kalier . Canonical example: Apirer ─► Parametrizer ─► Kyber-Cipher Apirer hits 3 endpoints → 3 INI SECTION APIRER<<< blocks → Parametrizer maps response body → buffer → Kyber-Cipher runs 3 times, encrypting each body. No manual config editing. Pause-safe. Single-lane queue. The mapping dialog is now part of normal flow persistence: - Connect exactly one source into Parametrizer. - Connect Parametrizer to exactly one target. - Double-click Parametrizer. - Click a source field on the left. - Click a target config field or target marker on the right. - Save mappings. - Save the .flw . When the .flw is loaded later, Tlamatini restores the mappings and writes the Parametrizer's interconnection-scheme.csv again. You do not need to remember which pool directory had the CSV. One limitation is intentional: one Parametrizer is a single-lane queue from one source to one target. If one API response must feed Emailer and File-Creator, use two Parametrizers. Two trigger modes: | Mode | When | |---|---| HTTP webhook | CI server, SaaS callback, cron, curl, internal portal — anything that POSTs. Auth: bearer / hmac / none . Validates → dedups → queues → starts target agents . | Folder-drop watcher | Industrial / IoT — sensor writes JSON to a shared folder. Gatewayer polls, archives, fires. | Pending events survive crashes via reanim queue.json . To accept GitHub-style webhooks which sign only the body , put the bundled Gateway-Relayer in front. ACPX = Agent Communication Protocol eXtension. It spawns external coding-agent CLIs as out-of-process child processes, talks to them over stdin/stdout, persists the conversation as NDJSON transcripts, and brokers them to the chat LLM as 12 native tools. It is a Python port of OpenClaw's ACPX plugin — agent id mapping, permissionMode vocabulary, and SKILL.md frontmatter all match verbatim. Defined in agent/acpx/agent registry.py::DEFAULT ACP AGENTS . User overrides go in config.json under acpx.agents.<id . agent id | Default command | Transport | Prompt form | |---|---|---|---| claude | claude | oneshot-prompt | claude -p "<task " | codex | codex | oneshot-prompt | codex exec "<task " | cursor | cursor-agent | oneshot-prompt | cursor-agent -p "<task " | gemini | gemini | oneshot-prompt | gemini -p "<task " | qwen | qwen-code | oneshot-prompt | qwen-code -p "<task " | tlamatini | python -m agent.acpx.self acp server | json-acp | stdin envelope | kiro / kimi / iflow / kilocode / opencode / pi / droid / copilot | own command | tui-repl | stdin | Transport modes: — fresh process per turn; prompt is a CLI arg; stdin closes; stdout captured to EOF. The oneshot-prompt only transport that reliably captures TUI agents on Windows TUI CLIs detect a piped stdout and refuse to flush in long-lived mode .— child speaks one JSON envelope per turn, ends with json-acp {"done": true} .— long-lived REPL; transport-aware idle rule fires after tui-repl startup grace + idle seconds even with zero events a silent TUI is, by definition, finished . All return JSON envelopes. Failures: {"ok": false, "reason": "...", "code": "..."} . | Tool | What it does | |---|---| acp doctor | Health probe + per-agent enumeration with resolvable and cli version . Always call first. | list acp agents | Cheap enumeration without the version probe. | acp spawn agent id, task, … | Spawn child. Returns session id , transport , transcript path , events . TUI agents return sub-second. | acp send session id, text, … | Send a follow-up turn. | acp send and wait session id, text, until idle seconds=10, max wait seconds=180 | Send and block until child settles. Prefer this for "wait for the full answer". | acp kill session id | Terminate. Returns transcript path so Exec Report can cite it. | acp transcript session id, max chars, direction | Read the on-disk NDJSON transcript. | acp session status session id | {alive, pid, transcript size, last event at, closed} . | acp list sessions | Enumerate live sessions. | acp relay session id src, session id dst, … | Single-call hand-off — replaces transcript→string→send. | invoke skill skill name, args json | Run a SKILL.md package inside SkillHarness . | list skills filter keywords | List registered skills. | 24 seed skills live under agent/skills pkg/ acp-router, summarize, setup-new-acpx-key, skill-creator, code-review, security-audit, kali-pentest, 8× tlamatini- maintenance helpers, plus OpenClaw-format ports for github / gmail / slack / jira / notion / todoist / trello / weather . Tick Multi-Turn + ACPX + Exec Report and send: "Spawn claude in C:/Development/Tlamatini , ask it to list the top-level files, harvest the answer, and kill the session." Expected tool sequence: acp doctor → acp spawn agent id="claude", task="list top-level files" → acp send and wait session id, "..." → acp kill session id "Spawn claude in this dir, ask it to draft a refactor of worker.py . Spawn gemini, relay claude's answer to it, ask gemini to critique. Kill both." Expected sequence: acp doctor → acp spawn claude, draft task → acp send and wait session a, … → acp spawn gemini, critique template → acp relay session a, session b ONE call — transform=last assistant text → acp kill session a → acp kill session b Without acp relay , that hand-off is three calls acp transcript → string-manipulate → acp send . Always prefer the dedicated tool. Two layers exist in config.json : { "ANTHROPIC API KEY": "sk-ant-...", // Layer 1: Tlamatini's own cloud calls "GEMINI API KEY": "AIza...", "acpx": { "agents": { "claude": { "env": { "ANTHROPIC API KEY": "sk-ant-..." } }, // Layer 2: spawned child env "gemini": { "env": { "GEMINI API KEY": "AIza...", "GOOGLE API KEY": "AIza..." } }, "codex": { "env": { "OPENAI API KEY": "sk-..." } }, "qwen": { "env": { "DASHSCOPE API KEY": "sk-..." } } } } } Merge order at spawn: { os.environ, spec.env} — explicit per-agent env wins over an exported shell variable. Easier path — invoke the setup-new-acpx-key skill from chat Multi-Turn + ACPX ticked : "Use invoke skill with setup-new-acpx-key to register my Anthropic key for the claude agent id." paste the key The skill writes data.keys , patches both config.json layers, optionally extends regen secrets.py , and verifies via acp doctor . Security: config.json is git-tracked. Use python regen secrets.py --mode push-able to swap real keys for placeholders before commit; --mode keyed restores from data.keys gitignored . Never commit data.keys . ACPXer is the canvas-facing version of the 12 LLM-facing tools. One ACPXer node = one full ACPX session lifecycle. It is self-contained — does NOT import agent.acpx — because pool subprocesses can't import agent. . Mirrors the runtime's transport-aware drain inline ~120 lines , writes byte-identical NDJSON transcripts, and emits Parametrizer-compatible INI SECTION ACPXER<<< blocks. Canonical visual relay flow: Starter → ACPXer claude → Parametrizer → ACPXer gemini → Parametrizer → ACPXer cursor → File-Creator → Ender Three different LLMs argue back and forth, fully visual, fully unattended. The Unrealer agent 62 in the catalog lets Tlamatini drive a live Unreal Engine 5 editor through the Unreal MCP plugin's TCP socket protocol. You spawn a chat agent unrealer call from Multi-Turn or drop an Unrealer node on the visual canvas; Tlamatini opens a TCP connection to 127.0.0.1:55557 , sends one JSON command {"type": <verb , "params": {...}} , captures the engine's JSON response into an INI SECTION UNREALER<<< block, and triggers downstream agents. Because the agent forwards whatever command + params you give it, the catalog is exactly whatever your connected plugin build exposes — from the base 28-command upstream release up to the 53-command, nine-category extended surface actor manipulation incl. viewport screenshots, Blueprint creation and graph wiring, input mappings, UMG widget building, in-editor Python/console execution, level I/O, asset import, and material authoring shipped by Tlamatini's own plugin fork, the Unreal Engine MCP modified specifically for this system — see §6.2 — without you ever leaving the chat or the canvas. XAIHT/XaihtUnrealEngineMCP Unreal MCP is an open-source UE5 plugin Model Context Protocol over a TCP socket that runs inside the Unreal Editor process and accepts one JSON command per TCP connection. Each command names a verb spawn actor , create blueprint , compile blueprint , add widget to viewport , … and a dictionary of parameters; the plugin schedules the work onto UE5's game thread, executes it, and writes a JSON response back over the same socket before closing it. The wire shape is small — {"type": <command , "params": {...}} going in, {"status": "ok"|"error", "result": {...}} or {"success": false, "error": "..."} coming back — and is identical across every documented command. Tlamatini does not embed or compile the plugin. It is a client of whatever UE5 instance the user has already started. The engine must be open, the plugin must be enabled, and its in-engine listener must be bound to 127.0.0.1:55557 the default — configurable per-call via host / port . Tlamatini contributes the calling side: one wrapped Multi-Turn tool, one visual canvas node, one Agent Contract entry, one Exec Report row family, and one Parametrizer source mapping — all built around the same UnrealConnection adapter at agent/agents/unrealer/unrealer.py . Recommended — Tlamatini's own extended fork. The plugin Tlamatini is built and tested against is the Unreal Engine MCP modified specifically for this system : Repository: https://github.com/XAIHT/XaihtUnrealEngineMCP.git What it is: the canonical chongdashu/unreal-mcp plugin forked and extended for Tlamatini. It ships the full 53-command, nine-category surface this chapter documents — the base editor / blueprint / node / project / umg verbs plus the System / Level / Asset / Material families and the newer take screenshot / focus viewport / set pawn properties / find blueprint nodes verbs. Plugin folder name: UnrealMCP Default plugin TCP port: 55557 on 127.0.0.1 Supported UE versions: Unreal Engine 5.5+ It speaks the identical wire protocol on the identical port as every other build below, so it is a drop-in: Tlamatini's UnrealConnection adapter needs no client-side changes to use it. Install this one if you want the System / Level / Asset / Material families that the seeded demos idPrompt 60/61/62 §6.5 exercise. Upstream base. The XAIHT fork is built on the canonical reference implementation Tlamatini's UnrealConnection adapter mirrors verbatim: Repository: https://github.com/chongdashu/unreal-mcp License: MIT Supported UE versions: Unreal Engine 5.5+ If you only ever need the base 28-command surface editor / blueprint / node / project / umg , the upstream is enough on its own. Equivalent community forks. Two other forks ship the same wire protocol on the same port; either works with Tlamatini's Unrealer with no client changes : https://github.com/CrispyW0nton/Unreal-MCP-Ghost https://github.com/gingerol/vhcilab-unreal-engine-mcp Pick the build that matches your UE5 version and your team's licensing comfort. If you fork the plugin to add a new command verb, your fork is automatically usable from Tlamatini — there is no client-side allow-list of verbs the wrapped tool forwards any command + params pair verbatim . The plugin is a per-project install not engine-wide . Steps: Clone or download the plugin — the recommendedfork from §6.2, or any compatible build only the XAIHT/XaihtUnrealEngineMCP MCPGameProject/Plugins/UnrealMCP folder matters — different forks may name the folder slightly differently; rename to UnrealMCP if needed . Drop the folder into your project's Plugins/ directory so the final path is <YourProject /Plugins/UnrealMCP/UnrealMCP.uplugin . Create the Plugins/ folder at the project root if it does not exist. Open the project in UE5. The editor will detect the new plugin and offer to rebuild it for your engine version — accept. If you opened a Blueprint-only project, you will be prompted to install Visual Studio Build Tools / Xcode command-line tools first, since the plugin is C++. Enable the plugin via Edit → Plugins → search "UnrealMCP" → tick Enabled . Restart the editor. Confirm the listener is bound. With the editor running, open the Output Log Window → Developer Tools → Output Log and look for a line such as LogTemp: UnrealMCP listening on 127.0.0.1:55557 . That line is your green light: the plugin is now waiting for JSON commands on the loopback interface. You do not need to press Play PIE .The plugin listens ateditorlevel — actor manipulation, Blueprint creation, widget construction, etc. all work against the open project even when PIE is stopped. Some UMG operations add widget to viewport physically render only after the user enters PIE, but the build steps are queued correctly either way. The Unrealer agent forwards whatever command + params you pass it, so the exact catalog is whatever your connected plugin build exposes — there is no client-side allow-list of verbs . The canonical chongdashu/unreal-mcp release ships 28 commands across 5 categories rows marked base below ; plugin builds that add the System / Level / Asset / Material command handlers — such as Tlamatini's own extended fork XAIHT/XaihtUnrealEngineMCP https://github.com/XAIHT/XaihtUnrealEngineMCP.git §6.2 — bring the total to 53 commands across 9 categories : | Category | Commands | Tier | |---|---|---| editor | get actors in level , find actors by name , spawn actor , create actor , delete actor , set actor transform , get actor properties , set actor property , spawn blueprint actor , focus viewport , take screenshot | base + focus viewport / take screenshot | blueprint | create blueprint , add component to blueprint , set static mesh properties , set component property , set physics properties , compile blueprint , set blueprint property , set pawn properties | base + set pawn properties | node | add blueprint event node , add blueprint input action node , add blueprint function node , connect blueprint nodes , add blueprint variable , find blueprint nodes , add blueprint get self component reference , add blueprint self reference | base + find blueprint nodes | project | create input mapping | base | umg | create umg widget blueprint , add text block to widget , add button to widget , bind widget event , add widget to viewport , set text block binding | base | system | execute python , execute console command , get class info , list assets | extended | level | open level , save current level , save all , new level , get current level | extended | asset | import asset , duplicate asset , rename asset , delete asset , save asset , create folder | extended | material | create material , create material instance , set material parameter , assign material | extended | execute python is the universal escape hatch — it runs an arbitrary Python script inside the editor, so anything in UE5's unreal Python API Niagara, Sequencer, landscape, audio, … is reachable even when no dedicated verb exists. take screenshot closes the observe→act loop: spawn or change something, then capture the viewport to verify it. Note that the plugin's headless build/cook/test tools build project , run automation tests , run macro are not part of this catalog — they shell out to UnrealEditor-Cmd as separate processes and are unreachable over the editor's TCP socket. Chain Unrealer nodes through a Parametrizer for the run macro equivalent. Param shapes vary per command e.g. spawn actor wants name + type + location + rotation ; create blueprint wants name + parent class ; set material parameter wants material + parameter + value ; import asset wants source file a disk path + destination path a /Game content path . The Unrealer agent does not validate them — it forwards them as-is, after two defensive fixups: it normalizes /Content/... content paths to /Game/... , prunes unset placeholder params, and remaps params.console command → the wire's params.command for execute console command so the console line doesn't collide with the top-level command: selector . The plugin will reply with {"status": "error", "error": "<reason "} if a param is missing or malformed, and that error lands verbatim in the INI SECTION UNREALER block so Multi-Turn / Parametrizer can branch on it. The wrapped Multi-Turn tool chat agent unrealer is the easiest way in. Tick Multi-Turn in the toolbar, leave Exec Report ticked too the Unreal calls get their own table in the answer , and send a prompt like: "Run Unreal command with command='spawn actor' and params.name='MyCube' and params.type='StaticMeshActor' and params.location= 0,0,150 ." The planner picks chat agent unrealer , the wrapped runtime spawns one short-lived unrealer.py child under agent/agents/pools/ chat runs /unrealer <seq <id / , the child opens a TCP socket to 127.0.0.1:55557 , sends the JSON command, captures the response, emits the INI SECTION UNREALER block to its log, and exits. The Multi-Turn loop reads the run's log excerpt, parses the section, and returns the full Unreal response JSON to the LLM. The LLM then sees the engine's reply and either reports it to you, branches on it, or fires the next call. The tool accepts the same overrides documented in config.yaml : host='10.0.0.5' and port=55557 to target a remote UE instance rare; the plugin binds to loopback by default and you would need to change the bind address inside the plugin or tunnel it . connect timeout=5 and read timeout=10 to widen the budgets for slow operations e.g. compile blueprint on a complex graph . Built-in demo prompts. Migration 0087 add unrealer demo prompt.py seeds a one-click demo into the Prompts table idPrompt=25 . Open the chat, click the Prompts dropdown, pick Unreal MCP End-to-End Editor Drive , and Tlamatini will execute ten guided steps spanning the base command categories — sanity-probe get actors in level , spawn a StaticMeshActor spawn actor , verify it find actors by name , scaffold a Blueprint create blueprint , add a StaticMeshComponent add component to blueprint , compile compile blueprint , spawn an instance spawn blueprint actor , build a UMG HUD widget create umg widget blueprint → add text block to widget → add button to widget → add widget to viewport — and render the result as a per-step HTML report table at the bottom of the answer. Use it as your smoke test the first time you wire the plugin up. Migration 0100 add unrealer extended demo prompts.py adds three more demos that exercise the extended System / Level / Asset / Material surface the base demo never touches, at basic → hard complexity: basic : the observe→act loop — idPrompt=60 — Unreal Snapshot get current level → spawn actor → take screenshot to C:/Temp/unreal snapshot.png → save current level . medium : content authoring — idPrompt=61 — Unreal Scene Forge list assets → create folder → create material → create material instance → set material parameter → spawn actor → assign material → take screenshot → save all . It is honest that set material parameter on a freshly-created blank material may return status: error — that is expected and recorded, not aborted. hard : the System escape hatch — idPrompt=62 — Unreal Python & Introspection execute console command via the agent's params.console command remap → get class info → list assets → execute python a multi-line script passed as a triple-quoted params.code → take screenshot . All three drive chat agent unrealer exactly like the base demo tick only Multi-Turn ; ACPX not required and require the same running editor + bound plugin listener. For unattended .flw workflows, drop the Unrealer sidebar agent onto the canvas. Each node sends exactly one Unreal command when its turn arrives. The node's config.yaml is the same one shipped under agent/agents/unrealer/config.yaml : host: 127.0.0.1 port: 55557 command: get actors in level params: name: '' type: '' location: ... the shipped config carries empty placeholders for every param across all 9 categories — editor/blueprint/node/umg/system/level/asset/material — so the Flow Compiler's dotted params.X overrides always resolve into an existing YAML leaf. Unset placeholders are pruned before the command is sent, so add/remove keys freely to match the verb you picked. connect timeout: 5 read timeout: 10 source agents: target agents: The agent emits an INI SECTION UNREALER<<< block to its log, which means Parametrizer can chain Unreal calls together . Registered source fields agent/services/agent contracts.py : host , port , command , status , error , response body . Canonical multi-step canvas pattern — create a Blueprint, compile it, spawn an instance: Starter → Unrealer create blueprint → Parametrizer → Unrealer compile blueprint → Parametrizer → Unrealer spawn blueprint actor → Ender Each Parametrizer copies the previous Unrealer's response body or a specific JSON field within it, via the Parametrizer dialog's interconnection-mapping UI into the next Unrealer's params block. Branching on status ok vs error via a Raiser between Unrealer and the next Parametrizer gives you per-step exception handling — e.g., abort to a Notifier if compile blueprint returns status: error . The unrealer.py script ~120 lines of business logic, plus the standard pool-agent boilerplate is self-contained : it does NOT import from agent.acpx , agent.services , or any other Tlamatini-internal package. Pool subprocesses run as separate Python interpreters with no sys.path back into the Django app, so the inline UnrealConnection adapter is a verbatim mirror of the upstream Unreal MCP Python client with the FastMCP plumbing stripped out . Per execution: Load , read config.yaml host , port , command , params , timeouts, and target agents . Write so the orphan-process reaper chapter 11 can track the run. agent.pid Open a fresh TCP socket to host:port with TCP NODELAY , SO KEEPALIVE , and 64 KB send/recv buffers. The Unreal MCP plugin closes the socket after each command, so the agent opens a new one per turn. Send json.dumps {"type": command, "params": params} no trailing newline and call recv until a complete JSON document has been assembled validated by attempting json.loads on the accumulated bytes after each chunk . Normalize the response shape — {"success": false, ...} from older plugin builds is rewritten into {"status": "error", "error": ...} so downstream Parametrizer / Multi-Turn code can rely on a single shape. Emit one atomic with the logging.info call INI SECTION UNREALER<<< block header: host , port , command , status , error ; body: pretty-printed Unreal JSON response, capped at 64 KiB . Single-call emission is mandatory for the parser at agent/agents/parametrizer/parametrizer.py . Trigger , so the canvas can route on the target agents even on error status field instead of relying on agent-level fail-stops. Remove and exit. agent.pid Failure modes the adapter handles gracefully each turns into {"status": "error", "error": "<reason "} plus a non-fatal log line, never an uncaught exception : Connection refused — the plugin's TCP listener is not bound editor not running, plugin not enabled, port mismatched . Socket timeout during receive — UE5's game thread is busy e.g. compile blueprint on a heavy graph and exceeded read timeout . Raise read timeout in config.yaml or in the wrapped tool call. Malformed JSON — the plugin closed mid-write; logged as an error status and downstream agents still fire. chat agent unrealer is registered in EXEC REPORT TOOLS agent/mcp agent.py under agent key="unrealer" and agent display="Unrealer" . When Exec Report is ticked alongside Multi-Turn , every Unreal call shows up as one row in a dedicated List of Unrealer Operations table at the bottom of the answer. Columns: command left-bordered with the Unrealer caption gradient , success SUCCESS / FAILURE derived from the underlying tool-call verdict — the same verdict Multi-Turn already uses for dedup and tool calls log . The table styling lives in agent/static/agent/css/agent page.css caption gradient mirrors .canvas-item.unrealer-agent in agentic control panel.css . A short pre-flight you can copy into a sticky note before any session: | Check | How | |---|---| | UE5 5.5+ open with a project loaded | File → Project → <YourProject — and leave the editor focused, not minimized to the system tray | | Plugin enabled | Edit → Plugins → UnrealMCP → Enabled = ✓ , restart of editor confirmed | | Listener bound | Output Log shows UnrealMCP listening on 127.0.0.1:55557 or your configured port | | Port not blocked | Test-NetConnection -ComputerName 127.0.0.1 -Port 55557 returns TcpTestSucceeded: True PowerShell | | Tlamatini server up | python Tlamatini/manage.py runserver --noreload shows the startup banner | Multi-Turn ticked | The toolbar checkbox to the left of Exec Report | | Tool enabled | Tools dialog in chat shows Chat-Agent-Unrealer ticked it ships ticked by default after migration 0086 add chat agent unrealer tool runs | Then run the seeded Unreal MCP End-to-End Editor Drive demo prompt idPrompt 25 as your smoke test. A clean run leaves three artifacts in your project: actor TlamatiniProbe Cube , Blueprint BP TlamatiniProbe with one spawned instance TlamatiniProbe Spawned , and widget /Game/UI/WBP TlamatiniProbeHUD . Delete them via right-click in the Content Browser when you are done. Unreal MCP is a acp doctor is not relevant here. workflow-agent surface, not the ACPX surface — the acp tools talk to external coding-agent CLIs claude, gemini, … , not to UE5. The corresponding "is the channel alive?" probe for Unrealer is to call chat agent unrealer with command='get actors in level' and check that status == 'ok' .The plugin is not listening. Check the UE5 Output Log for the status: error / Failed to connect to Unreal at 127.0.0.1:55557 . UnrealMCP listening on … line. If the line is absent, the plugin is either disabled or failed to build re-open the project; UE5 will re-prompt to rebuild . If the line is present but the connection still fails, your firewall is blocking loopback rare on Windows, but Restart-Service mpssvc and re-test if you have aggressive endpoint security .UE5's game thread is busy. Either widen Timeout receiving Unreal response . read timeout config.yaml or the wrapped-tool call , or split the work into smaller commands e.g. spawn 10 actors with 10 separate calls instead of one spawn n actors macro the plugin does not actually expose .Capitalize the status: error from a Blueprint command, but the verb seems valid. parent class exactly as UE5 expects Actor , Pawn , Character , UserWidget , … . The plugin does not auto-resolve actor → Actor . Widget appears in the Content Browser but is invisible in PIE. add widget to viewport queues the widget at editor level; you still need to press Play in the editor or call add widget to viewport from within a running PIE session to make it render. This is an Unreal MCP plugin behavior, not a Tlamatini bug. The Output Log shows the plugin received the command but nothing happened in the level. Most often: an actor spawn at a coordinate inside another object's collision volume. UE5 silently fails the spawn. Raise params.location by 0, 0, 150 and retry. A second instance of UE5 is bound to the same port. Only one UnrealMCP listener can bind to 127.0.0.1:55557 per host. Close the second editor instance, or configure each instance to bind to a different port and pass port=<n per Unrealer call. For the full debugging trail: pool-agent log lives at <pool /unrealer <n /unrealer <n .log ; chat-wrapped runs land under agent/agents/pools/ chat runs /unrealer <seq <id /unrealer <seq <id .log . Both contain the outbound JSON command and the inbound Unreal response verbatim. For shipping a one-click Windows installer to end users. build.py ──► build uninstaller.py ──► build installer.py │ │ │ ▼ ▼ ▼ pkg.zip Uninstaller.exe dist/Tlamatini Release/ python build.py Installs deps, runs collectstatic , executes PyInstaller, copies required payloads including README.md , the self-knowledge map Tlamatini.md , and bundled jd-cli/ , runs migrations, creates the default user user / changeme , renames the exe to Tlamatini.exe , copies all 68 agent templates, bundles support scripts register flw.ps1 , CreateShortcut.ps1 , Tlamatini.ps1 , Tlamatini.ico , and zips it all into pkg.zip . build.py is strict: missing README.md , missing jd-cli/ , or missing jd-cli.bat causes a non-zero exit. Self-modify builds. Add the --self-modify flag to ship Tlamatini's own source tree inside the distribution: python build.py --self-modify When the flag is present self modify = "--self-modify" in sys.argv , the build copies Tlamatini/agent/TlamatiniSourceCode/ recursively to the install root next to the exe, so it resolves like prompt.pmt / config.json / Tlamatini.md , and Tlamatini can read, inspect, and modify her own code at runtime. Without the flag the directory is omitted entirely. The build prints Self-modify build : YES or no so you can confirm which kind of build you produced. See §9.6 96-self-knowledge--self-modification for how the LLM uses it. python build uninstaller.py Builds uninstall.py into a single --onefile Tkinter exe. Output: Uninstaller.exe at the project root. python build installer.py Requires pkg.zip and Uninstaller.exe . Builds install.py with --onedir --windowed and a splash screen, copies pkg.zip and Uninstaller.exe into dist/Installer/ , and assembles dist/Tlamatini Release/ with SHA-256 verification. The final distributable is dist/Tlamatini Release/ — zip the folder, share it. - Tkinter GUI to choose installation directory no admin needed . - Extracts pkg.zip into <install path /Tlamatini/ . - Locks agent venv permissions. - Writes config.json . - Copies Uninstaller.exe . - Creates desktop and Start Menu shortcuts Tlamatini.lnk — falls back to user-scoped paths under restrictive Group Policies . - Registers .flw to open with Tlamatini. - Cleans the PyInstaller bundle path from helper subprocess environments. Frozen mode resolves config.json from the executable directory or CONFIG PATH env var . Template-agent discovery uses <install dir /agents in frozen mode and Tlamatini/agent/agents/ in source mode. resolve python executable tries PYTHON HOME → bundled python.exe → PATH. Tlamatini has two operational modes: | Mode | What it means | Where agent templates live | |---|---|---| Source / Not-Frozen | You run python Tlamatini/manage.py runserver --noreload from a cloned repo. | Tlamatini/agent/agents/ | Frozen / Installed | You run the packaged Tlamatini.exe from the installer. | <install dir /agents/ | The new Flow Compiler was built to respect both modes. It does not assume your repo is at C:/Development/Tlamatini , and it does not assume the installed app lives in a specific Program Files folder. The compiler asks Tlamatini at runtime: - "Am I frozen?" - "Where are the agent templates?" - "Where is this user's session pool?" - "Which agent contract applies to this node?" Then it writes only into the current pool: agents/pools/<session id /<agent name n /config.yaml That path exists in both modes. In source mode it is under the repo's Tlamatini/agent/agents/pools/ . In frozen mode it is under the installed app's agents/pools/ . For users, the takeaway is simpler: a .flw saved in source mode should load in an installed build, and a .flw saved in an installed build should load back in source mode. | Mode | Resolution order | |---|---| | Source | Tlamatini/agent/config.json | | Frozen | <install-dir /config.json next to the executable | | Both | CONFIG PATH env var wins over both | { "embeding-model": "Nomic-Embed-Text:latest", "chained-model": "glm-5:cloud", "ollama base url": "http://127.0.0.1:11434", "ollama token": "", "ANTHROPIC API KEY": "<ANTHROPIC API KEY goes here ", "GEMINI API KEY": "<GEMINI API KEY goes here ", "enable unified agent": true, "unified agent model": "glm-5:cloud", "unified agent base url": "http://127.0.0.1:11434", "unified agent temperature": 0.0, "unified agent max iterations": 4096, "chat agent limit runs": 100 } unified agent max iterations caps the Multi-Turn tool loop default 4096 . enable unified agent is the master switch for tool-calling. Key knobs: chunk size 3000 , chunk overlap 800 , k vector / k bm25 100 each , k fused 150 , enable bm25 , rrf k 60 , max doc chars 150000 , max context chars 250000 , and a context budget allocation map high relevance: 0.60, architecture: 0.20, related: 0.15, documentation: 0.05 . See BookOfTlamatini.md Part VII for the full schema. { "acpx": { "cwd": "C:/Development/Tlamatini", "stateDir": "C:/Users/<you /.tlamatini/acpx-state", "probeAgent": "gemini", "permissionMode": "approve-reads", "nonInteractivePermissions": "deny", "timeoutSeconds": 180, "agents": { "claude": { "command": "C:/Users/<you /AppData/Roaming/npm/claude.cmd", "env": { "ANTHROPIC API KEY": "sk-ant-..." } } } } } permissionMode ∈ approve-reads default / approve-all DANGEROUS / deny-all . The whole acpx block is optional; on first boot of an upgrade build, boot acpx appends the documented default block atomically. mcp system server port 8765 , mcp files search server port 50051 — MCP daemons. internet classifier model , web summarizer model , web context max chars — internet toggle. image interpreter model , image interpreter base url — vision. history summary , keep last turns — chat-history compression. kali server url http://127.0.0.1:5000 — the MCP-Kali-Server address auto-injected into chat agent kalier see §3.14 . stm32 mcp server script now "" — empty triggers zero-config auto-bootstrap , stm32 mcp repo url , stm32 mcp install dir — the STM32 Template Project MCP for STM32er see §3.15 . Leave stm32 mcp server script empty and STM32er downloads, installs, and validates the server itself on first use. You no longer need to hand-edit all of those values. On /agent/ , open Config - Models or Config - URLs to edit the most common runtime knobs in-place. The browser validates model strings / URLs / hosts / ports, the backend validates again, and config loader.save config updates atomically merges only the changed keys into the active config.json . The same loader path is used in source mode and frozen builds, so the chat UI and the executable stop drifting onto different config copies. Browser Chat / ACP Designer │ WebSocket ▼ Django Channels Daphne ASGI → AgentConsumer │ ├── RAG Pipeline FAISS + BM25, RRF, context budgeting, OOM fallback ├── Unified Agent Multi-Turn loop, planner, wrapped runtimes └── MCP Services System-Metrics WS, Files-Search gRPC │ ▼ LLM Backends: Ollama | Claude API | Qwen vision + ACPX Runtime → external CLIs | Layer | Responsibility | Where | |---|---|---| | 1. Persisted toggles | DB rows for Mcp / Tool / Agent UI enable/disable . | agent/models.py | | 2. Runtime MCP services | System-Metrics WebSocket + Files-Search gRPC daemons. | agent/mcp | | 3. Context fetcher chains | LCEL sidecars that inject system / files context. | agent/chain lcel.py | | 4. Main answer chains | Basic / History-aware / Unified. factory.py monkey-patches invoke . | agent/rag/chains/ | | 5. Unified-agent tools | 74 synchronous @tool functions 20 core Python + 42 wrapped chat-agent + 12 ACPX/Skill . Active only in Multi-Turn. | agent/tools.py + agent/chat agent registry.py + agent/acpx/ | Frontend toggles → WebSocket → AgentConsumer → ask rag skips prompt-shape validator → UnifiedAgentChain.invoke → filter acpx tools tools, acpx enabled → planner picks ≤20 tools capability scoring + history-aware boost → MultiTurnToolAgentExecutor: 1..4096 iterations of LLM call → tool calls → ToolMessage → Exec Report HTML appended if exec report enabled, BEFORE save message → broadcast → frontend renders, shows Create Flow if all 4 gates pass Tlamatini has two ways to create flows: - The chat can infer a flow from Multi-Turn tool calls. - The ACP canvas can build a flow by dragging agents and drawing arrows. Those two paths now meet at the same backend contract layer. This is important because flow files are not just pictures. A flow must eventually become a set of real agent folders, and every folder needs a correct config.yaml . The contract layer is intentionally small: | File | What it does | |---|---| agent/services/agent paths.py | Finds the correct agents/ and agents/pools/ folders in both source mode and frozen mode. It also normalizes names like TeleTlamatini , tele-tlamatini , and teletlamatini into the same agent type. | agent/services/agent contracts.py | Describes what each agent needs: which config fields hold incoming agents, which fields hold outgoing agents, which agents are singletons, which agents are long-running, which agents should be hidden from validation, which Parametrizer fields can be mapped, and which secrets must be redacted before export. | agent/services/flow spec.py | Converts old and new .flw shapes into one clean FlowSpec . It accepts legacy sourceIndex / targetIndex links and newer stable sourceId / targetId links. | agent/services/flow compiler.py | Converts a FlowSpec into the actual pool configs. In dry-run mode it returns the configs for validation. In write mode it updates the current session pool before Start runs. | For beginners, the rule is: the canvas or chat creates a flow idea, then the Flow Compiler turns that idea into executable agent folders. The compiler does a few quiet but important safety jobs: - It starts from each agent template's config.yaml , then merges only the node's custom settings. - It clears and rebuilds managed connection fields, so stale arrows from an old pool do not survive by accident. - It understands special agent wiring such as AND , OR , Asker , Forker , Counter , Ender , Stopper , and Cleaner . - It writes interconnection-scheme.csv for Parametrizer nodes when mappings are saved in the .flw . - It keeps FlowCreator and FlowHypervisor out of runtime validation because they are helper/control agents, not normal flow workers. - It redacts known secrets for remote chat ingress agents such as TeleTlamatini and WhatsTlamatini when chat-created flows are exported. This is the Pareto improvement: a small shared backend layer makes both major features safer. Chat-created flows and ACP-created flows now speak the same format before they touch the runtime. | Family | Members | |---|---| Control | Starter, Ender, Stopper, Cleaner, Sleeper, Croner | Routing | Raiser, Forker, Asker, Counter | Logic gates | OR, AND, Barrier | Action | Executer, Pythonxer, Prompter, Summarizer, Crawler, Googler, Playwrighter, Apirer, Gitter, Ssher, Scper, Dockerer, Kuberneter, Pser, Jenkinser, Sqler, Mongoxer, Mover, Deleter, Shoter, Mouser, Keyboarder, Windower, File-Creator, File-Interpreter, File-Extractor, Image-Interpreter, J-Decompiler, De-Compresser, Telegramer, TeleTlamatini, WhatsTlamatini, ACPXer, Unrealer, Reviewer, Analyzer, Kalier, STM32er | Cryptography | Kyber-KeyGen, Kyber-Cipher, Kyber-DeCipher CRYSTALS-Kyber post-quantum | Utility | Parametrizer, FlowBacker, Gatewayer, Gateway-Relayer, Node-Manager | Terminal / monitoring | Monitor-Log, Monitor-Netstat, Emailer, RecMailer, Notifier, Whatsapper, TelegramRX, FlowHypervisor | AI / design | FlowCreator | Per-agent details config knobs, lifecycle, naming convention, log markers : see BookOfTlamatini.md Part IV — The Tlamatini Bestiary . To add a new agent, follow Tlamatini/.agents/workflows/create new agent.md 8-step checklist . Tlamatini ships with a first-person self-knowledge map — Tlamatini/agent/Tlamatini.md — that the LLM reads as her own description of who and what she is: her two runtime modes frozen vs source, and how to tell them apart , the ports she opens 8000 for the web app, 8765 for the System-Metrics MCP, 50051 for the Files-Search MCP , her main pages, her tech stack, her full capability surface, and how she can improve herself. The audience is the LLM alone, so the file deliberately does not follow prompt.pmt 's HTML/contrast styling rules — it is a private self-reference, never rendered to users. The map is injected into the system prompt at prompt-build time. prompt.pmt carries a <self knowledge {self knowledge}</self knowledge block, and agent/rag/config.py fills it in: load self knowledge block reads Tlamatini.md , brace-escapes it { → {{ , } → }} so its code snippets cannot collide with the f-string template variables, and fails open — a missing, empty, or unreadable file degrades to a short literal notice instead of raising. The substitution happens at the single prompt-load site in load config and prompt , so it covers all four chains basic, history-aware, unified, prompt-only without adding a new input variable. Tlamatini.md is resolved from the application directory exactly like prompt.pmt and config.json the install root next to the .exe in frozen mode, Tlamatini/agent/ in source mode , and build.py ships it both via --add-data=…/Tlamatini.md;agent and by copying it to the install root so frozen resolution next to the exe works. The identity rules in prompt.pmt point the LLM at Tlamatini.md whenever a prompt concerns who or what she is, her architecture / modes / ports / pages / internals, or improving herself. Self-modification is a second, independent capability axis . The optional directory Tlamatini/agent/TlamatiniSourceCode/ , when present, contains Tlamatini's own source code so she can read, inspect, and modify herself — present means a self-able-modify build; absent means a not-self-able-modify build orthogonal to frozen vs source . The tree is bundled only when build.py is invoked with the new --self-modify flag see §7.2 72-step-1--buildpy ; without the flag it is omitted entirely. Because the directory is optional, prompt.pmt instructs the LLM to always verify the directory's presence for example, a Multi-Turn directory listing before claiming she can read or edit her own code; if it is absent she says so and falls back to the injected self-knowledge plus the docs. When you load your own project as context Context ▸ Set directory / Set file as context and then ask a generic "summarize the project / the source code / the provided context" question, the loaded context takes priorityover the always-injected self-knowledge — so Tlamatini summarizesyourcode, not herself. This is enforced by a prompt.pmt loaded-context-priority rule plus a deterministic scope header agent/rag/utils.py::prepend loaded context scope applied across all four chains. When you click Set directory as context in the Context menu, Tlamatini walks the directory, splits each file into chunks, and pushes every chunk through Ollama's embedding API to build a FAISS index. On a laptop / consumer GPU a heavy embedding model can occupy 75–95% of total VRAM by itself — and once a chat model is also resident the combined footprint exceeds available memory and the daemon thrashes RAM↔VRAM swap on every embed batch. A 30-second context-load turns into a multi-hour stall. The embedding-memory pre-flight guard Tlamatini/agent/embedding memory guard.py catches this before the embed burst starts. It runs only when an NVIDIA GPU is detected; on CPU-only / AMD / Apple Silicon hosts it is a silent no-op and the legacy load path is unchanged. The trigger case is the dev box this codebase is calibrated on: an NVIDIA GeForce RTX 4070 Laptop GPU with 8 188 MiB of VRAM. The previously-configured embedding model qwen3-embedding:8b 7.6 B parameters, Q4 K M quantization sits at ~6.24 GB resident — 77.9% of total VRAM. Add the chat model and the daemon evicts something on every embed batch. The fix is either: switch to a smaller model e.g. nomic-embed-text:v1.5 at ~0.60 GB resident, 7% saturation or accept the slow path knowingly. The guard surfaces the choice before the heavy work starts, so you can abort, swap the model in config.json , and restart Ollama — saving an hour of debugging "why is context loading frozen?". The guard is wired into agent/consumers.py::setup contextual rag chain at exactly one point: after the "loading context" banner is broadcast to the chat, before the heavy asyncio.to thread setup llm with context, … call that drives the embedding burst. The flow is: WebSocket "set-directory-as-context" ↓ consumers.py:setup contextual rag chain path only ↓ broadcast MSG AGENT LOADING CONTEXT chat bubble ↓ ► embedding memory guard.check embedding memory for directory ... │ ├─► returns None no GPU / under threshold / probe failed │ → proceed silently │ └─► returns warning dict → broadcast HTML warning chat bubble → proceed anyway informational, non-blocking ↓ asyncio.to thread setup llm with context, ... └─► OllamaEmbeddings + FAISS.from documents ... ← VRAM burst The check runs inside asyncio.to thread so a slow nvidia-smi or cold /api/show call never blocks the Channels event loop. The whole block is wrapped in try/except Exception so any unhandled probe error prints a one-line EMBED-MEM Pre-flight check skipped fail-open to tlamatini.log and the load continues — a diagnostic must never block the user . The guard reuses the already-cached nvidia-smi -L probe from agent/gpu perf.py:: has nvidia gpu introduced for the model-pinning hook . The probe runs at most once per process; subsequent calls hit the in-module cache. On CPU-only Linux/Windows, AMD GPUs, and Apple Silicon the probe returns False once at server start and every subsequent call to the guard returns None immediately — no subprocesses spawned, no HTTP calls made, no overhead. This is the portability guarantee : a fresh git pull on a no-GPU box behaves exactly as before the guard existed. The 28 dedicated no-GPU compatibility tests see 10.7 lock the contract in place. When the GPU gate passes, the guard predicts the embedding model's resident VRAM in priority order: | Tier | Source | Trigger | Accuracy | |---|---|---|---| A | GET /api/ps size vram | Model already resident in Ollama | Exact — verbatim daemon value | B | POST /api/show → parameter count × bits per weight × overhead | Model pulled but unloaded | ±5% on calibrated models | C | any probe failure | Ollama down, model not pulled, cloud model :cloud suffix | Returns None → fail-open | Tier B uses a standard llama.cpp / GGUF bits-per-weight table: | Quant | Bits/weight | Quant | Bits/weight | |---|---|---|---| F32 | 32.0 | Q4 K M | 4.83 | F16 / BF16 | 16.0 | Q4 K S | 4.58 | Q8 0 | 8.5 | Q4 0 | 4.55 | Q6 K | 6.56 | Q3 K M | 3.91 | Q5 K M | 5.69 | Q2 K | 2.96 | Unknown quants fall back to a conservative 5.0 bits/weight. The overhead multiplier accounts for KV cache + activation buffers + GGML allocator slack: for models with × 1.40 ≥ 1 B parameters large-model regime for × 2.20 sub-1 B models proportionally larger KV/buffer overhead Calibration against live measurements on the RTX 4070 Laptop: | Model | Params × bits/8 raw | Predicted × overhead | Measured resident | Error | |---|---|---|---|---| qwen3-embedding:8b Q4 K M | 4.54 GB | 6.36 GB × 1.40 | 6.24 GB | +1.9% | Nomic-Embed-Text:latest F16 | 274 MB | 603 MB × 2.20 | 600 MB | +0.5% | Tier B also pulls the embedding dimension from /api/show via any architecture-prefixed .embedding length key e.g. qwen3.embedding length=4096 , nomic-bert.embedding length=768 . Combined with a directory pre-scan that mirrors the exclusion rules of agent/rag/factory.py::CustomTextLoader , it reports a projected FAISS-index RAM size num chunks × embedding dim × 4 bytes, float32 . This is RAM, not VRAM, but useful to surface on directories with hundreds of thousands of chunks. The guard fires when predicted vram ≥ 0.80 × smallest-GPU total VRAM . Why the smallest GPU rather than the sum or the largest ? Because Ollama loads each model into a single device — using the max would silently under-report the constraint on heterogeneous multi-GPU rigs. When the threshold is crossed, the guard returns a structured dict the consumer renders as an HTML chat bubble. A real example from this dev box artificially threshold-lowered to 70% so qwen3-embed:8b trips : ⚠️ Embedding-memory warning Embedding model qwen3-embedding:8b needs ~6,378 MiB of VRAM currently resident in VRAM , which is 77.9% of the smallest GPU's total 8,188 MiB — above the safety threshold of 70%. Projected FAISS vector store RAM, not VRAM : ~28 MiB across 1,847 chunks at dim 4096. Context loading will continue, but expect slow embedding throughput or RAM↔VRAM swap. To eliminate the pressure, switch embeding-model in config.json to a smaller model e.g. nomic-embed-text:v1.5 and restart. The message is informational and non-blocking — context loading proceeds. The user picks whether to wait it out, hit Cancel, or change models. The phrasing names the exact config.json key embeding-model , with the spelling preserved from the existing codebase and a concrete alternative. | Knob | Where | Default | When to change | |---|---|---|---| | Trigger threshold | check embedding memory for directory ..., threshold= | 0.80 | Pass 0.70 on smaller GPUs 6 GB cards where 80% is already too tight. | | Large-model overhead | OVERHEAD LARGE constant | 1.40 | If a new model family proves the calibration off by 10%, recalibrate against /api/ps and bump the constant. | | Small-model overhead | OVERHEAD SMALL constant | 2.20 | Same calibration story for sub-1B models. | | Bits/weight table | QUANT BITS dict | Q4 K M=4.83 etc. | Add new entries when a future GGUF quant ships. | What the guard does NOT do, by deliberate choice: - It does not abort context loading. The warning is informational. If you want abort-on-warning behavior, wire a confirm/cancel WebSocket round-trip — the surface is described in agent page init.js near set-dir-context . - It does not estimate the chat model's VRAM. Only the embedding model is checked, because that is the model the directory-load path forces into VRAM. The chat model is handled by gpu perf.pin ollama model separately. - It does not persist warnings. Each context-load runs an independent check. - It does not call nvidia-smi on CPU-only hosts. Both gates has nvidia gpu cached and the gpu total memory bytes query short-circuit before any subprocess spawn. - It does not add new dependencies. subprocess , urllib.request , and os.walk are the only stdlib touchpoints — the same surface agent/gpu perf.py already uses. The guard ships with 49 automated tests in Tlamatini/agent/test embedding memory guard.py , split into seven SimpleTestCase classes: | Test class | Count | What it pins | |---|---|---| QuantTableTests | 2 | Known quants resolve to standard bits/weight; unknown quants fall back to the conservative default. | PredictFromShowTests | 3 | Tier-B prediction lands within calibrated bounds for both 7.6 B and 137 M reference models. | EmbeddingDimExtractionTests | 2 | The dim key is found regardless of architecture prefix qwen3. , nomic-bert. , future archs . | ChunkEstimatorTests | 4 | Directory walk honors default + user omissions, respects max chunks per file , and handles single-file mode. | GuardEntryPointTests | 8 | All entry-point branches: no-GPU, cloud, threshold gate, Tier A /api/ps , Tier B /api/show , probe failure. | FormatMessageTests | 2 | HTML renders the model name, percent, threshold, and chunk count. | NoGpuCompatibilityTests | 28 | Every no-GPU failure mode — see breakdown below. | The NoGpuCompatibilityTests class is the portability proof. Its coverage matrix: | Failure mode | Tests | |---|---| | Module import on no-GPU host has no side effects | test module imports without side effects | nvidia-smi binary missing entirely | test run cmd returns 127 for real missing binary , test total vram returns none when nvidia smi missing | nvidia-smi exists but driver unloaded | test total vram returns none when driver unloaded | nvidia-smi times out / crashes | test run cmd absorbs timeout / ... permission error / ... generic oserror | nvidia-smi returns empty or garbage output | test total vram returns none on empty output / ... on unparseable output | | Heterogeneous multi-GPU rig | test total vram picks smallest gpu in heterogeneous rig | gpu perf module missing / its probe raises | test has nvidia gpu falls back when gpu perf unimportable , test has nvidia gpu returns false when gpu perf probe raises | | Ollama daemon offline closed port | test ollama show returns none against closed port , test ollama ps returns none against closed port | | Malformed Ollama URLs / empty args | test ollama show returns none for garbage url | Model not in /api/ps | test ollama loaded vram returns none when model not in ps , ... when ps fails | | Entry on a CPU-only host | test check returns none on cpu only host | GPU detected but --query-gpu fails | test check returns none when nvidia smi query fails | | GPU detected but Ollama offline | test check returns none when ollama offline | | Pathological 0 MiB GPU reading | test check returns none when gpu zero total | Empty ollama base url in config | test check returns none for empty base url | | Deleted / nonexistent / empty path | 3× test chunk estimator + test check with nonexistent path does not crash | | Unreadable file inside the walked tree | test chunk estimator with unreadable file skips it | | Partial warning dict missing optional keys | test format warning message handles missing optional keys | Live portability proof real subprocess + real urllib | test real entry point call never raises | test real entry point call never raises is the CI gate: it makes the actual subprocess.run "nvidia-smi", ... and urlopen "http://127.0.0.1:11434/..." calls against whatever the runner offers, and asserts the return is either None or a well-formed warning dict — never an exception. The same test passes on this RTX 4070 dev box returns None because qwen3-embed sits at 77.9%, under the 80% gate and on a CPU-only CI image returns None because the GPU gate fails fast . Run them yourself: cd Tlamatini python manage.py test agent.test embedding memory guard --verbosity=2 49 tests in ~2.3 s, no DB setup, no GPU required. Tlamatini now ships a three-tier reaper Tlamatini/agent/orphan reaper.py that cleans up the console-host children every console subprocess on Windows drags behind it. Without this pass, users were occasionally seeing conhost.exe processes lingering in Task Manager with the Tlamatini icon — the icon is inherited from the parent EXE that spawned the console — and reasonably concluding that Tlamatini was leaking processes. On Windows, when a tool execute command , chat agent executer , an ACPX CLI child, an agent-pool Python subprocess, … spawns a console child, Windows allocates a conhost.exe companion to host that console. If the immediate parent dies before the OS reaps the console pair, that conhost.exe outlives Tlamatini. Two compounding causes were closed at once: The reaper itself sweeps zombies and orphaned console hosts at three lifecycle points below . Spawn sites were hardened — views.py::execute starter agent view , execute ender agent view , restart agent view , execute flowcreator view , every ACPX child in acpx/runtime.py , and a subprocess.Popen. init guard at the top of agents/ender/ender.py mirrored across every other pool agent now spawn with CREATE NO WINDOW | DETACHED PROCESS | CREATE NEW PROCESS GROUP and stdio piped to DEVNULL . No console is allocated in the first place, so no conhost.exe companion exists to orphan. | Tier | When it runs | Scope | Visibility | |---|---|---|---| Tier 1 | After every Multi-Turn tool call that may have spawned a child execute command , execute file , unzip file , decompile java , googler , agent starter/stopper/parametrizer , every chat agent , every acp . Driven by MultiTurnToolAgentExecutor. reap after tool in agent/mcp agent.py . Also fires on the tool-exception path so a crashed tool still gets cleaned up. | Dead/zombie descendants of the current PID, plus orphaned conhost.exe whose parent is gone. Pool-cmdline scan is skipped here cheap path . | Silent. Survivors accumulate on the executor for Tier 2 to surface. | Tier 2 | Once, right after the final answer is broadcast to the user. Driven by AgentConsumer. tier2 orphan sweep in agent/consumers.py . Runs in a thread so it doesn't block the WebSocket loop and merges its survivors with Tier 1's leftovers de-duped by PID . | Same as Tier 1 plus the agent-pool cmdline scan kills processes whose cmdline references agents/pools/... but are not tracked by AgentProcess / ChatAgentRun anymore . | If anything survives BOTH tiers, the consumer sends a second chat message listing every surviving name + PID pair so the user can end them manually from Task Manager. | Tier 3 | At Tlamatini.exe shutdown — AgentConfig.ready registers it on the same atexit / SIGINT / SIGBREAK path that already cleans up pools. | Full sweep self-tree + pool cmdline + console-host orphans . | Logs --- Tier-3 reaper killed=… survivors=… errors=… to tlamatini.log . Survivors are listed by name PID so a post-mortem reader can audit what refused to die. | A process is considered a "Tlamatini orphan" if any of the following hold: - It is a descendant of the current Tlamatini PID and its status is ZOMBIE / DEAD . - It is a conhost.exe / openconsole.exe whose parent PID is in our process tree, OR whose parent PID no longer exists. - Its cmdline references the agent-pool directory agents/pools/... or agents/pools/ chat runs /... but it is no longer tracked. Each candidate is escalated terminate → wait 1 s → kill via psutil ; an "unable-to-kill" outcome surfaces as a survivor, never as an exception. The reaper never raises into the caller — a cleanup that crashes the chat path would be worse than the orphans it tries to kill. Out of scope on purpose: console hosts spawned by unrelated processes a different IDE, your shell, another app's child — the parentage check keeps the sweep narrow. When Tier 2 detects survivors, the user sees a second chat bubble immediately after the main answer: ⚠ Heads-up: Tlamatini tried to clean up after this request but the following process es refused to terminate. They are most likely harmless leftovers from a tool you ran, but if you do not recognize them please end them manually from Task Manager so no Tlamatini-spawned child outlives the app: • conhost.exe — PID 18244 • python.exe — PID 19108 The rendering helper is orphan reaper.format survivors message ; it returns None so no extra message is sent when the survivor list is empty, which is the common case after the spawn-site hardening landed. - "connection refused" → ollama serve in a dedicated terminal. Check ollama base url . - Model not found → ollama list to see what's pulled. Pull the missing tag. - Remote Ollama → set ollama token for bearer auth. - Set-Context shows no green banner → check file permissions, ensure files are text not binary. - "Out of memory" during embedding → fallback mode kicks in; retrieval quality drops, files still accessible. Switch to a smaller embedding model. See chapter 10 — the embedding-memory pre-flight guard now warns you about this before the embed burst starts on GPU hosts. - Hit max doc chars → bump it. - Session says it was restored after a refresh, but the input stays disabled briefly → that is expected while the contextual RAG chain rebuilds. Wait for the ready state / spinner to clear before sending the next prompt. - Did you tick Multi-Turn ? Is enable unified agent: true ? - "Tool X is not available" → the planner did not bind X. Check Planner. select console lines, add matching keywords to your prompt, or raise max selected tools . - 4096 iterations exhausted → likely a busy-poll loop. Use chat agent sleeper / chat agent run wait instead.