Telemachus

A multi-provider TypeScript/Bun CLI coding agent with sliding-window context management, MCP support, and a built-in setup wizard.

# curl one-liner (macOS / Linux)
curl -fsSL https://raw.githubusercontent.com/Kristos/telemachus/main/install.sh | bash

# Docker (GHCR — same namespace as the source repo)
docker run -it --rm -v "$HOME/.telemachus:/root/.telemachus" ghcr.io/kristos/telemachus:latest

First run? tm drops you into an interactive setup wizard that picks providers, writes config, and runs a smoke test.

What is Telemachus

Telemachus is a CLI coding agent in the same family as Claude Code: it reads your repo, runs tools, edits files, and drives long agentic loops from the terminal.

It speaks to multiple LLM providers — Anthropic native (with prompt caching), any OpenAI-compatible endpoint (DeepSeek, Ollama, llama.cpp, vLLM), and configurable fallback chains — so you can route per-task instead of being locked to one vendor.

A sliding-window context engine keeps long sessions affordable: messages roll off in tool-pair-safe batches, with on-demand LLM compaction (/compact) and exact per-turn cost tracking so you always know what you're spending.

It is MCP-compatible (auto-mounts servers from a config file) and reads ~/.claude/skills/ as slash commands, so existing Claude Code investments port over without duplication.

The agent ships as several surfaces from the same core: a TUI (Ink + React), a headless agent-job runner, an orchestration engine (worker/reviewer/decomposer over git worktrees), and optional Discord, Telegram, and Web UI bridges.

Features

• Multi-provider LLM — Anthropic native (prompt caching), OpenAI-compatible APIs (DeepSeek, Z.ai, OpenRouter), local Ollama / llama.cpp / vLLM. Profile-driven routing — switch providers per task without manual /model.
• Tool-pair-safe sliding window — context management that never severs tool_use / tool_result pairs.
• Live status bar — tokens in/out, session total, USD cost, context window %, current model, permission mode.
• Built-in tools — bash (timeout), file read/write/edit, grep (ripgrep), glob, web search, ask, todo, worktree (git).
• MCP client (degraded-mode) — auto-mounts servers from ~/.claude.json, failed servers don't crash startup.
• Skill loader — reads ~/.claude/skills/ and exposes each skill as a slash command.
• Session persistence — atomic JSONL auto-save to ~/.telemachus/sessions/{uuid}.jsonl.
• Session resume — tm -r picker, tm --session <uuid> direct resume.
• Permission modes — yolo (no prompts), ask (inline prompt before bash / file writes), readonly (silent deny).
• Slash commands — /compact (on-demand LLM summarisation), /model (switch provider mid-session), /clear (reset context).
• Compiled binary — bun build --compile produces a single tm executable.
• Tab completion — cycles through slash commands in the input.

Front-ends, one core

Front-end	What it's good for
Terminal UI	Daily coding work; live status bar; slash commands; session resume.
Headless agent-runner (tm agent run <name>)	Cron jobs, webhooks, anything that fires without a human.
Orchestration engine (tm orchestrate)	Worker/reviewer loop with parallel fan-out and blast-radius gate.
Discord bot	Tap-in from anywhere; long-running conversations; !run / !status / !orchestrate commands.
Telegram bot	Same as Discord, different transport.
Web UI	Browser-based chat with the same agent core.

All front-ends share the same tool registry, session store, MCP mounts, and skill loader.

Documentation

• Quickstart — install, first run, smoke test
• CLI reference — flags, slash commands, environment variables
• MCP servers — auto-mount, sandboxing, per-server config
• Orchestration — worker/reviewer/decomposer loops
• Secrets management — tm secrets and the OS keychain bridge
• Docker — running the agent in a container
• Contributing — how to file issues and open PRs

License

MIT — see LICENSE.