You know what you want to do. You just don’t remember whether it’s tar -xzf or tar -zxvf, or why the sed -i that worked on a Linux server fails on your Mac.

The usual fix is to paste the question into a chat website. That works, but it sends your file paths, hostnames and project names to someone else’s server, and the answer may still be written for a different system than yours.

ThetaTerm takes another route. It runs on a small model on your own machine, and it asks before anything runs:

$ tterm -q "list files in this directory, largest first"
$ ls -lS .
Run it? [Y/n]:

This post explains how a model small enough to run on a laptop gets the command right, and why you stay the final check.

What small models get wrong

Small models are good at naming tools. Ask how to find large files and they’ll say find or du. What they’re bad at is options, because options differ between the three families of command-line tools:

Userland	Where you meet it
GNU	Most Linux distributions
BSD	macOS
BusyBox	Alpine, containers, small devices

A command that works on one can fail, or quietly do something different, on another. sed -i is the classic: GNU accepts it bare, BSD wants an argument after it.

A model can’t reliably remember which flavor you have. ThetaTerm doesn’t ask it to.

Give the model your own documentation

Instead of relying on memory, ThetaTerm puts the answer in front of the model:

1. Describe the system. At start-up it builds one line, such as macOS 26.6.2, BSD userland, zsh shell. Every prompt starts with it.
2. Choose programs. The model suggests up to three programs that could do the task. ThetaTerm takes the first two that are actually installed.
3. Excerpt their man pages. It reads each program’s installed man page and keeps the synopsis plus the option entries that share the most words with your request, capped at 3,500 characters so a small model’s context isn’t flooded.
4. Write the command. With your system’s real documentation in view, the model writes one command.
5. Check it. The command must be valid syntax for your shell, and every program it calls must be installed. If not, the model sees the error and tries again, up to three attempts in total.

Choosing two programs rather than one matters more than it sounds. Asked for an MD5 checksum, a small model suggests shasum before md5. With both man pages in front of it, it writes md5.

ThetaTerm never runs a program to read its docs. Not every program honours --help, and running an unknown program just to learn about it is a risk in itself. It reads man pages only.

You are the safeguard

The checks catch commands that can’t work. They don’t judge whether a command is a good idea: rm -rf . is valid syntax and passes.

So the main protection is you, reading the command before you answer. ThetaTerm always shows the full command and waits.

It adds one guard on top. Most requests are about the directory you’re in, so a command that reaches further, through sudo, $HOME, an absolute path, ~ or .., is more likely to be a mistake. Those commands are:

• shown in red, with the reason
• defaulted to no
• asked about even if you passed -y to skip confirmation

This guard is a pattern match on the words of the command, not a sandbox. It catches a model’s honest mistakes, like writing /tmp/out when you meant ./out. It won’t catch a command built to hide where it reaches. Once a command runs, it has all the permissions you have.

What leaves your machine

With the default setup, nothing. ThetaTerm talks to any server with an OpenAI-compatible API, and the default is gemma4:e4b on Ollama, running locally.

Each request sends the model your request, the one-line system description and the man page excerpts. File contents and command output are never sent. If you point ThetaTerm at a hosted API instead, those three things go to that provider, and nothing more.

Settings are read only from your own config directory, never from a .env in the folder you’re working in. That stops a cloned repository from quietly redirecting your API key to its own server.

There’s no subscription and no per-token bill, because the model runs on your hardware.

It works for AI agents too

tterm-mcp is an MCP server that lets agents such as Claude Code ask ThetaTerm about your system, an installed program’s documentation, or whether a command will work. None of its tools runs a command. The agent runs what it decides to, under its own permission prompts.

Try it

You need macOS or Linux, uv, and a model of at least 3 billion parameters. Smaller ones write wrong commands too often.

ollama pull gemma4:e4b
uv tool install thetaterm
tterm -q "find files modified in the last 2 days"

ThetaTerm is open source under Apache-2.0. The code, the tutorial and the full safety model are on GitHub.

Read every command before you run it. The model can be wrong; that’s why it asks.