{"id":47676451,"url":"https://github.com/djtony707/titan","last_synced_at":"2026-07-07T06:00:24.026Z","repository":{"id":338134872,"uuid":"1156709522","full_name":"Djtony707/TITAN","owner":"Djtony707","description":"Building TITAN — the open-source AI operating system for trusted autonomous work: agents, tools, memory, approvals, receipts, voice, mission control, and SOMA. npm i -g titan-agent","archived":false,"fork":false,"pushed_at":"2026-07-03T18:53:19.000Z","size":20061,"stargazers_count":18,"open_issues_count":14,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-07-03T20:10:47.393Z","etag":null,"topics":["agent","agent-framework","ai","ai-agents","ai-framework","amthropic","automation","autonomous-agents","claude","llm","mcp","multi-agents","nodejs","openai","orchestration","rag","self-hosted","tools","typescript","voice"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/titan-agent","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Djtony707.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORTERS.md","governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"Djtony707"}},"created_at":"2026-02-13T00:45:32.000Z","updated_at":"2026-07-03T18:12:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Djtony707/TITAN","commit_stats":null,"previous_names":["djtony707/titan"],"tags_count":81,"template":false,"template_full_name":null,"purl":"pkg:github/Djtony707/TITAN","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Djtony707%2FTITAN","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Djtony707%2FTITAN/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Djtony707%2FTITAN/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Djtony707%2FTITAN/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Djtony707","download_url":"https://codeload.github.com/Djtony707/TITAN/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Djtony707%2FTITAN/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35216572,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","agent-framework","ai","ai-agents","ai-framework","amthropic","automation","autonomous-agents","claude","llm","mcp","multi-agents","nodejs","openai","orchestration","rag","self-hosted","tools","typescript","voice"],"created_at":"2026-04-02T13:32:34.281Z","updated_at":"2026-07-07T06:00:23.967Z","avatar_url":"https://github.com/Djtony707.png","language":"TypeScript","funding_links":["https://github.com/sponsors/Djtony707"],"categories":[],"sub_categories":[],"readme":"[//]: # \"npm-text-start\"\n\n\u003e **TITAN** — A local-first AI agent framework that runs on your hardware, with your models, under your control. Spawn a team of specialists around a goal, watch them work live — step-by-step, with real file diffs — and stay in the loop without giving up control. `npm i -g titan-agent`\n\u003e [//]: # (npm-text-end)\n\n\u003cdiv align=\"center\"\u003e\n\n# TITAN\n\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/titan-logo.png\" alt=\"TITAN Logo\" width=\"240\"/\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eThe local-first AI agent framework that teaches itself, mixes councils of models, plays well with other agents — and lets you watch it work.\u003c/strong\u003e\n  \u003cbr\u003e\u003csmall\u003eYour hardware. Your models. Your control. Built in TypeScript, MIT-licensed, 40K+ lifetime installs.\u003c/small\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/titan-agent\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/titan-agent?color=blue\u0026label=npm\" alt=\"npm version\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/titan-agent\"\u003e\u003cimg src=\"https://img.shields.io/npm/dt/titan-agent?color=blue\u0026label=downloads\" alt=\"npm downloads\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/Djtony707/TITAN/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/Djtony707/TITAN?style=social\" alt=\"GitHub Stars\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/Djtony707/TITAN/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-green\" alt=\"License\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/sponsors/Djtony707\"\u003e\u003cimg src=\"https://img.shields.io/badge/sponsor-♥-ec4899\" alt=\"Sponsor\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/titan-desk.gif\" alt=\"The TITAN Living Desk — the mascot announces a self-learned skill and celebrates on the canvas\" width=\"880\"/\u003e\n  \u003cbr\u003e\u003csmall\u003e\u003cem\u003eThe Living Desk: home is a canvas, the mascot is a creature — here it announces a skill it just taught itself.\u003c/em\u003e\u003c/small\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#whats-new\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/titan-agent?color=blueviolet\u0026label=version\" alt=\"npm version\"/\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/providers-36-purple\" alt=\"36 LLM Providers\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/channels-19-orange\" alt=\"19 Channels\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/skills-~143%20loaded-teal\" alt=\"~143 skills loaded\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/WCAG-2.1%20AA-blueviolet\" alt=\"WCAG 2.1 AA\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/tests-8000%2B-green\" alt=\"8000+ tests\"/\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  ⭐ \u003ca href=\"https://github.com/Djtony707/TITAN\"\u003eStar us on GitHub\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  ♥ \u003ca href=\"https://github.com/sponsors/Djtony707\"\u003eSponsor\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  💬 \u003ca href=\"https://github.com/Djtony707/TITAN/discussions\"\u003eDiscussions\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003ca id=\"whats-new\"\u003e\u003c/a\u003e\n\n## What's new in v7.2.0 \"Conscience\" — Honesty as an Enforced Invariant\n\n**TITAN stopped being able to bluff.** Two honesty organs turn any model — local\nor cloud — into one that *verifies before it claims* and *critiques before it\nspeaks*. Flip one switch (`agent.reliabilityMode: true`) and your local model\nbehaves with the reliability discipline of a frontier model, because reliability\nis enforced in the harness, not hoped for in the prompt.\n\n- 🛡️ **Verification wall (always on):** claim you sent/posted/deleted/deployed/\n  saved something with no tool that did it → TITAN appends a visible correction.\n- 🧠 **Self-critique (Reliability Mode):** the model reviews its own draft\n  adversarially and appends honest \"on reflection\" caveats. Live-proven: a local\n  model caught its own over-precise number and a definitional conflation,\n  unprompted.\n- ⚡ **Perf:** ~19MB/turn read deleted (tail-read trajectories); every timer\n  `.unref()`'d.\n\nSee **[CHANGELOG.md](CHANGELOG.md)** for the full v7.2.0 entry.\n\n---\n\n## What's new in v7.1.0 \"Council\" — Local-First Intelligence, Together\n\n**Agents advising agents, models sized to their machines, and benchmarks you can trust.**\n\n### 🧠 `/moa` — Mixture of Agents\nAsk a **council**, not a model: N reference advisors answer in parallel (trimmed context, no tools, per-advisor timeouts), and one acting aggregator synthesizes the answer with full tool use. Advisors default to **your own local models across your own machines** — the mixture costs nothing and parallelizes across GPUs. `/moa \u003cprompt\u003e` for one answer, `/moa use \u003cpreset\u003e` for a session, presets in config.\n\n### 🌐 Works alongside Hermes Agent \u0026 OpenClaw — the MCP triangle\nTITAN's MCP server now speaks **whole-agent**: `titan_chat`, `titan_delegate_task` / `titan_task_status`, `titan_moa`, `titan_status`. One config line makes TITAN a tool inside Hermes or OpenClaw — and TITAN's MCP client consumes their servers right back. Six directed edges, all shipped surfaces, no adapters. ([docs/INTEROP.md](docs/INTEROP.md))\n\n### 📏 Context-Fit — local models become first-class\nTITAN now **learns each deployment's real context ceiling from live traffic** and sizes its toolset to fit: small-context deployments get a lean toolset instead of a fatal overflow, and every request got ~4K tokens lighter (the tool catalog shrank 5×). Strict local backends (vLLM/llama.cpp/LM Studio template quirks) are handled; gateway misroutes fail fast.\n\n**Proof, not vibes**: under the new `TITAN_BENCH=1` isolation mode, **Qwen3.6-35B-A3B NVFP4 on DGX-Spark-class hardware scores 85% through TITAN's harness — tying the RTX 5090's best local model.** Full corrected tables in [benchmarks/MODEL_COMPARISON.md](benchmarks/MODEL_COMPARISON.md).\n\n### 🛡️ Honesty as an enforced invariant (any model)\nTITAN won't let a model bluff. The **verification wall** appends a visible\ncorrection if a reply claims it *did* something (sent, posted, deleted,\ndeployed, saved) with no tool that actually did it — deterministic, always on.\nTurn on **Reliability Mode** (`agent.reliabilityMode: true` — one switch) and TITAN\nalso critiques its own draft before you see it, appending honest \"on reflection\"\ncaveats for anything it didn't verify. This is how a local model reaches\nfrontier *reliability* without frontier size — and it works on whatever brain\nyou plug in.\n\nSee **[CHANGELOG.md](CHANGELOG.md)** for the complete v7.1.0 entry.\n\n---\n\n## What's new in v7.0.0 \"Independence\" — Alive, Welcoming, Model-Agnostic\n\n**The Independence Day release** — because local-first *is* independence: your AI, your hardware, your data. Four themes: **TITAN provably teaches itself from your usage, first run takes one minute, it lives on your machine between conversations, and it runs well on any capable model.** (Connect your first model and you'll see the fireworks. 🎆)\n\n### 💪 Muscle Memory — self-improvement you can actually trust\n\nThe #1 wish across agent-framework reviews: agents that turn repeated workflows into skills *by themselves* — without the untrustworthy self-grading that plagues every attempt at it. TITAN ships it, with proof:\n\n- **It notices.** Repeat a workflow ~3 times and TITAN mines the pattern from its own task trajectories and drafts a reusable, parameterized skill with its own slash command.\n- **The replay exam.** Before you ever see a learned skill, it must **reproduce the original workflow's exact tool path against your real historical request**, verified by the deterministic eval harness. No self-praise — grounded proof. Failed drafts stay hidden.\n- **Structurally safe.** Exams replay inside a tool allowlist sandbox; workflows containing side-effectful tools (send / post / delete / deploy / …) are never mined at all; nothing ever auto-adopts.\n- **One click to adopt** → instant `/slash-command` in every channel, a savings ledger per run, and a mascot that announces what it learned. \"Not for me\" is remembered forever.\n\n### 👋 Welcome Mode — first run in about a minute\n\n- **The gateway always boots.** No Ollama, no API keys? v7.0 starts anyway and greets you — no more terminal refusal before you've ever seen the desk.\n- **The dashboard walks you in:** one-click connect when Ollama is detected (models auto-listed), or paste an Anthropic/OpenAI key, or point at any OpenAI-compatible endpoint (LiteLLM, vLLM, LM Studio, llama.cpp).\n- **No restart** — connect a model and the desk unlocks live. Chat answers with friendly setup guidance until then.\n\n### 🧠 Model-agnostic harness\n\nTITAN no longer assumes one vendor's quirks. The generic `openai_compat` provider (DeepSeek / Qwen / GLM / Kimi / MiniMax / xAI / Groq / …) now honors per-model tool-calling instead of a blind passthrough:\n\n- **Native tool-calls per vendor** via a shared **per-model capability registry** (qwen3.6, deepseek-v4, glm-5.1, kimi-k2.6, minimax, nemotron-3) used by *both* the Ollama and openai-compat paths.\n- **`forceToolUse` → `tool_choice`** per-model, plus JSON `format` (`response_format` + a 2 KB anti-truncation floor), with a guard for the DeepSeek-reasoner HTTP-400 case.\n- **Adaptive `max_tokens`** — parse a deployment's real ceiling out of a 400 and retry, so a static `maxOutput` never hard-fails a model on a constrained deployment.\n- **Deterministic system-widget gates** — \"show backup\" reliably renders the widget no matter which model is driving, instead of depending on per-model formatting adherence.\n\n\u003e TITAN is deliberately **not** tuned to one LLM. Model-fit and harness bugs are kept separate so the framework stays model-agnostic.\n\n### ♿ Accessible by design (WCAG 2.1 AA)\n\n- a11y primitives across the UI: Input / Modal / Toast / Button focus + ARIA, a skip-link and `\u003cmain\u003e` landmark, and a global focus-visible baseline.\n- A new **\"Studio\" theme** (clean neutral graphite) plus a **WCAG contrast-audit harness** that programmatically proves every theme meets AA.\n\n### 👀 Living-agents foundation — *watch it work*\n\nA session-scoped **event spine** now emits `tool:call` / `tool:result` events (with a diff for file changes) as the agent runs. On top of it:\n\n- **Live Studio** — a \"watch it work\" split-pane that shows a **step timeline**, **live file diffs**, and a **changed-files rail** as the agent operates.\n- Sessions are **URL-addressable and replayable** — share a link, scrub the timeline.\n\n*(The Live Studio ships with the timeline + diff stream + changed-files list. A live preview server, a one-click-revert button, and the round/token spine tail are on the [roadmap](#roadmap) — not in v7.0.)*\n\n### 🫀 Alive by default — the life loop\n\nTITAN doesn't just respond — it lives on your machine:\n\n- **The Heartbeat.** Every ~30 minutes TITAN checks its world and decides if ONE thing is worth telling you, unprompted — the mascot says it. Default is silence; quiet hours respected.\n- **Proactive memory.** It quietly notices durable things about you from real conversations (strict rules, never sensitive categories) — what it learns shapes every future reply and fills the plain-language **\"What I know about you\"** page.\n- **It proposes work.** When a drive is genuinely neglected, Soma files a suggestion into your approvals — shadow-rehearsed first, never auto-run. (v7.0 fixes the threshold that had made this mathematically impossible.)\n- **Real reminders, honestly kept.** \"Remind me Friday at 5pm\" actually fires — the mascot announces it at the right time. And a built-in anti-fabrication guard means TITAN can never claim it scheduled something it didn't.\n\n### 🪵 The Living Desk — home is a canvas, the mascot is a creature\n\n- **Home IS your canvas.** The \"Ask TITAN\" input is itself a widget — move it, resize it, build your desk around it. Five desk themes (incl. the new **Night Desk** dark walnut), zoomable 40–200%.\n- **The mascot wanders the desk**, goes wherever you place it, narrates work in plain English, celebrates finishes, carries your day-streak flame, and greets you with what it finished while you were away.\n- **Edit widgets by talking** — the editor's \"Ask AI\" bar rewrites a widget from a plain-English request; History undoes.\n- **Five doors, not 48** — Home · Desk · Studio · Memory · Workshop. All the power is still there, behind the Workshop door.\n\n### 🔭 Observability \u0026 tracing\n\n- Per-run **spans** (latency, tokens, cost, tools) with a live summary and **OTel export**.\n- File-backed per-run trace store at `$TITAN_HOME/traces`, served via `/api/traces`, `/api/traces/summary`, and OTel `/api/traces/export`.\n\n### 🧩 Mission Control — 4 new panels\n\n**Memory Taxonomy** (9 memory types + the drive-backed *emotional* differentiator) · **Security self-audit** (severity-grouped config findings) · **Evals dashboard** · **Observability / tracing**.\n\n### Also in v7.0\n\n- **Workflow Builder** — a dependency-free SVG **goal/subtask DAG** of any mission: nodes coloured by status, edges from `dependsOn`, layered by longest-dependency-depth, the live current subtask highlighted. Click a node for detail, or author a new workflow from a plain-English prompt. Mission decomposition now threads real dependency edges (backward-only, always-acyclic), so the DAG reflects true ordering.\n- **2 new agent skills:** `codebase_explore` (walks a repo into a structured map — entrypoints, key files, language mix, top dirs) and `delegate_agent` (orchestrates external coding agents — codex / aider / goose / gemini / opencode; **never** the `claude` CLI).\n- **8 ECC software-craft skills** (MIT, attributed), `config_audit` (config security self-audit), a spec-driven workflow (acceptance criteria recited every turn), and a named memory taxonomy (`memory_map`).\n- **SECURITY:** the Facebook Messenger webhook verifies the `X-Hub-Signature-256` HMAC (constant-time) when `FB_APP_SECRET` is set — forged POSTs are then rejected with 403. (Set the secret to enable enforcement; without it, verification is skipped.)\n- **FIX:** the agent loop-breaker could itself infinite-loop (the round counter froze) — now terminal and bounded.\n\nSee **[CHANGELOG.md](CHANGELOG.md)** for the full v7.0.0 entry and everything before it.\n\n---\n\n## See it\n\n| 👋 Welcome Mode — first run in a minute | 💪 Muscle Memory — a real learned skill |\n|---|---|\n| \u003cimg src=\"docs/assets/welcome-mode.png\" alt=\"Welcome Mode setup card over the dimmed desk\" width=\"420\"/\u003e | \u003cimg src=\"docs/assets/muscle-widget.png\" alt=\"Muscle Memory widget showing a replay-verified learned skill awaiting adoption\" width=\"420\"/\u003e |\n| *No model configured? The gateway boots anyway and walks you in.* | *An actual skill TITAN taught itself from repeated usage — exam badge and evidence included.* |\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/mascot-learned.png\" alt=\"The mascot announcing a learned skill on the desk\" width=\"880\"/\u003e\n  \u003cbr\u003e\u003csmall\u003e\u003cem\u003e“I taught myself add-widget — replay exam passed!” — proactive, and provable.\u003c/em\u003e\u003c/small\u003e\n\u003c/p\u003e\n\n---\n\n## Why TITAN\n\n- **It teaches itself — provably.** Muscle Memory turns your repeated workflows into replay-verified skills. Every learned skill passes a deterministic exam against your real usage before you see it; nothing auto-adopts. No other framework ships trustworthy self-improvement on by default.\n- **A council, not just a model.** `/moa` fans your question to advisor models across your own machines and synthesizes one sharper answer — mixture-of-agents at $0/turn.\n- **Plays well with other agents.** TITAN is an MCP tool inside Hermes/OpenClaw and consumes them right back — delegate jobs, share councils, cooperate.\n- **One-minute first run.** `npm install -g titan-agent \u0026\u0026 titan gateway` — the dashboard greets you and connects a model in about a minute. No Docker, no YAML, no config-file editing.\n- **Model-agnostic, for real.** One harness, native tool-calls per vendor, a per-model capability registry, adaptive token ceilings. Bring DeepSeek, Qwen, GLM, Kimi, MiniMax, Anthropic, OpenAI, Gemini, or anything OpenAI-compatible — the framework adapts instead of being tuned to one LLM.\n- **Local-first.** Run any model on your own hardware via Ollama, or route to any of 36 providers through one router. Switch models mid-conversation. Failed models auto-fallback. Your data never leaves your machine unless you explicitly send it to a cloud provider.\n- **Watch it work.** The Live Studio shows the agent's step timeline, real file diffs, and changed files as it runs. Sessions are URL-addressable and replayable.\n- **A team of specialists, not a chatbot.** The orchestrator decomposes a mission, fans the work out to up to 4 specialists in parallel, verifies output, and synthesizes the result.\n- **Accessible by design.** WCAG 2.1 AA primitives, a contrast-audit harness that proves every theme meets AA, full keyboard focus, ARIA, and a skip-link landmark.\n- **Observable.** Per-run spans (latency, tokens, cost, tools) with OTel export.\n\n---\n\n## Quick start\n\n```bash\n# Stable release\nnpm install -g titan-agent\ntitan gateway            # opens Mission Control at http://localhost:48420\n```\n\nThat's it — no setup required first. The dashboard greets you and connects a model in about a minute (one click if Ollama is running; or paste any API key / OpenAI-compatible endpoint). Prefer the terminal? `titan onboard` runs the full interactive wizard.\n\n**Which model?** Benchmarked through TITAN's own harness (July 2026, clean rerun): best local = **`qwen3-coder-next`** (85%, 5.2s median) and — on DGX-Spark-class unified memory — **Qwen3.6-35B-A3B NVFP4** (85%, ties it); best cloud = **GLM-5.1** / **Kimi K2.6** (93%). TITAN v7.1 auto-adapts to each deployment's real context (learned live), so small-context deployments degrade gracefully instead of failing — details and honest caveats in [benchmarks/MODEL_COMPARISON.md](benchmarks/MODEL_COMPARISON.md).\n\nOr one-liner:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Djtony707/TITAN/main/install.sh | bash\n```\n\nOr Docker:\n\n```bash\ndocker run -d -p 48420:48420 --name titan \\\n  -e ANTHROPIC_API_KEY=your-key \\\n  -v titan-data:/home/titan/.titan \\\n  ghcr.io/djtony707/titan:latest\n```\n\n**Requirements:** Node ≥ 22 (pure ESM). NVIDIA GPU + CUDA optional for LoRA fine-tuning and F5-TTS voice cloning. Apple Silicon Metal supported.\n\n**Upgrading from v5.x or v6.x:** just re-install. The migration runner takes an automatic backup to `~/.titan/backups/` and rolls forward. `titan backup restore \u003cid\u003e` puts you back if anything breaks.\n\n---\n\n## What TITAN actually does\n\n**A team of specialists, not a chatbot.** Type a mission. The orchestrator decomposes it, fans the work out to up to 4 specialists in parallel (Scout / Builder / Writer / Analyst / Sage), and synthesizes the result. You watch them work in real time on Mission Control.\n\n**Watch it work, live.** The Live Studio is a split-pane \"watch it work\" view: a **step timeline** on one side, **live file diffs** and a **changed-files rail** on the other, driven by a session-scoped event spine that emits `tool:call` / `tool:result` as the agent runs. Sessions are URL-addressable and replayable, so you can share a link or scrub back through what happened.\n\n**Model-agnostic by design.** TITAN binds native tool-calls per vendor through a shared capability registry, maps `forceToolUse` to each model's `tool_choice`, enforces JSON mode with an anti-truncation floor, and adapts `max_tokens` to a deployment's real ceiling. Run any capable model — the harness fits the model, not the other way around.\n\n**A real autonomous loop.** Goals run in the background. The driver picks subtasks, spawns specialists, verifies output, retries with smarter strategies on failure, and surfaces blocking questions only when a human is actually needed. Up to 25 tool rounds per turn, real planning, real verification, with a bounded loop-breaker that can't itself spin.\n\n**Materializes the workspace around you.** Don't have a tool for the job? Ask the agent and it builds one. Stock tracker, pomodoro, SDR widget, dashboard — drag them around on infinite canvases. Built on Mission Control, a React 19 SPA served by the gateway at port 48420.\n\n**A soul that does something.** TITAN-Soma is a homeostatic drive layer (purpose, curiosity, hunger, safety, social) that ticks every 60s and modulates behavior. Dream Mode writes a journal entry about its day at 03:30 local. Persona profiles + auto-revert A/B test prompt changes against drive satisfaction and roll back regressions automatically.\n\n---\n\n## The team (5 specialists, up to 4 in parallel)\n\n| Specialist | What it does | When you'll see it |\n|---|---|---|\n| **Scout** | Web research, fact-checking, monitoring, data gathering | \"Find me everything about X\" |\n| **Builder** | Code, files, shell commands, deploys, infrastructure | \"Build me a dashboard with charts\" |\n| **Writer** | Content, copy, emails, documentation, posts | \"Write the launch announcement\" |\n| **Analyst** | Data analysis, decisions, reasoning, spreadsheets | \"Compare option A vs B vs C\" |\n| **Sage** | Review, critique, verification, quality assurance | \"Make sure this is right before I send it\" |\n\nThe LLM picks which specialists to spawn based on the goal. You can also call them directly via `agent_team`, `agent_chain`, `agent_delegate`, or `spawn_agent`. For *external* coding agents (codex / aider / goose / gemini / opencode), use the new `delegate_agent` skill — it never shells out to the `claude` CLI.\n\n---\n\n## Where TITAN runs\n\n**LLM providers (36 total).** 4 native: Anthropic, OpenAI, Google, Ollama. 32 OpenAI-compatible presets: Groq, Mistral, Fireworks, xAI, Together, DeepSeek, Cerebras, Cohere, Perplexity, Venice, Bedrock, LiteLLM, Azure, DeepInfra, SambaNova, Kimi, HuggingFace, AI21, Cohere v2, Reka, Zhipu, Yi, Inflection, Novita, Replicate, Lepton, Anyscale, Octo, Nous, OpenRouter, NVIDIA, MiniMax. The generic `openai_compat` path binds native tool-calls per model via the shared capability registry. Verify in `src/providers/openai_compat.ts`.\n\n**Channels (19 adapters).** Discord, Telegram, Slack, WhatsApp, Matrix, Signal, MS Teams, Facebook Messenger (HMAC-verified webhook), Google Chat, IRC, Mattermost, Lark/Feishu, LINE, Zulip, Email (inbound), WebChat. Verify in `src/channels/`.\n\n**Mesh networking.** Run TITAN on multiple machines and they discover each other via mDNS, or peer them statically over Tailscale or any overlay. Distribute work across your homelab.\n\n**TITAN Phone Desk** *(experimental, opt-in)*. Optional Dograh sidecar integration for Twilio/Telnyx voice workflows. Approval-gated outbound calls, admin allowlists, opt-out enforcement, replay protection. Disabled by default; no calls are placed unless you configure it.\n\n**Home Assistant.** Voice or text control of lights, thermostats, locks, sensors via the `home_assistant` skill.\n\n**Voice mode.** LiveKit WebRTC for low-latency duplex calls. F5-TTS for voice cloning (Andrew, Adam, Bella, Joel, Sarah, Nicole, Aaron, Beth voices included). Browser TTS fallback when F5-TTS isn't installed.\n\n---\n\n## The numbers (verified)\n\n| Thing | Count | Verify with |\n|---|---|---|\n| **Version** | 7.0.0 | `package.json`, `src/utils/constants.ts` |\n| **Downloads** | 40K+ lifetime | `npm view titan-agent` + npm stats |\n| **LLM providers** | 36 (4 native + 32 OpenAI-compat) | `src/providers/openai_compat.ts` |\n| **Channel adapters** | 19 | `src/channels/*.ts` |\n| **Skills loaded at runtime** | ~143 | `GET /api/skills` |\n| **Tools registered** | ~248 | `GET /api/skills` |\n| **Test cases** | 8,122 passing / 9 skipped / 0 failing | `npm test` |\n| **Mission Control admin panels** | 51 | `ui/src/components/admin/` |\n| **Soma drives** | 5 (purpose, curiosity, hunger, safety, social) | `src/organism/` |\n| **Gateway port (default)** | 48420 | `src/utils/constants.ts` |\n| **Node** | ≥ 22, pure ESM | `package.json` |\n| **License** | MIT | `LICENSE` |\n\nEvery row above traces to code. The repo has a self-check at `tests/unit/readme-claims.test.ts` that fails CI if the verified counts drift beyond tolerance.\n\n### v7.0 verification\n\nThe v7.0.0 release was verified end-to-end before publish:\n\n- **Full test suite:** 8,122 pass / 9 skip / **0 fail**.\n- **Muscle Memory adversarial review:** 26-agent review fleet, 21 confirmed findings — all fixed before ship; the learned-skill pipeline was proven live (mined a real repeated workflow, drafted `add-widget`, passed its replay exam unprompted on first boot).\n- **Welcome Mode first-run:** verified on a virgin machine end-to-end — boot with zero config → guided connect → first real reply, no restart.\n- **Live UI route sweep:** 40 / 40 routes render clean (zero console errors).\n- **v7-smoke e2e:** 12 / 12.\n- **API sweep:** 18 / 19 (the one non-200 is a 503 by design).\n- **Chat:** works end-to-end.\n- **Behavioral eval-gate:** 93% (GO).\n\n---\n\n## Testing\n\n```bash\nnpm test                 # full suite (8,000+ cases)\nnpm run test:watch       # watch mode\nnpm run test:parity      # cross-model parity (replays the same scenario across providers)\nnpm run test:eval        # live behavioral eval against a running gateway (5-15 min)\nnpx vitest run tests/core.test.ts   # single file\n```\n\nFive testing layers cover regression risk at different levels:\n\n| Layer | What it covers | Speed |\n|---|---|---|\n| Unit | Pure functions: regex, classifiers, gate extraction, token budget, secret scanner, capability registry, contrast harness | seconds |\n| Mock trajectory | Tape-replay through `MockOllamaProvider` — asserts the right tools fire in the right order | \u003c 1s |\n| Cross-model parity | Same scenario across multiple provider tapes — catches behavioral drift | \u003c 1s |\n| Full deterministic | Whole vitest run | 2-4 min |\n| Live eval | Behavioral suites against a running agent | 5-15 min |\n\n---\n\n\u003ca id=\"roadmap\"\u003e\u003c/a\u003e\n\n## Roadmap (not in v7.0)\n\nThese are **planned**, not shipped. v7.0 lays the foundation for them but does not include them:\n\n- **Roster Forge — dynamic agent spawning.** Define and spin up new specialist roles at runtime, beyond the fixed five.\n- **Verdict-grounded self-evolution loop.** Close the loop so the agent's own eval verdicts drive prompt/behavior evolution automatically. (v7.0's Muscle Memory covers *workflow-level* self-learning with replay exams; this item extends grounded verdicts to prompt/behavior evolution, e.g. GEPA fitness.)\n- **Live Studio live preview pane.** A running preview server in the Studio right-pane (today: timeline + file-diff stream + changed-files list only — **no preview pane**).\n- **One-click revert + the round/token spine tail.** A revert button on the change rail and round/token accounting on the event spine (today: **no revert button**, diffs are read-only).\n\nIf you want one of these sooner, [open a discussion](https://github.com/Djtony707/TITAN/discussions) or a PR.\n\n---\n\n## Reality check\n\nTITAN is experimental. It can execute commands, modify files, and take autonomous actions. **Use at your own risk.** Think of it as a motivated intern with root access who never sleeps and occasionally gets too creative.\n\nStart in supervised mode. Review what it does — the Live Studio makes that easier than ever. Don't hand it root on systems you can't afford to lose. The safety features are strong (5-layer secret scanner, prompt-injection shield, kill switch, approval gates on destructive tools that can't be bypassed by sibling tools in a batch, atomic file checkpoints with restore, HMAC-verified inbound webhooks) but they augment good judgment, not replace it.\n\n---\n\n## Architecture\n\n```\nsrc/\n├── agent/        # Core loop, orchestrator, sub-agents, Command Post governance,\n│                 # Soma drives, Dream Mode, Persona A/B, mission lifecycle, event spine\n├── browsing/     # Playwright pool + CapSolver CAPTCHA\n├── channels/     # Channel adapters (16)\n├── config/       # Zod-validated schema\n├── context/      # ContextEngine plugin system\n├── gateway/      # Express + Mission Control React SPA (port 48420), traces API\n├── mcp/          # MCP Server (stdio + HTTP)\n├── memory/       # Memory, learning, graph, briefings, memory taxonomy\n├── mesh/         # mDNS + WebSocket + HMAC mesh networking\n├── organism/     # TITAN-Soma homeostatic drive layer\n├── providers/    # 36 LLM providers + router + fallback chain + capability registry\n├── skills/       # Builtin skills + dev + NVIDIA + ECC software-craft + personal\n├── telephony/    # Phone Desk / Dograh integration (opt-in)\n├── voice/        # F5-TTS + LiveKit WebRTC\n└── vram/         # GPU VRAM orchestrator (auto model swap)\nui/               # React 19 + Vite + Tailwind 4 + React Router 7 (Mission Control + Live Studio)\ntests/            # vitest suite (8,000+ cases)\ne2e/              # Playwright E2E\n```\n\n**Pure ESM, TypeScript strict mode, zero `__dirname`.** All config via Zod. Provider/model format: `\"provider/model-name\"` (e.g. `\"anthropic/claude-sonnet-4-20250514\"`). Multi-round tool loop up to 25 rounds in autonomous mode. Auth defaults to token mode; bypassed if no token configured (open access — turn it on for multi-user deployments). The `/v1` OpenAI-compatible endpoint is authenticated when auth is configured.\n\n---\n\n## Build it yourself\n\n```bash\ngit clone https://github.com/Djtony707/TITAN\ncd TITAN\nnpm install\nnpm run build \u0026\u0026 npm run build:ui\nnpm run dev:gateway          # http://localhost:48420\n```\n\nCI on GitHub Actions runs the full test suite + eval gate. See `.github/workflows/`.\n\n---\n\n## Further reading\n\n- **[CHANGELOG.md](CHANGELOG.md)** — every release, with the why\n- **[ARCHITECTURE.md](ARCHITECTURE.md)** — deeper architecture notes\n- **[CONTRIBUTING.md](CONTRIBUTING.md)** — how to contribute a skill, channel, or fix\n- **[SECURITY.md](SECURITY.md)** — security model + reporting issues\n- **[AGENTS.md](AGENTS.md)** — agent design notes\n- **[GitHub Discussions](https://github.com/Djtony707/TITAN/discussions)** — community Q\u0026A\n- **[Issues](https://github.com/Djtony707/TITAN/issues)** — bugs, requests\n\n---\n\n## Support TITAN\n\nThis is a solo open-source project. If TITAN saves you time or you'd like to see more development, support means a lot:\n\n- ⭐ **[Star the repo](https://github.com/Djtony707/TITAN)** — takes 2 seconds, helps others find it\n- ♥ **[Sponsor on GitHub](https://github.com/sponsors/Djtony707)** — monthly sponsorship keeps it open-source\n- 🐛 **File issues** when you hit them — every report makes the next release better\n- 🛠️ **PRs welcome** — new channels, skills, providers, fixes all appreciated\n\nBuilt by [Tony Elliott](https://github.com/Djtony707). MIT licensed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjtony707%2Ftitan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdjtony707%2Ftitan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjtony707%2Ftitan/lists"}