Talon – open-source agentic AI harness for Telegram, Discord, Teams and terminal

Talon, an open-source agentic AI harness, launched with support for Telegram, Discord, Microsoft Teams, and terminal, offering pluggable backends including Claude Agent SDK, Kilo, OpenCode, Codex, and OpenAI Agents. The tool provides MCP tool access, background agents, goals, skills, triggers, and per-chat settings, enabling multi-platform autonomous AI operations.

Multi-platform agentic AI harness. Runs on Telegram , Discord , Microsoft Teams , and the Terminal , with a pluggable backend Claude Agent SDK , Kilo , OpenCode , Codex , or OpenAI Agents and full tool access through MCP. Multi-frontend | Telegram Grammy + GramJS userbot , Discord discord.js , Microsoft Teams Bot Framework , Terminal with live tool visibility | Pluggable backend | Claude Agent SDK, Kilo, OpenCode, Codex, OpenAI Agents — selectable per-process via backend config. Streaming, model fallback, context-overflow recovery. | MCP tools | Messaging, media, history, search, web fetch, cron jobs, triggers, goals, stickers, file system, admin controls | Plugins | Hot-reloadable plugin system. Built-in: GitHub, MemPalace, Playwright, Brave Search | Background agents | Heartbeat hourly by default — advances goals, proactively messages when something matters and Dream memory consolidation + diary | Goals | Persistent multi-day objectives the agent commits to in chat; every heartbeat run re-reads them, makes progress, and records what it did | Skills | Agent-authored reusable scripts bash/python/node — procedures worked out once get saved and replayed locally at zero token cost | Triggers | Self-authored watcher scripts bash/python/node that wake the bot when conditions are met | Per-chat settings | Model, effort level, and pulse toggle per conversation via inline keyboard | Model registry | Models discovered from the active backend at startup — new models appear in all pickers automatically | git clone https://github.com/dylanneve1/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: Node.js 24+ https://nodejs.org/ - Backend-specific: claude backend: Claude Code https://docs.anthropic.com/en/docs/claude-code installed and authenticated claude CLI on PATH . kilo backend: nothing extra — @kilocode/sdk spawns a local server. Free models are accessible without auth; routed models use Kilo's own credentials. opencode backend: nothing extra — @opencode-ai/sdk spawns a local server. codex backend: install the codex CLI npm i -g @openai/codex and authenticate with codex login , CODEX API KEY , TALON CODEX KEY , or codexApiKey . OPENAI API KEY is used only as a fallback when no Codex login exists. - Talon runs from a normal source or package install; standalone compiled binaries are not supported. index.ts Composition root | +-- core/ Platform-agnostic engine | +-- agent-runtime/ Backend capability interfaces, events, stores | +-- 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 | +-- engine/ Message flow: dispatcher per-chat serial, | | cross-chat parallel , HTTP gateway for MCP | | tool calls, backend lifecycle controller | +-- plugin.ts Plugin loader, registry, hot-reload | +-- 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 | +-- openai-agents/ OpenAI Agents SDK backend Responses API | +-- frontend/ | +-- shared/ Cross-frontend presentation helpers | +-- telegram/ Grammy bot + GramJS userbot | +-- discord/ discord.js v14 | +-- teams/ Bot Framework + Graph API | +-- terminal/ Readline CLI with tool call visibility | +-- storage/ Sessions, history, chat settings, | cron jobs, media index, daily logs +-- util/ Config, logging, workspace, paths, time Dependency rule: core/ imports nothing from frontend/ or backend/ . Frontends and backends depend on core types, never on each other. All five backends Claude SDK, Kilo, OpenCode, Codex, OpenAI Agents implement the same Backend capability interface from core/agent-runtime/capabilities.ts . 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 /dylanneve1/talon/blob/main/prompts/README.md for the assembly order, file ownership user-editable vs package-owned templates , and the per-backend delivery contracts. 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. | Backend | backend value | Transport | Notes | |---|---|---|---| | Claude SDK | "claude" | In-process via @anthropic-ai/claude-agent-sdk | Requires the claude CLI on PATH . Hook-based turn termination. | | Kilo | "kilo" | Local HTTP server via @kilocode/sdk | SSE-streamed turns. Routes to many model providers via Kilo's auth. | | OpenCode | "opencode" | Local HTTP server via @opencode-ai/sdk | SSE-streamed turns; same MCP and session shape as Kilo upstream fork . | | Codex | "codex" | Per-turn subprocess via @openai/codex-sdk | Requires the codex CLI from @openai/codex and Codex auth codex login , CODEX API KEY , TALON CODEX KEY , or codexApiKey . MCP servers configured via TOML overrides at thread start. | | OpenAI Agents | "openai-agents" | In-process via @openai/agents | Responses API or any OpenAI-compatible endpoint via TALON AGENTS URL / openaiBaseUrl . Persistent per-chat MCP bundles. | 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. 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. 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+ with the mempalace package. Set up a Python environment python -m venv ~/.talon/mempalace-venv ~/.talon/mempalace-venv/bin/pip install mempalace Unix or: ~/.talon/mempalace-venv/Scripts/pip install mempalace Windows { "mempalace": { "enabled": true, "palacePath": "~/.talon/workspace/palace", "pythonPath": "~/.talon/mempalace-venv/bin/python" } } Both paths are optional --- defaults to ~/.talon/workspace/palace/ and the venv Python respectively. 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 . 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 https://brave.com/search/api/ . 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. talon setup Interactive setup wizard talon start Start as a background daemon talon stop Stop the daemon talon chat Terminal chat mode always available talon status Health, sessions, plugins, disk usage talon config View or edit configuration talon logs Tail structured log file talon doctor Validate environment and dependencies Config file: ~/.talon/config.json | Field | Default | Description | |---|---|---| frontend | "telegram" | "telegram" , "discord" , "teams" , "terminal" , or an array | backend | "claude" | "claude" , "kilo" , "opencode" , "codex" , or "openai-agents" | botToken | --- | Telegram bot token | model | "default" | Default model. Interpretation depends on the active backend. | codexApiKey | --- | Codex-only OpenAI API key. Prefer this over openaiApiKey for Codex API-key auth. codex login takes precedence over shared openaiApiKey . | concurrency | 1 | Max concurrent AI queries 1--20 | pulse | true | Periodic group engagement | heartbeat | false | Background maintenance agent | heartbeatIntervalMinutes | 60 | Heartbeat interval | braveApiKey | --- | Brave Search API key | timezone | --- | IANA timezone e.g. "Europe/London" | plugins | | External plugin packages | disabledToolTags | --- | Hide whole tool groups from the model e.g. "stickers", "web" — each registered tool costs context tokens per session | disabledTools | --- | Hide individual tools by name end turn cannot be disabled | adminUserId | --- | Telegram user ID for /admin commands | allowedUsers | --- | Whitelist of Telegram user IDs | apiId / apiHash | --- | Telegram API credentials for full message history | github | --- | GitHub plugin config see above | mempalace | --- | MemPalace plugin config see above | playwright | --- | Playwright plugin config see above | 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 , /reset , /status , /help Docker: docker compose up -d 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 JSON with uptime, memory, queue depth, active sessions, and last activity timestamp. 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. npm run dev watch mode npm test 2300+ 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 MIT