Talon
Multi-platform agentic AI harness. Runs on Telegram, WhatsApp, Discord, Microsoft Teams, the Terminal, and a cross-platform Desktop/Mobile companion app (Flutter), with a pluggable backend (Claude Agent SDK, Kilo, OpenCode, Codex, Antigravity, or OpenAI Agents) and full tool access through MCP.
Features
Quick Start
git clone https://github.com/thefalconry/talon.git && cd talon
npm install
# Interactive setup (select frontend, configure tokens, pick model)
npx talon setup
# Start
npx talon start # configured frontend (daemon mode)
npx talon chat # terminal chat mode
Prerequisites:
- Bun 1.3+ or Node.js 24+. Talon ships as
TypeScript sources and runs them directly: Bun executes them natively, Node goes
through a
tsxloader. Thetalonlauncher detects which runtime started it, so either works with no configuration —npm start/npm run devtake the Bun path,npm run start:node/npm run dev:nodethe Node one. Bun is what the release binaries and the maintained deployment run on; Node stays supported. - Backend-specific:
claudebackend: Claude Code installed and authenticated (claudeCLI on PATH).kilobackend: nothing extra —@kilocode/sdkspawns a local server. Free models are accessible without auth; routed models use Kilo's own credentials.opencodebackend: nothing extra —@opencode-ai/sdkspawns a local server.codexbackend: install thecodexCLI (npm i -g @openai/codex) and authenticate withcodex login,CODEX_API_KEY,TALON_CODEX_KEY, orcodexApiKey.OPENAI_API_KEYis used only as a fallback when no Codex login exists.agybackend: install Google's Antigravity CLI soagyis onPATH(or setagyBinary/AGY_BINARY), then runagyonce interactively on the host and complete the Google sign-in. There is no API key — headless runs reuse the cached OAuth credentials under~/.gemini/antigravity-cli/.
Standalone binary
Each release also ships self-contained binaries (no Node.js required) for Linux and macOS (x64 + arm64) and Windows (x64). Prompts and all native modules are embedded in the binary.
# Homebrew (macOS / Linux)
brew install thefalconry/talon/talon
# Debian / Ubuntu — download the .deb for your arch from the release, then:
sudo apt install ./talon_<version>_amd64.deb # or _arm64.deb
# Fedora / RHEL — download the .rpm for your arch from the release, then:
sudo dnf install ./talon-<version>-1.x86_64.rpm # or .aarch64.rpm
# Direct download — grab talon-<os>-<arch> from the release, verify, run:
chmod +x talon-linux-x64 && ./talon-linux-x64 --version
# macOS, if Gatekeeper blocks an unsigned binary:
xattr -d com.apple.quarantine ./talon-darwin-arm64
Verify a direct download against the release SHA256SUMS:
sha256sum -c SHA256SUMS --ignore-missing, and its build provenance with
gh attestation verify talon-linux-x64 --repo thefalconry/talon (see
SECURITY.md).
Server only, no Telegram? Run the daemon with just the client bridge, reached by the companion app and talon-node: see docs/server-install.md.
The binary runs the full interactive/agent CLI (
setup,start,chat,doctor, …) and supervises MCP children like any other install shape. The one gap: a plugin shipping its MCP server as TypeScript source (mcpServerPath) needs a runtime that can execute TS, which a compiled binary is not — those want the npm install. Plugins declaring an explicitmcpServercommand work everywhere.
Architecture
index.ts Composition root
|
+-- core/ Platform-agnostic engine
| +-- agent-runtime/ Backend capability interface, events, stores
| +-- frontend-runtime/ Frontend capability interface + descriptor registry
| +-- models/ Model layer: catalog, per-chat active model,
| | reasoning-effort vocabulary
| +-- prompt/ System-prompt assembly + prompts/system templates
| +-- background/ Agents that run without a user message:
| | heartbeat, dream, pulse, cron, triggers
| +-- tools/ MCP tool definitions + spawn/env contract
| +-- mcp-hub/ Daemon-hosted MCP over streamable HTTP; supervises
| | stdio children with respawn-and-backoff
| +-- engine/ Message flow: dispatcher (per-chat serial,
| | cross-chat parallel), HTTP gateway for MCP
| | tool calls, backend lifecycle controller
| +-- weaver/ Per-chat live state: a Weaver owns Looms own Threads
| +-- tasks/ Task table — the process table for agent work
| +-- bus/ Typed pub-sub spine + event journal
| +-- vfs/ The talon:// namespace (~/.talon/ns), FUSE-backed
| +-- mesh/ Device mesh: presence, exec/fs channel, teleport
| +-- memory/ Typed memory store policy: core view, import, taps
| +-- scripts/ Run-to-completion execution of saved scripts +
| | the WASM-sandboxed Lua runner for trigger scripts
| +-- daemon/ Start / stop / restart, pidfile, discovery
| +-- plugin/ Plugin loader, registry, hot-reload
| +-- update/ Self-update for git-checkout deployments
|
+-- backend/
| +-- registry.ts Bootstrap-decoupled backend lookup
| +-- shared/ Cross-backend helpers (stream state, flow violation,
| | delivery contract, metrics, prompt format,
| | model retry, system prompt, usage)
| +-- remote-server/ Shared infrastructure for agent-server backends
| | (MCP registration, sessions, providers, lifecycle)
| +-- claude-sdk/ Claude Agent SDK (in-process MCP, hooks)
| +-- kilo/ Kilo HTTP server backend (streaming via SSE)
| +-- opencode/ OpenCode HTTP server backend
| +-- codex/ Codex CLI backend (`@openai/codex-sdk`)
| +-- agy/ Antigravity CLI backend (headless stream-json)
| +-- openai-agents/ OpenAI Agents SDK backend (Responses API)
|
+-- frontend/
| +-- factories.ts Attaches each built-in's lazy `create`
| +-- shared/ Cross-frontend presentation helpers
| +-- telegram/ grammY bot + GramJS userbot
| +-- whatsapp/ Baileys multi-device socket
| +-- discord/ discord.js v14
| +-- teams/ Bot Framework + Graph API
| +-- terminal/ Readline CLI with tool call visibility
| +-- native/ Client bridge (HTTP + SSE) for the companion app
|
+-- native/ WASM + napi cores (blake3, strsim, textops, sqlguard,
| htmlents, scheduler, fusefs, warden), each with a
| pure-TS or wasm fallback
+-- storage/ SQLite layer: sessions, history, chat settings, cron,
| media index, metrics, goals, skills, kv, daily logs
+-- util/ Config, logging, workspace, paths, time, runtime
Dependency rule: core/ imports nothing from frontend/ or backend/. Frontends and backends depend on core types, never on each other. All six backends (Claude SDK, Kilo, OpenCode, Codex, Antigravity, OpenAI Agents) implement the same Backend capability interface from core/agent-runtime/capabilities.ts. Frontends mirror this: each implements the Frontend contract from core/frontend-runtime/capabilities.ts and self-registers in the frontend registry (identity + chat-id routing in a descriptor, lazy create in a per-frontend factory.ts) — see docs/frontends.md. Kilo and OpenCode additionally share the remote-server/ infrastructure because they wrap forks of the same upstream HTTP agent server.
Prompts: everything the model reads at session start is assembled by core/prompt/ from the files in prompts/ — see prompts/README.md for the assembly order, file ownership (user-editable vs package-owned templates), and the per-backend delivery contracts.
Frontends
Select via the frontend field in ~/.talon/config.json — one id, or an array to run several at once. Every frontend implements the same Frontend contract and registers a descriptor (identity + which chat ids it owns) in the frontend registry, so a chat id routes to its owning frontend with no central switch — see docs/frontends.md.
Running several is just an array; each chat id keeps its own session and the frontend that owns it answers:
{ "frontend": ["telegram", "whatsapp", "native"] }
The WhatsApp frontend drives a real WhatsApp account over Baileys multi-device — the same mechanism as WhatsApp Web, so no Business API account is involved.
// ~/.talon/config.json
{
"frontend": "whatsapp",
"whatsapp": {
// The bot account's own number, E.164 digits, no "+". Omit for QR pairing.
"pairingNumber": "353871234567",
// Who may DM it — bare numbers or full JIDs. Empty disables DMs.
"allowedJids": ["447700900102"],
// Which groups it serves: "listed" | "with-allowed-user" | "all"
"groupPolicy": "with-allowed-user",
// In groups: reply only when mentioned/quoted, or to everything
"respondMode": "mention"
}
}
First start prints a pairing code (or a QR when pairingNumber is omitted) — enter it under WhatsApp → Linked devices → Link with phone number. Credentials persist in ~/.talon/whatsapp-auth/, so later starts reconnect on their own, with backoff across drops.
groupPolicy: "with-allowed-user" is the useful middle setting: the bot serves any group containing someone from allowedJids — "the groups I'm in" — without listing group JIDs by hand.
Markdown from the model is translated into WhatsApp's own dialect (*bold*, _italic_, ~strike~, monospace blocks) by walking the parsed token tree rather than by regex, and long replies split on message boundaries instead of truncating.
Backends
Select via the backend field in ~/.talon/config.json. All backends implement the same Backend capability interface — heartbeat, dream, and chat handlers are backend-agnostic.
The Kilo and OpenCode backends share infrastructure (backend/remote-server/) since the upstream HTTP API is the same; each backend supplies its own SDK client, port, and delivery suffix. Codex is its own integration on top of the Codex CLI's JSONL event stream, and Antigravity is its own on top of agy's headless NDJSON protocol.
Desktop & mobile app
The native frontend turns the daemon into a client bridge — a versioned HTTP + Server-Sent-Events JSON API (the Talon Client Bridge Protocol, src/frontend/native/protocol.ts) that any GUI client can speak. The reference client is Talon Companion, a single Flutter codebase that runs on Windows, macOS, Linux, and Android. The protocol has three independent implementations (daemon, companion, talon-node); shared wire fixtures in protocol/ are replayed by all three test suites so a drift on any side fails its CI — see protocol/README.md.
// ~/.talon/config.json
{
"frontend": "native",
"native": { "host": "127.0.0.1", "port": 19880 }
// For remote (e.g. a phone): "host": "0.0.0.0", "token": "your-secret"
}
The old
"desktop"spelling still loads — config normalization rewrites it to"native"and logs a deprecation — but new configs should saynative.
- Local (desktop): the app connects to a Talon on the same machine and launches one if needed (
TALON_FRONTEND_OVERRIDE=desktop). - Remote (mobile/LAN): point the app at
host:port+ token; the bridge requiresAuthorization: Bearer …(or?token=on the SSE stream) whenever a token is set. - Encryption: off-loopback binds serve HTTPS by default with a persistent self-signed certificate (
~/.talon/keys/); the companion pins its SHA-256 fingerprint on first connect and refuses any change afterwards. The daemon logs the fingerprint at startup and/healthadvertises it. Opt out (or in, on loopback) with"tls": false/truein thenativesection. - From anywhere, certificate-only (Immich-style): put your reverse proxy (Caddy, nginx, Traefik, Cloudflare Tunnel) in front with client-certificate auth; import the
.p12in the companion, which also switches to your home-network address whenever it answers. Talon still authenticates with its token — see docs/mtls.md.
The app keeps itself up to date — it watches this repo's releases and installs the next one itself (silently on a rooted/Shizuku phone, swap-and-relaunch on desktop; see docs/companion-updates.md). It provides multi-chat history, live streaming with reasoning + tool-call visibility, per-chat model/effort/reset, and settings sync — read and change the daemon's own config (default model, display name, timezone, pulse/heartbeat/dream) and restart it. See apps/companion/README.md.
Managing plugins & skills
Both stores are managed from the CLI; changes hot-reload into a running daemon (plugins) or apply on the next session (skills):
# Plugins — npm specs, git repos, or local paths
talon plugin install @scope/my-talon-plugin # npm → module plugin
talon plugin install some-mcp-server --mcp # npm → standalone MCP server (npx)
talon plugin install owner/repo # git → module plugin
talon plugin install owner/repo#<sha> # …at that commit (or --commit <sha>)
talon plugin list # built-ins + configured entries
talon plugin disable github # also toggles built-ins
talon plugin remove my-talon-plugin
# Skills — SKILL.md folders from local paths, git URLs, or owner/repo[/subpath]
talon skill install anthropics/skills/document-skills/pdf
talon skill install ./my-skill --force
talon skill list
talon skill disable pdf # hidden from the prompt index, still readable
talon skill remove pdf
Module plugins install under ~/.talon/plugins/; standalone MCP servers are
registered as npx entries in config.json. A git source can be pinned to a
commit with #<sha> or --commit <sha> (7-64 hex digits): Talon checks that
commit out and verifies HEAD before installing. Either way the install
folder's .talon-install.json records the repo and the exact commit. Disabling keeps the entry (or a
.disabled marker in the skill folder) so enabling restores it unchanged.
Built-in Plugins
GitHub
GitHub API access via the official GitHub MCP server. Gives the agent access to repositories, issues, PRs, code search, and more.
Requirements: Docker installed and running.
{
"github": {
"enabled": true,
"token": "ghp_..."
}
}
The token is optional --- defaults to the output of gh auth token if the GitHub CLI is authenticated.
The server image is pinned to a known-good tag and pulled in the background at boot when absent (docker still pulls on first use as the fallback). Override with "imageTag" ("latest" opts out of pinning); "autoProvision": false disables the pre-pull.
Long-term Memory
Talon supports two long-term memory backends, selected via the unified memory section:
{
"memory": {
"enabled": true,
"backend": "mempalace"
}
}
Set "backend" to "mempalace" (local, vector search + knowledge graph) or "mem0" (mem0 hosted platform or self-hosted server). Backend-specific settings go in a matching memory.mempalace / memory.mem0 sub-object. The legacy top-level mempalace section is still honored when memory is absent.
MemPalace backend
Structured long-term memory with vector search. The agent can store, search, and retrieve memories semantically. Integrates with Dream mode for automatic memory consolidation and personal diary entries.
Requirements: Python 3.10+ on PATH. Nothing else — Talon provisions its own environment.
On first boot Talon creates a venv at ~/.talon/mempalace-venv and installs the pinned mempalace version into it. From then on the venv is self-maintaining: version drift against the pin reconciles automatically in the background, a broken install (half-written site-packages, a gutted venv) self-heals at the next start, and one-time palace data migrations (e.g. the ≥3.4 wing-name normalization) are applied exactly once, safely and idempotently. Failed upgrades never take the working install down — the current version keeps serving and the retry backs off.
{
"memory": {
"enabled": true,
"backend": "mempalace",
"mempalace": {
"palacePath": "~/.talon/workspace/palace",
"version": "3.10.0",
"autoUpdate": true,
"autoProvision": true
}
}
}
Everything is optional --- palacePath defaults to ~/.talon/workspace/palace/, version defaults to the built-in pin, and both auto* flags default to true. Leave pythonPath unset to use the managed venv --- its interpreter is ~/.talon/mempalace-venv/bin/python on Linux/macOS and ~/.talon/mempalace-venv/Scripts/python.exe on Windows; any other value is treated as operator-managed (see below). autoProvision governs creating and healing the venv; autoUpdate governs reconciling a working venv to the pin --- they are independent.
Bring your own environment: point pythonPath at any interpreter — a uv tool install, pipx, conda, or your own venv — and Talon treats it as operator-managed: it is probed and reported on (talon doctor shows the exact upgrade command for your install flavor) but never mutated.
mem0 backend
Long-term memory via mem0 --- mem0 extracts durable facts from what the agent stores and retrieves them by semantic search. Works against the hosted platform (API key) or a self-hosted mem0 server.
Requirements: None --- the mem0ai SDK is bundled with Talon.
{
"memory": {
"enabled": true,
"backend": "mem0",
"mem0": {
"apiKey": "m0-...",
"userId": "talon"
}
}
}
apiKey defaults to the MEM0_API_KEY env var. For a self-hosted server set "host" instead --- the key is then optional. userId is the entity id memories are filed under (default "talon").
Playwright
Headless browser automation via the Playwright MCP server. The agent can browse websites, take screenshots, generate PDFs, fill forms, and scrape content.
Requirements: None --- @playwright/mcp is bundled with Talon.
{
"playwright": {
"enabled": true,
"browser": "chromium",
"headless": true
}
}
Supported browsers: chromium (default), chrome, firefox, webkit, msedge.
For Playwright-managed engines (chromium, firefox, webkit) the browser build is downloaded automatically at boot when missing — version-matched to the bundled @playwright/mcp. System channels (chrome, msedge) and endpoint mode are never touched. "autoProvision": false disables the download.
Brave Search
Web search via the Brave Search MCP server. Replaces the built-in WebSearch/WebFetch tools with higher-quality search results.
{
"braveApiKey": "BSA..."
}
Get an API key at brave.com/search/api.
Custom Plugins
Plugins add MCP tools and gateway actions without modifying core code. SOLID interface --- only name is required.
{
"plugins": [{ "path": "/path/to/my-plugin", "config": { "apiKey": "..." } }]
}
export default {
name: "my-plugin",
version: "1.0.0",
mcpServerPath: resolve(import.meta.dirname, "tools.ts"),
validateConfig(config) {
/* return errors or undefined */
},
getEnvVars(config) {
return { MY_KEY: config.apiKey };
},
handleAction(body, chatId) {
/* gateway action handler */
},
getSystemPromptAddition(config) {
return "## My Plugin\n...";
},
init(config) {
/* one-time setup */
},
destroy() {
/* cleanup */
},
};
Plugins support hot-reload via the reload_plugins MCP tool --- no restart required.
CLI
talon Interactive menu (runs setup on first launch)
talon setup Guided setup wizard
talon start Start as a background daemon
talon stop Stop the daemon
talon restart Restart the daemon
talon run Run in the foreground, attached
talon chat Terminal chat mode (always available)
talon status Health, sessions, plugins, runtime, disk usage
talon ps List agent tasks (--all includes journal history)
talon kill Abort a killable task by id
talon events Tail the event bus (-f follows, --history [N] reads the journal)
talon plugin Manage plugins (install / enable / disable / remove)
talon skill Manage skills (install / enable / disable / remove)
talon history Chat history kept by Talon (show / hidden / purge — docs/chat-history.md)
talon accounts Claude accounts (list / add / remove / login — docs/claude-accounts.md)
talon config View or edit configuration
talon logs Tail structured log file
talon doctor Validate environment and dependencies
Configuration
Config file: ~/.talon/config.json
Scaling limits
Two caps bound how much background work Talon keeps alive. Both keep their
historical defaults and are raised in ~/.talon/config.json; the error a
capped tool returns names the key to raise.
With maxPersistentPerChat unset, persistent and ad-hoc triggers share
maxActivePerChat, exactly as before. Set it and the two draw from separate
budgets: persistent triggers count only against maxPersistentPerChat, and
maxActivePerChat then bounds ad-hoc (non-persistent) triggers only — so a
chat running long-lived watchers still has room for a short CI wait. Caps are
checked at trigger_create; lowering one never kills a trigger already
running, and persistent triggers resumed after a restart are not re-checked.
"triggers": { "maxActivePerChat": 5, "maxPersistentPerChat": 6 },
"agents": { "maxConcurrent": 12 }
Background reasoning effort
heartbeatEffort / dreamEffort set how hard the background agents think —
useful when you want unattended goal work to reason harder than a chat turn,
or hourly heartbeats to stay cheap. Chat effort stays per-chat (/settings).
Which levels a model accepts comes from its catalog entry, so the usable set
differs per model (max is Claude's ceiling, xhigh is Codex's). A level the
model doesn't offer is dropped — the run proceeds on the model default, the
reason is written to the run log, and the boot-time model audit warns about it.
Backends with no reasoning knob at all (Kilo, OpenCode) ignore the setting.
Terminal Mode
npx talon chat
Tool calls shown in real-time with parameters. Streaming phase indicators (thinking / responding / using tools). Per-turn stats: duration, tokens, cache hit rate, tool count.
Commands: /model, /effort, /context, /status, /reset, /rename, /resume, /help, /quit
Production
Docker: the image runs the daemon on Bun (bun src/index.ts); ~/.talon and ~/.claude are bind-mounted from the host into the container's HOME=/home/bun. Prebuilt images are on GHCR (ghcr.io/thefalconry/talon:latest), and a first boot can be configured entirely from TALON_* environment variables — see docs/docker.md for the quick install, and docs/truenas.md for a step-by-step TrueNAS SCALE install.
docker compose up -d
A Node 24 + tsx image is kept as a fallback for one release cycle: docker build --build-arg RUNTIME=node -t talon . (or set build.args.RUNTIME in docker-compose.yml). Mount paths are the same for both. See packaging/README.md for the build's details.
The image is also ready for the Antigravity (agy) backend: add -f docker-compose.agy.yml to mount ~/.gemini and the agy binary (or bake the binary in with AGY_DOWNLOAD_URL + AGY_SHA256). See docs/docker.md.
Systemd: unit file at packaging/systemd/talon.service — copy to /etc/systemd/system/, set User= and WorkingDirectory=, then systemctl enable --now talon.
Health endpoint: GET http://localhost:19876/health returns the daemon's identity (app, mode, pid, port, startedAt, ok). With the gateway token (Authorization: Bearer $(cat ~/.talon/keys/gateway-token)) it also returns uptime, memory, queue depth, active sessions, and last activity timestamp. Every other gateway route requires that token.
Logging: Structured JSON via pino to ~/.talon/talon.log. Rotated on startup when the file exceeds 10MB.
Resilience: Dynamic model fallback on overload, session auto-retry on expiry, rate limit handling with backoff, atomic file writes, graceful shutdown with 15-second drain timeout.
Development
npm run dev # watch mode (Bun)
npm run dev:node # watch mode (Node + tsx)
npm test # 4500+ tests across unit / SDK-stub / MCP-functional / integration tiers
npm run test:coverage # with coverage report
npm run typecheck # tsc --noEmit
npm run lint # oxlint
npm run format # prettier --write
npm run depcruise # dependency-cruiser — enforces the core/ import rule
npm run knip # unused files, exports, and dependencies
CI runs the full suite on Node 24 across Linux, macOS, and Windows; a separate
job compiles the standalone bun build --compile binary on all three and
smoke-tests the CLI and the MCP supervisor from it.
License
Apache License 2.0 — see LICENSE.
Releases up to and including v5.18.1 were published under the MIT License, kept at LICENSE-MIT. That grant is irrevocable for those versions and still covers the contributions made under it — see NOTICE.
