Skip to content
tomo

Guides

Task-oriented walkthroughs for running tomo: the channels it answers on, named workers, memory and skills, scheduling and the heartbeat, voice, MCP in both directions, the config file, and the policy gate that sits under all of it.

Each guide covers one job you actually do with tomo, grounded in the real config keys and commands. They assume you have worked through the quick start and have a ~/.tomo/config.yaml from tomo onboard.

  • Channels are the front doors tomo serve opens: the local web chat plus Telegram, Discord, Slack, and iMessage, each with an allow-list, and /session to carry one conversation across them.
  • Workers are named specialists with their own persona, model, policy, and memory, routed by @name or a channel binding, able to hand a task to a colleague.
  • Memory and skills cover the markdown memory tomo reads and writes itself, the curator that reflects after substantial turns, and the skills you install to teach it a workflow.
  • Scheduling is how tomo works on its own: tomo cron jobs and the heartbeat, both of which fail closed when no one is watching.
  • Voice runs speech both ways on your machine with whisper and piper, so no audio leaves the box.
  • MCP works in two directions: attaching MCP servers so their tools join tomo's, and serving tomo's own tools to other clients with tomo mcp.
  • Configuration is a tour of ~/.tomo/config.yaml, from providers and the agent knobs to the data directory.
  • Policy and safety is the whole trust model: the gate every tool call passes, capability classes, taint, and what tomo will never do by default.

Read policy and safety first if you care about what runs, what asks, and what taint does. Everything else here builds on that gate.

Channels The front doors tomo serve opens: the always-on web chat plus Telegram, Discord, Slack, and iMessage, each gated by an allow-list, and how /session binds a chat to a shared conversation you can carry between channels. Policy and safety How tomo decides what a tool call may do: capability classes, per-tool rules, the taint escalation that blunts prompt injection, external-tool handling, and what tomo will never do by default. Workers Named specialist workers with their own persona, model, policy, and memory. How routing picks a worker by @name or channel binding, and how one worker hands a self-contained task to a colleague, one level deep and gated by its own policy. Memory and skills The markdown memory tomo reads and writes itself, the curator that reflects after substantial turns and stamps each note with where it came from, and the skills you install to teach a workflow. Installing a skill is always your explicit act. Scheduling How tomo works on its own: cron jobs that fire a prompt on a schedule and post the result, and the heartbeat that runs against a checklist and stays quiet when there is nothing to say. Unattended runs fail closed. Voice Voice both ways, all local so no audio leaves the machine. Transcribe inbound voice notes with whisper.cpp, speak replies back with piper, and keep it reciprocal: talk and it talks back, type and it stays text. MCP Model Context Protocol in both directions: attach MCP servers so their tools join tomo's toolset (namespaced, defaulting to ask), and serve tomo's own tools to Claude Code and other clients with tomo mcp. Configuration A tour of ~/.tomo/config.yaml: the default model, providers for Anthropic and OpenAI-dialect servers, ${VAR} env expansion, the agent knobs, the policy gate, the data directory, and pointers to every section documented in its own guide.