Get started

Install and run.

A single binary, no daemon. Build from source or grab a prebuilt archive, sign in your way, then launch the terminal UI or drive it headless from a script.

Sixty-second start

Clone and install

Builds in release and links tomte onto your PATH.

git clone https://github.com/ryan-mt/tomte && cd tomte
make install

Sign in

Opens a browser for OAuth, or prompts for an API key.

tomte login

Run

Launches the terminal UI. Add resume to reopen a session.

tomte

Prefer a prebuilt binary

Grab the archive for your platform from the latest release and put tomte on your PATH.

Latest release

Linux x86-64tomte-x86_64-unknown-linux-gnu.tar.gz

macOS Inteltomte-x86_64-apple-darwin.tar.gz

macOS Apple Silicontomte-aarch64-apple-darwin.tar.gz

Windows x86-64tomte-x86_64-pc-windows-msvc.zip

Sign in your way

Four doors in: a subscription or an API key, OpenAI or Anthropic. OAuth uses PKCE and tokens refresh themselves.

Subscription, OpenAI

tomte login signs in with a ChatGPT Plus, Pro, Team, or Enterprise account over OAuth.

Subscription, Anthropic

Claude Pro or Max signs in over OAuth after you acknowledge the terms notice.

API key

Paste an OpenAI or Anthropic key, or let tomte pick up OPENAI_API_KEY and ANTHROPIC_API_KEY from the environment.

tomte login                                 # OpenAI OAuth (ChatGPT subscription)
tomte login --api-key --provider openai     # paste an OpenAI key
tomte login --api-key --provider anthropic  # paste an Anthropic key
tomte status                                # who am I, and on what plan
tomte logout

Two ways to talk to it

Run tomte with no subcommand for the full terminal UI. Or go headless for scripts, cron, and systemd. Same agent either way.

tomte, tomte resume, tomte chat, tomte run

headless

tomte chat "write a fibonacci function in Python"
tomte chat --model gpt-5.5-pro --reasoning high "refactor module X"
tomte prove --json   # gate CI on the project's own checks
tomte handoff --out HANDOFF.md   # the shift report, scripted
tomte run --cwd /srv/project --prompt-file nightly-task.md

Configuration

Settings live in config.json under your config directory. A project can override the safe behavioural fields with its own .tomte/config.json.

model: Default model, for example gpt-5.5 or claude-fable-5.
reasoning_effort: none, minimal, low, medium, high, xhigh, or max.
verbosity: low, medium, or high.
auto_approve_read: Auto-approve read-only tools.
auto_approve_write: Auto-approve write tools. False by default.
fallback_models: Ordered list used for transparent failover.

config.json

{
  "model": "gpt-5.5",
  "reasoning_effort": "medium",
  "verbosity": "medium",
  "auto_approve_read": true,
  "auto_approve_write": false,
  "fallback_models": []
}

Security-sensitive keys like default_permission_mode, the auto-approve flags, and providers are global-only, so a cloned repo cannot disable approvals or redirect the model.

Build from source

You need stable Rust, and ripgrep is recommended since it powers the grep tool. Then link it into your PATH, or run it in dev mode.

Read the field guide Contributing

from source

git clone https://github.com/ryan-mt/tomte && cd tomte
make install      # build release + link to PATH
make link-dev     # OR dev mode, re-runs cargo on each call
make unlink       # remove the link