TITAN — The Intelligent Task Automation Network

A fully autonomous AI agent framework with Autopilot Mode, Deliberative Reasoning, and Gmail OAuth. 20 providers. 60+ tools. 2,860+ tests. Pure JavaScript — no native compilation. No, seriously.

Quick Start • Why TITAN • Features • Providers • Mission Control • Mesh Networking • Custom Skills • CLI

WARNING — EXPERIMENTAL SOFTWARE TITAN is experimental, actively developed software. It can execute shell commands, modify files, access the network, and take autonomous actions on your system. Use at your own risk. Think of it less as "software you install" and more as "a very motivated intern with root access." The author and contributors provide this software "as is" without warranty of any kind. By installing or running TITAN, you accept full responsibility for any consequences, including but not limited to data loss, system instability, unintended actions, API charges, or security issues. Always review TITAN's configuration, run it in supervised mode first, and never grant it access to systems or credentials you cannot afford to lose. See LICENSE for the full legal terms.

Quick Start

Requirements: Node.js >= 20, an API key, and a healthy sense of adventure.

npm install -g titan-agent
titan onboard             # Interactive setup (pick a provider, paste your API key, give TITAN a soul)
titan gateway             # Launch Mission Control at http://localhost:48420
titan agent -m "Hello"    # Talk to your agent from the terminal

From Source

git clone https://github.com/Djtony707/TITAN.git && cd TITAN/titan
npm install
cp .env.example .env      # Add API keys
npm run dev:gateway        # Start in dev mode

Why TITAN

Features

Deliberative Reasoning

Most agents give you a single-shot answer and call it a day. TITAN actually thinks.

When TITAN detects an ambitious request — "figure out how to monetize this homelab," "build me an automated content pipeline," "come up with a strategy for X" — it doesn't just wing it. Instead, it enters a multi-stage deliberation loop:

1. Analyze — Examines the request from multiple angles using a reasoning model with high thinking
2. Plan — Generates a structured, dependency-aware execution plan
3. Approve — Presents the plan for your review (because autonomy without oversight is how sci-fi movies start)
4. Execute — Runs each task step-by-step, reporting progress in real-time via WebSocket
5. Adapt — If a step fails, re-analyzes and adjusts the plan

/plan figure out how to make money with my homelab    # Force deliberation mode
/plan status                                            # Check progress
/plan cancel                                            # Abort mission

Or just ask something ambitious and TITAN will detect it automatically. The detection is configurable — you can tune the complexity threshold, require approval, set max plan steps, or disable it entirely if you prefer your agents impulsive.

20 AI Providers, 70+ Models

Connect any combination of cloud and local models. TITAN routes, fails over, and load-balances automatically.

titan model --discover       # Live-detect all available models
titan model --alias fast=openai/gpt-4o-mini   # Create shortcuts
titan model --set anthropic/claude-sonnet-4-20250514

Built-in aliases: fast, smart, cheap, reasoning, local — fully configurable.

Running locally? See docs/MODELS.md for GPU-tiered Ollama model recommendations.

60+ Built-in Tools

Gmail OAuth Integration

Full Gmail access via OAuth2 — search, read, list, and send email. No extra npm packages. No googleapis. Just native fetch and the Gmail REST API, the way nature intended.

• Dashboard OAuth flow — Click "Connect Google Account" in Settings, complete consent, done
• Real Gmail API — email_search, email_read, email_list use the Gmail REST API with automatic token refresh
• Smart sending — email_send tries Gmail API first, falls back to SMTP if OAuth isn't configured
• Zero dependencies — Everything through native fetch (we don't believe in node_modules bloat)

# Or set credentials via environment variables
export GOOGLE_OAUTH_CLIENT_ID="your-client-id"
export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"

Token storage: ~/.titan/credentials/google.json — separate from config, because credentials deserve their own apartment.

SOUL.md — Personality That Persists

TITAN isn't just another "helpful assistant." It has a soul. Literally — it's a file called SOUL.md.

During onboarding, TITAN asks who you are and how you want it to behave. Your answers generate a personalized SOUL.md that's injected into every LLM system prompt:

# SOUL.md - Who You Are

## About Your Human
Music producer and developer. Runs a homelab with 6 machines.
Prefers direct, no-fluff answers.

## Your Personality
Technical partner, not a tutor. Think like an architect.
Suggest better approaches proactively. Be concise.

Edit it anytime from Mission Control Settings → Profile → SOUL.md editor. Because your AI should know that you hate verbose explanations. (The irony of this README's length is not lost on us.)

Temporal Knowledge Graph

Pure TypeScript graph memory — no Docker, no Neo4j, no external services.

• Conversations are automatically recorded as timestamped episodes
• Entities (people, projects, topics) are extracted and linked
• Relevant memories are injected into every system prompt
• Searchable across time with natural language

titan graphiti --init     # Initialize the graph
titan graphiti --stats    # View entity/episode counts

Multi-Agent System

Run up to 5 concurrent agents, each with its own model and personality. It's like having a team, except nobody argues about the thermostat.

titan agents --spawn researcher --model openai/gpt-4o
titan agents --spawn coder --model ollama/qwen3.5:4b
titan agents --list

Prompt Injection Shield

Two-layer defense against prompt injection attacks:

• Heuristic engine — Detects "ignore previous instructions", system prompt extraction, developer mode exploits
• Strict mode — Keyword density analysis and tail manipulation detection

Combined with the separate DM pairing system, which requires new senders to be approved before they can interact with your agent. Because not everyone deserves to talk to your AI.

Loop Detection & Circuit Breaker

Three detection algorithms prevent runaway tool loops:

• Repeat detection — Same tool, same arguments, called repeatedly
• No-progress detection — Tool returns identical output on consecutive calls
• Ping-pong detection — Alternating tool patterns with no forward progress
• Global circuit breaker — Hard stop after configurable threshold (your wallet says thanks)

Task Planner

Automatic goal decomposition with dependency-aware execution:

• Breaks complex goals into ordered sub-tasks
• Parallel execution of independent tasks
• 3x auto-retry with exponential backoff
• Persistent state at ~/.titan/plans/

Smart Context & Cost Optimization

• Auto-summarizes conversation history to stay within token budgets
• Routes simple queries to cheaper models automatically
• Per-session cost tracking with configurable daily budgets
• Classifies messages as simple/moderate/complex/ambitious for intelligent routing

Continuous Learning

TITAN gets smarter the more you use it:

• Tracks tool success/failure rates across all interactions
• Records error patterns and successful resolutions
• Persistent knowledge base at ~/.titan/knowledge.json
• Learned context injected into every system prompt

Relationship Memory

• Persistent user profile that survives restarts
• Remembers your name, preferences, work context
• Personal continuity across all sessions
• Enhanced by SOUL.md personality definition

Encrypted Secrets Vault

Store API keys and credentials securely in an AES-256-GCM encrypted vault with PBKDF2 key derivation. Reference secrets in config via $VAULT:secret_name.

titan vault --init              # Create vault with passphrase
titan vault --set OPENAI_KEY    # Store a secret
titan vault --list              # List stored secrets

Tamper-Evident Audit Log

HMAC-SHA256 chained JSONL audit trail at ~/.titan/audit.jsonl. Tracks tool executions, config changes, auth events, and security alerts with cryptographic tamper detection.

Self-Healing Doctor

titan doctor --fix automatically diagnoses and repairs common issues: missing directories, invalid configs, broken channels, stale logs, orphaned sessions, and file permissions. It's basically have you tried turning it off and on again, but automated.

Autopilot Mode

TITAN runs hands-free on a schedule, evaluates a checklist of standing instructions, takes autonomous action, and reports results.

titan autopilot --init           # Create ~/.titan/AUTOPILOT.md checklist
titan autopilot --enable         # Turn on scheduled runs
titan autopilot --run            # Trigger an immediate run
titan autopilot --status         # View schedule and last run info
titan autopilot --history        # See past run results

Edit ~/.titan/AUTOPILOT.md to control what TITAN watches each cycle. Results are classified as OK (silent), NOTABLE (summary delivered), or URGENT (priority alert). Cost-optimized: uses a cheaper model for routine runs, respects daily budgets, and skips runs outside active hours.

E2E Encrypted Sessions

AES-256-GCM encryption for sensitive conversations. Keys generated per-session, held in memory only.

Skyvern Browser AI (Optional)

TITAN integrates with Skyvern for AI-powered browser automation. Instead of brittle CSS selectors, Skyvern uses vision + LLMs to interact with web pages using natural language.

Native tools (built-in): TITAN includes 3 native Skyvern tools (skyvern_task, skyvern_extract, skyvern_sessions) that call Skyvern's REST API directly — no extra dependencies needed.

MCP integration (optional): For the full 35-tool suite, register Skyvern as an MCP server:

pip install skyvern && skyvern init    # Install Skyvern (Python)
skyvern run server                      # Start the Skyvern backend (port 8000)
titan mcp --add skyvern                 # Register as MCP server in TITAN

The MCP integration adds skyvern_act, skyvern_validate, credential management, and self-healing script compilation.

Skyvern is AGPL-3.0 licensed and runs as a separate service. TITAN's MIT license is not affected.

Providers

TITAN supports 20 AI providers out of the box. Add your API key and go. Or add all 20. We won't judge.

All providers support automatic failover. If one goes down, TITAN seamlessly routes to the next available provider. Your agent stays up even when OpenAI doesn't.

# Configure via CLI
titan config set providers.groq.apiKey "gsk_..."
titan config set providers.openrouter.apiKey "sk-or-..."

# Or via environment variables
export GROQ_API_KEY="gsk_..."
export OPENROUTER_API_KEY="sk-or-..."

Mission Control

A 12-panel dark-mode dashboard at http://localhost:48420. It's like NASA mission control, but for your AI agent, and with fewer rocket explosions.

New in Settings:

• Providers tab — Google OAuth connection (connect/disconnect with one click, manage client ID/secret)
• Profile tab — SOUL.md live editor (edit your agent's personality without touching the filesystem)

New in Onboarding:

• 4-step wizard: Profile → Soul → Provider → Autonomy
• Step 2 asks about you and how you want TITAN to behave
• Generates a personalized SOUL.md automatically

All settings are editable live without restarting the gateway.

Mesh Networking

Deploy TITAN across multiple computers with zero configuration. Machines auto-discover each other and share models.

LAN Discovery (mDNS)

Machines on the same network find each other automatically via Bonjour/mDNS.

# On machine 1
titan mesh --init        # Generates a shared secret

# On machine 2
titan mesh --join "your-secret-here"

# Check connectivity
titan mesh --status

Tailscale Integration

If you run Tailscale, TITAN automatically discovers peers on your VPN — works across networks, data centers, and cloud instances.

{
  "mesh": {
    "enabled": true,
    "tailscale": true
  }
}

Remote Model Routing

When a requested model isn't available locally, TITAN automatically routes to a peer that has it. Load-balanced across all available nodes.

Custom Skills

Create new tools for TITAN in seconds. Drop files into ~/.titan/skills/ and they're loaded automatically.

YAML Skills (Easiest)

# ~/.titan/skills/word_count.yaml
name: word_count
description: Count words, lines, and characters in a file
parameters:
  filePath:
    type: string
    description: Path to the file
    required: true
script: |
  const fs = require('fs');
  const content = fs.readFileSync(args.filePath, 'utf-8');
  const lines = content.split('\n').length;
  const words = content.split(/\s+/).filter(Boolean).length;
  return 'Lines: ' + lines + ', Words: ' + words + ', Characters: ' + content.length;

JavaScript Skills

// ~/.titan/skills/hello.js
export default {
  name: 'hello',
  description: 'Greet someone by name',
  parameters: {
    type: 'object',
    properties: {
      name: { type: 'string', description: 'Name to greet' }
    },
    required: ['name']
  },
  execute: async (args) => `Hello, ${args.name}!`
};

AI-Generated Skills

titan skills --create "a tool that converts CSV files to JSON"

TITAN writes, compiles, and hot-loads the skill instantly. Because why write code when you can make your AI write code?

Skill Auto-Generation

When TITAN encounters a task it can't solve with existing tools, it can write a new skill on the fly, compile it, and use it immediately.

Channel Adapters

Connect TITAN to your messaging platforms:

All 9 channels support the DM pairing security system. Configure via ~/.titan/titan.json or Mission Control Settings.

Recipes

Reusable multi-step workflows triggered by slash commands.

# Built-in recipes
/code-review     # Review files for bugs and improvements
/standup         # Prepare daily standup notes
/explain         # Explain code in plain English
/brainstorm      # Generate ideas on a topic
/debug           # Debug errors with guided analysis
/plan            # Deliberative reasoning with plan approval

Recipes support parameterized prompts ({{variable}}), optional tool-direct steps, and confirmation gates.

CLI Reference

Configuration

All state lives in ~/.titan/:

Development

npm run build          # tsup ESM production build
npm run test           # vitest (2,860+ tests, 70 files)
npm run ci             # typecheck + full test suite
npm run typecheck      # tsc --noEmit
npm run dev:gateway    # Dev mode with tsx
npm run test:coverage  # Coverage report (78%+ with 55% threshold)

Architecture

src/
  agent/        Core agent loop, multi-agent, swarm, planner, autonomy, deliberation, cost optimizer
  auth/         OAuth token managers (Google)
  channels/     Discord, Telegram, Slack, Google Chat, WhatsApp, Matrix, Signal, Teams, WebChat
  providers/    Anthropic, OpenAI, Google, Ollama + 16 OpenAI-compatible
  memory/       Episodic, learning, relationship, temporal graph
  skills/       60+ built-in tools + user skill loader
  security/     Shield, sandbox, encryption, pairing, vault, audit log
  gateway/      HTTP/WS server + Mission Control dashboard + OAuth endpoints
  mesh/         mDNS + Tailscale peer discovery, WebSocket transport
  recipes/      Workflow engine + persistence
  mcp/          Model Context Protocol client
  config/       Zod schema + loader (with deliberation + OAuth config)
  cli/          Commander.js CLI (16 commands), self-healing doctor
  utils/        Constants, logger, helpers

Autonomy Modes

Email tools are classified by risk: email_search, email_read, email_list are safe; email_send is moderate (because sending emails on someone's behalf without asking is how you lose friends).

Configure via titan config set autonomy.mode supervised or Mission Control Settings.

Roadmap

See TASKS.md for the full development roadmap.

Recently Shipped (v2026.5.x)

• v2026.5.11: Deliberative Reasoning (analyze→plan→approve→execute), Gmail OAuth integration (native fetch, zero deps), Soul Onboarding (4-step wizard with SOUL.md generation), SOUL.md live editor in dashboard, /plan slash command, ambitious message complexity detection, Google OAuth dashboard controls, 2,860+ tests
• v2026.5.9: Bug fixes + local model performance — port pre-check, small model tool reduction (<8B models get 7 core tools), Ollama think:false, configurable stall detector with GPU auto-detection, titan config [key], slash commands via REST API, config validation, graph entity extraction hardening, concurrent LLM request limiting, 2,850+ tests
• v2026.5.8: Ollama model guide (docs/MODELS.md), 147→0 ESLint warnings, local model alias, 2,830+ tests
• v2026.5.7: Google Chat channel (real webhook), Autopilot dashboard panel, Cloudflare Tunnel support, 2,600+ tests
• v2026.5.6: 3 new providers (Azure OpenAI, DeepInfra, SambaNova), Skyvern MCP browser automation, docs cleanup
• v2026.5.5: Autopilot Mode — hands-free scheduled agent runs with cron
• v2026.5.4: Encrypted secrets vault, tamper-evident audit log, self-healing doctor (--fix), 3 new providers (Venice AI, AWS Bedrock, LiteLLM), resource limits, 2,100+ tests
• v2026.5.3: 20 runtime bug fixes (Batches 1-2), 1,523 tests, 66.88% coverage
• Email skill (IMAP/SMTP via Nodemailer)
• PDF parsing skill (pdf-parse)
• Computer use (screenshots, mouse, keyboard via nut.js)
• WhatsApp, Matrix, Signal, MS Teams channel adapters
• Persistent webhooks with cron scheduling
• Morning briefing system
• OpenClaw Skill Scanner (quarantine + auto-scan)
• Onboarding wizard (titan onboard)
• MCP (Model Context Protocol) client support

Upcoming

• Vector Search & RAG Pipeline — SQLite FTS5 + embeddings for semantic memory search
• Code Interpreter — Sandboxed JavaScript/Python execution for data analysis
• Plugin Marketplace — Community skill sharing and discovery
• Team Mode & RBAC — Role-based access control for multi-user deployments

Contributing

1. Fork the repo
2. Create a feature branch (git checkout -b feat/my-feature)
3. Commit your changes (git commit -m "feat: add my feature")
4. Push (git push origin feat/my-feature)
5. Open a Pull Request

We don't bite. Unless you submit a PR that adds is-even as a dependency.

The Future of TITAN

TITAN is under active development and growing fast. Every release brings new providers, new tools, and deeper intelligence. The roadmap includes vector search & RAG, a code interpreter, plugin marketplace, team mode with RBAC, and much more.

It started as "what if I made an AI agent that actually does stuff" and evolved into a 27K-line TypeScript framework with 20 providers, 60+ tools, deliberative reasoning, Gmail OAuth, mesh networking, and a personality system. We're not entirely sure when it became sentient, but the SOUL.md file is a good suspect.

If you're looking for an AI agent framework that's lightweight enough to run on a Raspberry Pi but powerful enough to orchestrate multi-model workflows across a mesh of machines — you're in the right place.

Star the repo, join the journey, and help shape what autonomous AI agents look like.

Acknowledgments

TITAN stands on the shoulders of giants. Special thanks to the projects and people whose work made this possible.

Architectural Inspiration

• OpenClaw by Peter Steinberger — TITAN's architecture, CLI surface, tool signatures, workspace layout (AGENTS.md, SOUL.md, TOOLS.md), and DM pairing system are inspired by OpenClaw, the open-source personal AI assistant framework. Licensed under MIT.

Temporal Knowledge Graph

• Graphiti by Zep AI — TITAN's native temporal knowledge graph (src/memory/graph.ts) is inspired by the Graphiti project's approach to episodic memory, entity extraction, and temporal graph architecture. Created by Daniel Chalef, Preston Rasmussen, Pavlo Paliychuk, Travis Beauvais, and Jack Ryan. Licensed under Apache 2.0. Research paper: arXiv:2501.13956.

Browser Automation

• Skyvern by Skyvern AI — AI browser automation using vision + LLMs (native tools + MCP integration). Licensed under AGPL-3.0 (runs as a separate service).

Open-Source Libraries

• Express — HTTP server and API routing
• Zod — Configuration schema validation
• Commander.js — CLI framework
• ws — WebSocket server for real-time communication
• Chalk — Terminal styling
• Ora — Terminal spinners
• Boxen — Terminal box rendering
• Inquirer — Interactive CLI prompts
• dotenv — Environment variable loading
• node-cron — Cron scheduling
• uuid — Unique ID generation
• Playwright — Browser automation (optional)
• bonjour-service — mDNS mesh discovery (optional)
• tsup — Build tooling
• Vitest — Test framework
• TypeScript — Type-safe development

Thank you to all the maintainers and contributors of these projects.

Support / Fund

If TITAN saves you time, consider supporting its development:

Every contribution — large or small — helps keep TITAN free, maintained, and moving forward.

Disclaimer

TITAN IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS, COPYRIGHT HOLDERS, OR CONTRIBUTORS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

TITAN is an autonomous agent that can execute arbitrary commands, modify your filesystem, make network requests, and incur API costs. The author accepts no responsibility or liability for any actions taken by the software, including but not limited to: data loss, unauthorized access, unintended system modifications, API usage charges, security breaches, or any other damages resulting from use of this software. You are solely responsible for reviewing and approving all actions taken by TITAN on your systems.

License

MIT License — Copyright (c) 2026 Tony Elliott

Created by Tony Elliott (Djtony707)