usage.md

Usage

Writing a message

• @path attaches a file to your message. Typing @ opens a picker under the input: up / down moves through the matches, tab takes the highlighted one, esc closes it. Picking a directory walks into it, so you can browse down to a file without typing the whole path. A file attached whole counts as read, so the model can edit it right away. Works in -p mode too: thoth -p "explain @src/main.rs".
• !command runs a command yourself. Its output goes into the conversation as context without spending a model turn, which is the cheap way to show the agent a build error or a git log.
• thoth --continue (or -c) picks up this project's previous conversation, tools and all.

Keys

• enter sends. While the agent is working, messages queue up.
• shift+enter starts a new line in the message instead of sending it. alt+enter and ctrl+j do the same, for terminals that swallow the first one. Where none of them get through, end the line with \ and press enter: the backslash becomes the line break. The input grows to fit, up to ten rows.
• A / at the start of the message opens the list of slash commands, with what each one does, narrowing as you type. tab or enter takes the highlighted one. The same picker completes @path anywhere in the line.
• esc closes the picker, interrupts generation, or clears the input when idle.
• up / down move in the picker, then between the lines of a multi-line message, and through input history when there is only one line.
• Mouse wheel, pgup / pgdn scroll the transcript.
• ctrl+y copies the last reply to the clipboard. thoth asks the terminal to do the copying (OSC 52), which works over ssh and inside tmux and needs no clipboard program; a terminal that does not answer it copies nothing and says nothing, so if the paste comes up empty, use ctrl+t instead.
• ctrl+t hands the mouse back to the terminal, so click-and-drag selects text the way it does everywhere else and your usual copy key works. The scroll wheel belongs to the terminal while this is on; ctrl+t again gives it back to thoth. shift while dragging does the same thing without the key, in the terminals that support it.
• shift+tab cycles how much thoth asks before it acts. The current mode is in the status line.
• ctrl+o expands or collapses long tool outputs.
• y / a / s / n answer permission prompts: once, always, skip this step and carry on, or no and stop.
• up / down and enter move through thoth's options and take one; 1-9 picks one straight off, the last row lets you write your own answer, and esc lets thoth decide.
• ctrl+c quits.

Slash commands

command	effect
/config	edit the config profiles and switch between them (/cfg)
/undo	put back the files the last request changed, /undo list shows what is there
/copy	copy the last reply to the clipboard, /copy all the whole conversation
/clear	reset the conversation (the system prompt is rebuilt)
/compact	summarize the conversation to free context space
/recap	load the previous session's summary into context
/memory	show project memory, /memory clear wipes it
/allow	list what is always allowed here, /allow reset clears it
/mode	show or set how much thoth asks: manual, accept edits, auto, plan. /plan is short for the last one
/status	profile, model, server and api, tokens, cost, uptime
/init	analyze the project and generate THOTH.md
/model NAME	switch model, /models lists what the server has
/help, /quit	help and exit

Permissions

Writing files, editing them, shell commands, web_fetch, remember and reading a file from outside the working directory all ask first. Reads inside the project do not.

Answering a (always) is scoped, not a blanket grant: for shell it allows that one program (cargo, git, ...), for web_fetch that one host, and for reading or writing a file outside the working directory the directory it sits in, so one look at a dotfile does not open the whole disk. The grant is saved in ~/.thoth/projects/<key>/allow.json and survives restarts, so review it with /allow now and then. Auto-approved actions still print the full command line and the full diff.

Modes

shift+tab cycles four of them, and /mode names one directly. The mode lasts for the session and is never saved: a mode turned on for a sandbox must not still be on tomorrow against a real repository.

mode	what happens
manual	the default. Every change and command asks first
accept edits	changes to files go through; the shell and the network still ask
auto	nothing asks
plan	nothing is changed at all

accept edits stops at the shell on purpose: a file change is shown as a diff and /undo puts it back, and a command is neither.

In plan mode the tools that write are refused before they run, and the model is told to describe what it would do instead. When it answers, thoth asks what to do with the plan: carry it out with edits accepted, carry it out asking each time, or keep planning. Choosing one of the first two switches the mode and sends the plan back to be carried out, so there is nothing to retype.

When thoth asks you to choose

The model can put a question on screen with two to nine options when the task has a fork in it that only you can settle. The options are listed under the input: up/down move through them, enter takes the highlighted one, and 1-9 picks one straight off.

The last row is not one of the model's options. It is there for when none of them is what you want: take it and the input box opens, you write the answer in your own words, and enter sends that instead. The model is told plainly that you took none of its options, so it does the thing you asked for rather than the offer yours sounded closest to. esc while writing goes back to the list, and anything you had half-typed when the question arrived is put back afterwards.

esc on the list hands the decision back, and the model is told to take whichever option changes the least and say which one it took. In -p mode there is nobody at the keyboard, so the question is printed and answered for you rather than hanging.

Editor integration

Install thoth-for-vscode and thoth knows your active file, the selected lines and text, and the Problems panel. That context is attached to each request, and the model can also call a problems tool after editing to see if errors cleared. It works through small state files in ~/.thoth/ide/; nothing is sent anywhere.

Without the extension, on Windows, thoth falls back to reading editor window titles. That only reveals which file is open, not selections or diagnostics.

The status bar shows ctx 12.3k/32.8k (37%) (context used / window size), out (tokens generated this session), the running cost when the profile has prices, and the current editor file. While the model works, the line above the input shows a spinner and the elapsed time.

Memory and recap

.thoth/memory.md lives in the project. The model saves durable facts there with its remember tool (conventions, decisions, gotchas) and they are loaded into the system prompt every session. Commit the file or gitignore .thoth/, whichever fits your repo.

~/.thoth/projects/<key>/ lives in your home directory, like Claude Code's ~/.claude/projects, and never touches the repo. It holds last-session.md (a summary written on every compact, loaded with /recap), session.json (the full transcript for --continue) and allow.json (the permission allowlist). The transcript contains whatever the tools printed, so treat it as you would your shell history; delete the directory to wipe it.

Context management

thoth auto-compacts at 2/3 of the window. On Ollama it knows the window because it sets it; on every other api it goes by context_window in the profile, and without one it never compacts on its own, so run /compact yourself. If generation hits the limit mid-answer it compacts and continues.

Identical repeated tool calls get blocked, and a read-only call repeated with the same arguments replaces the older copy in the context rather than adding a second one. After 40 agent steps it pauses and asks you to say "continue"; raise max_turns in the profile if your tasks routinely need more.

Project instructions

At startup the system prompt includes a scan of the working directory (top-level files plus detected stack, e.g. Bun/TypeScript/Rust) and your project instruction file: THOTH.md (what /init generates), AGENTS.md, or CLAUDE.md, whichever exists first. If the file is just a short pointer to one of the others, thoth follows it.