SupaTerra Docs

Introduction

SupaTerra is an AI coding agent that runs in your terminal. You describe a task; it reads your project, edits files, runs commands, and tells you what actually happened.

It talks to Claude through the Anthropic API with your own key. There is no SupaTerra server in between: requests go from your machine straight to api.anthropic.com (or a gateway you choose with baseURL).

• One file to install. Each release is a single executable built with bun build --compile. No Node, Bun or Python needed.
• Asks before it changes anything. Reading is free; writing files and running commands go through a permission gate.
• Seven local tools. read_file, list_dir, glob, grep, edit_file, write_file, bash, plus optional server-side web_search.
• Streams everything. Text appears as the model writes it, with one compact line per tool call.
• Scriptable. supaterra run "…" prints the answer and exits with a meaningful code.

Installation

Download the archive for your platform from the GitHub Releases page, unpack it, and put the executable on your PATH. Every release also ships SHA256SUMS.txt so you can verify the download.

Install the binary

# unpack and move the exe somewhere on your PATH
Expand-Archive supaterra-windows-x64.zip
Move-Item .\supaterra-windows-x64\supaterra-windows-x64.exe C:\Tools\supaterra.exe
# add C:\Tools to PATH (once), then open a new terminal
supaterra --version

tar -xzf supaterra-darwin-arm64.tar.gz
chmod +x supaterra-darwin-arm64
sudo mv supaterra-darwin-arm64 /usr/local/bin/supaterra
# only if Gatekeeper refuses to open it
xattr -d com.apple.quarantine /usr/local/bin/supaterra
supaterra --version

tar -xzf supaterra-linux-x64.tar.gz
chmod +x supaterra-linux-x64
sudo mv supaterra-linux-x64 /usr/local/bin/supaterra
supaterra --version

Run from source

You need Bun 1.2 or newer.

git clone <repo-url> SupaTerra
cd SupaTerra
bun install
bun run dev              # same as the binary, straight from src/
bun run dev -- --help    # pass flags after --

To produce your own executables, see Building binaries.

API key

SupaTerra uses your own Anthropic API key. Create one at platform.claude.com, then either store it with login or provide it through the environment.

Store it with login

supaterra login

1. Paste the key. Input is hidden while you type.
2. It is saved as apiKey in ~/.supaterra/config.json. Other settings in that file are kept.
3. SupaTerra checks the key by listing one model. If the check fails you see the API error and the command exits with code 1. The key stays saved, so run login again to replace it.

A key that does not start with sk-ant- is saved anyway, with a warning. login needs an interactive terminal; in CI use the environment instead.

Use the environment

export SUPATERRA_API_KEY=sk-ant-...     # wins over everything
# or the variable the Anthropic SDK already knows
export ANTHROPIC_API_KEY=sk-ant-...

The key is looked up in this order: SUPATERRA_API_KEY, then ANTHROPIC_API_KEY, then apiKey in the config file. If none is set, SupaTerra still tries the credentials the Anthropic SDK can find on its own (for example ANTHROPIC_AUTH_TOKEN). If that also fails, an interactive terminal walks you through login; a non-interactive one exits with No API key. Set SUPATERRA_API_KEY or run `supaterra login`.

Quickstart

1. Save your key

   Run supaterra login and paste the key.

2. Open a project

   The folder you start in becomes the agent's working directory.

   cd ~/projects/shop-api
   supaterra

3. Describe the task

   Write it the way you would to a colleague, in any language. The agent answers in the language you use.

   ❯ parsePrice in src/utils.ts returns NaN for "€1.299,99". fix it and add tests

4. Approve what it wants to change

   Before an edit or a command you get a prompt. Press y to allow once, n to refuse, a to allow that tool for the rest of the session.

   ⚠ edit_file wants to modify files:
     edit src/utils.ts
   [y] yes  [n] no  [a] always (edit_file, this session) ›

5. Read the result

   The agent runs your tests through bash and reports the real outcome, including failures. A gray line shows the turn's duration and output tokens so far.

Interactive sessions

Running supaterra with no command opens a session in the current directory. The banner shows the version, model, effort and working directory, and whether write and shell calls will ask for permission.

Reading the output

• Text streams in as markdown rendered for the terminal: headings, lists, quotes, fenced code with a language label, inline code, bold, italic, strikethrough and links.
• Each tool call is one line: ⚙ grep /parsePrice/ in *.ts, followed by ✓ 4 lines or a red ✗ with the first line of the error. Calls slower than a second show their duration.
• A spinner on stderr shows what is happening: thinking, preparing edit_file (1,240 chars), running bash, searching the web.
• With --thinking (or /thinking) the model's summarized reasoning appears dimmed, prefixed with ┆.
• With --verbose the first 20 lines of every successful tool result are printed under its summary line.

One-shot & scripting

supaterra run runs a single prompt to completion, prints the answer, and exits. The run keyword is optional: any words that are not a known command are treated as the prompt.

supaterra run "explain the structure of this repo"
supaterra "explain the structure of this repo"        # same thing
echo "summarize README.md" | supaterra run            # prompt from stdin
supaterra run -y "add unit tests for src/utils.ts and run them"
supaterra run -C ../api -m claude-sonnet-5-5 -e medium "list the HTTP routes"

Non-interactive runs

A run is interactive only when both stdin and stdout are terminals. Piping input in or redirecting output (> out.md) makes it non-interactive, and then nobody can answer a permission prompt:

• Read-only tools still run.
• edit_file, write_file and bash are denied, and the model is told so. A gray notice on stderr says so up front.
• Pass --yolo to allow them. Writes outside the working directory are still denied, because they always need a human to say yes.

The answer goes to stdout; the spinner, notices and the final usage line go to stderr. That keeps supaterra run "…" > answer.md clean.

Exit codes

Example: GitHub Actions step

- name: Ask SupaTerra for a changelog entry
  env:
    SUPATERRA_API_KEY: ${{ secrets.SUPATERRA_API_KEY }}
  run: supaterra run -e medium "write a one-paragraph changelog entry for the last commit" > entry.md

Slash commands

Inside a session, a message that starts with / is a command for SupaTerra, not for the model. Changes made with commands last for the session only; make them permanent with supaterra config set.

Saving sessions

/save writes the full message history, token usage, model and working directory to ~/.supaterra/sessions/<id>.json. Ids look like 20261024-153012-k3x9: the local date and time plus four random characters. Saving again overwrites the same file and keeps its original creation time. /clear starts a fresh id.

❯ /save
saved 20261024-153012-k3x9 → ~/.supaterra/sessions/20261024-153012-k3x9.json
❯ /sessions
  20261024-153012-k3x9  claude-opus-5-5  parsePrice in src/utils.ts returns NaN for "€1.299,99"…
❯ /resume 20261024-153012-k3x9
resumed 20261024-153012-k3x9 (14 messages): parsePrice in src/utils.ts returns NaN…

A session's title is the first 60 characters of its first message. /resume restores the messages, the usage counters and the model. It also moves back to the saved working directory if that folder still exists; otherwise it warns and stays where you are.

Context & compaction

Every request sends the whole conversation, including tool results. Long sessions eventually approach the model's context window. Compaction replaces the history with a summary the model writes for itself: goals, decisions, files touched, what was verified, open problems and the next step.

• Manually: /compact at any time. The summary is printed so you can check it.
• Automatically: when a request no longer fits, SupaTerra compacts once and retries the turn. This covers both the API rejecting an oversized prompt and the model running out of room mid-reply.
• Even when the history itself is too big to summarize: SupaTerra retries with a shortened plain-text transcript (long tool outputs cut, oldest parts dropped), then a shorter one.

If the context is still exceeded after one compaction, the turn stops with Use /clear to start over.

Usage & cost

/cost prints the running totals for the session. One-shot runs print the cost line to stderr at the end when stderr is a terminal.

❯ /cost
requests     14
input        38,210
output       4,112
cache read   31,900
cache write  6,310
cost         ~$0.2900

The cost is an estimate from a price table built into SupaTerra, matched on the model id, with cache writes priced at 1.25× input. It uses the model that is active when you run /cost for the whole session. An unknown model shows unknown pricing. Your Anthropic Console is the source of truth for billing.

SupaTerra keeps the system prompt and tool list byte-identical between requests so prompt caching keeps hitting; that is what the cache read line measures.

Tools overview

The model works through tools. SupaTerra validates every call's input against a schema before running it, and an invalid call is sent back to the model as an error instead of being executed.

Paths are relative to the working directory unless absolute; ~ expands to your home folder. Directory walks skip node_modules, .git, .hg, .svn, dist, build, out, .next, .nuxt, .turbo, .cache, coverage, __pycache__, .venv, venv, target and .idea.

Reading & searching

These four tools never ask for permission. They can read any path you can, including outside the working directory.

read_file

Returns line-number⇥text rows and, if the file continues, a footer like [1,240 more lines; total 3,240]. A file with a NUL byte in its first 8,000 bytes is reported as binary instead of being dumped.

list_dir

One parameter, path (default: working directory). Returns a header with counts, then folders (with a trailing /) and files with sizes, each sorted by name. Ignored folders are left out.

glob

Returns up to 500 paths, most recently modified first, then a count of the rest. Skips node_modules and .git, does not match dotfiles, and does not follow symlinks.

grep

Output is file:line: text, with lines longer than 300 characters cut. Binary files, files over 2 MB, ignored folders and hidden folders are skipped.

Editing files

edit_file

The edit is refused, and the file is left untouched, when:

• old_string is empty or identical to new_string;
• old_string is not found. If it would match after normalizing line endings, the error says the file uses CRLF so the model re-reads it instead of guessing;
• old_string appears more than once and replace_all is not set.

On success it reports the number of replacements, for example Edited src/utils.ts: 1 replacement.

write_file

Parameters path and content. Creates missing parent folders, writes the whole file, and reports Created or Overwrote with the line count. The model is told to prefer edit_file for small changes.

bash

Which shell

The chosen shell is named in the system prompt so the model writes commands for it.

How commands run

• In the working directory, with no stdin. Anything that waits for input hangs until the timeout, so the model is told to use non-interactive flags.
• With extra environment variables SUPATERRA=1, NO_COLOR=1 and CI=1 (unless CI is already set), so most tools print plain output.
• On timeout or Ctrl C the whole process tree is killed: taskkill /T on Windows, the process group on macOS and Linux.
• After the shell exits, output is collected for at most one more second. A background job that keeps the pipes open cannot hang the agent.

The result contains stdout, then [stderr] output, a [timed out after … ms] marker when relevant, and always [exit code N].

web_search

An Anthropic-hosted tool: the search runs on Anthropic's servers, not on your machine, and results come back inside the model's reply. It is off by default and limited to 8 searches per request.

supaterra -w                          # this run
supaterra config set webSearch true   # always

Inside a session, /web toggles it. While it runs, the spinner shows searching the web. Web search may be billed separately by Anthropic.

Permissions

Each tool has a level: read, write or exec. The gate decides per call:

1. read tools always run.
2. A write outside the working directory always needs a human to say yes, even in yolo mode.
3. Otherwise the call runs if auto-approve is on (--yolo, /yolo, autoApprove) or you answered a for that tool earlier in the session.
4. If nobody can answer (non-interactive run), the call is denied.
5. Otherwise you are asked.

A denial is sent to the model as The user declined this tool call. Do not retry it unchanged; adjust the approach or ask. The system prompt tells it to treat that as a decision, not an obstacle.

Untrusted repositories

A repository you just cloned can contain files that SupaTerra reads automatically. Two of them matter:

.supaterra.json is restricted

A project config may only set model, effort, maxTokens, showThinking, webSearch and maxIterations. Everything else in it is ignored, in particular:

• baseURL: otherwise a repo could send your API key to its own server;
• autoApprove: otherwise a repo could switch off permission prompts and run commands;
• apiKey and fallbacks.

An invalid effort value is dropped too.

Instruction files are part of the prompt

SUPATERRA.md, AGENTS.md or CLAUDE.md in the working directory is added to the system prompt verbatim. In a repository you do not trust, read that file first, keep permission prompts on, and look at each command before you approve it.

Keys & local data

Set SUPATERRA_HOME to move both somewhere else. Nothing else is written outside your project, and nothing is sent anywhere except the Anthropic API (or your baseURL).

• On shared machines, chmod 600 the config file or keep the key in an environment variable.
• The system prompt tells the model not to print .env files or credentials, but read tools can open any file you can. Do not rely on the prompt as a security boundary.
• config and /config always mask the key as ***.

Config file

Settings live in ~/.supaterra/config.json (print the path with supaterra config path). Edit it by hand or with config set, which validates the key and converts true/false and whole numbers.

supaterra config                      # effective config, key masked
supaterra config get model            # one value
supaterra config set effort xhigh
supaterra config set webSearch true
supaterra config path

All settings

Per-project overrides

Put a .supaterra.json in the project root to change defaults for that folder. Only the safe keys are honored (see Untrusted repositories):

{
  "model": "claude-sonnet-5-5",
  "effort": "medium",
  "maxIterations": 30
}

Precedence

Each layer overrides the ones below it. Hover a layer to lift it out of the stack.

Slash commands like /model sit on top of all of these for the rest of the session, and are not saved.

Environment variables

A .env.example in the repository shows the common ones. SupaTerra does not load .env files itself; export the variables in your shell (Bun loads .env automatically when running from source).

CLI reference

supaterra [options]                     # interactive session
supaterra [options] run <prompt...>     # one-shot
supaterra [options] <prompt...>         # one-shot, run keyword omitted
supaterra login
supaterra config [get <key> | set <key> <value> | path]
supaterra version | help

Flags are strict: an unknown flag prints the error and the help text and exits with code 2.

Models, effort & thinking

Any model id the API accepts works with --model. SupaTerra turns on extra features only for models known to support them:

Choosing an effort

Effort trades thoroughness for speed and tokens. low and medium suit quick questions and small edits; high (default) is a good general setting; xhigh and max are for hard debugging and large refactors where you would rather wait than retry.

When the model declines

If a request is refused, the turn stops with The model declined to continue and the reason the API gives. With fallbacks on and a supported model, the API may instead let a fallback model continue; you then see … declined this request; … continued.

Project instructions

Put house rules for the agent in a markdown file in the project root. SupaTerra uses the first one it finds, in this order: SUPATERRA.md, AGENTS.md, CLAUDE.md. Up to 40,000 characters are appended to the system prompt under Project instructions.

# Project instructions

- Package manager is pnpm. Run tests with `pnpm test`, types with `pnpm typecheck`.
- Never edit files under src/generated/; run `pnpm codegen` instead.
- API handlers live in src/routes/, one file per resource.
- Before saying a change works, run the tests for the files you touched.

Good instructions are short and concrete: commands to run, folders to avoid, conventions that are not obvious from the code. The file is re-read when you change folders with /cwd, and read fresh at the start of every run.

The agent loop

One message from you can take many requests to the API. SupaTerra repeats the loop below until the model stops asking for tools.

How a turn ends

Two safety nets: after maxIterations tool rounds (default 60) SupaTerra stops with Send another message to continue., and if a tool call's streamed input is not valid JSON the request is re-sent, at most twice.

The system prompt

It names the tools, the working directory, OS, architecture and shell, and sets the working rules: look before changing, prefer edit_file for targeted edits, run the project's own checks and report real results, respect denials, avoid destructive commands unless asked, keep secrets out of output, lead answers with the result, cite code as path:line, and reply in your language. It contains no timestamps or random ids so it stays identical between requests and keeps the prompt cache warm.

Building binaries

scripts/build.ts cross-compiles single-file executables with bun build --compile --minify. It works from any OS; Bun downloads the target runtime on first use.

bun run build                                  # all five targets into dist/
bun run build:win                              # windows-x64
bun run build:mac                              # darwin-arm64, darwin-x64
bun run build:linux                            # linux-x64, linux-arm64
bun run scripts/build.ts --only linux-arm64 --outdir out

The Windows build gets a title, publisher, version and description, plus an icon if assets/icon.ico exists. The script prints a size and timing table and exits with 1 if any target failed.

CI and releases

bun run typecheck && bun test
git tag v0.1.1 && git push origin v0.1.1      # starts the release workflow

Adding a tool

Tools live in src/tools/, one file each, defined with defineTool and a zod schema. The schema is converted to JSON Schema for the API and also validates every call before it runs.

import { z } from "zod";
import { defineTool } from "./types.ts";
import { displayPath, resolvePath } from "./paths.ts";

export const wordCountTool = defineTool({
  name: "word_count",
  description: "Count the words in a text file.",
  permission: "read",                      // read | write | exec
  schema: z.object({
    path: z.string().describe("File to count"),
  }),
  summarize: (i) => `count words in ${i.path}`,   // the one-line UI summary
  async run(input, ctx) {
    const abs = resolvePath(ctx.cwd, input.path);
    const file = Bun.file(abs);
    if (!(await file.exists())) return `Error: file not found: ${displayPath(ctx.cwd, abs)}`;
    const words = (await file.text()).split(/\s+/).filter(Boolean).length;
    return `${words} words in ${displayPath(ctx.cwd, abs)}`;
  },
});

1. Register it

   Add it to ALL_TOOLS in src/tools/index.ts. Tools are sent sorted by name, so the order there does not affect caching.

2. Mention it in the system prompt

   src/system-prompt.ts lists the tool names in its first paragraph; add yours.

3. Return errors as text

   Start the result with Error: to mark it as failed. Thrown exceptions are caught and reported the same way.

4. Test

   Run bun run typecheck and bun test.

Troubleshooting

Error messages