@vextlabs/theron-cli

v0.3.0

Published

17 days ago

Theron CLI — an agentic coding assistant that verifies its own output. Runs an agentic tool loop in your terminal, then runs post-turn checks (types, tests, lint, arithmetic, citations) over the files it touched; blocking failures feed the next turn so it

Theron CLI

An agentic coding assistant that verifies its own output, from Vext Labs. It runs an agentic tool loop in your terminal — reading, editing, and running code on your machine. The model streams its answer first; then, after the turn, the CLI runs a suite of verifier kernels (types, tests, lint, arithmetic, citations) over the files it touched. Any blocking failures are prepended to your next turn as a system note, so the model self-corrects on the following turn without you copy-pasting the error.

npm install -g @vextlabs/theron-cli
theron onboard

What makes it different

Most coding CLIs end a turn the moment the model stops talking. Theron CLI adds a grading step after each turn and a switchable domain council on top of the agent loop:

Output verification after every turn. A suite of up to 8 verifier kernels is available; each profile runs its own subset (the default code profile runs 3: typecheck, lint, test_smoke), in parallel (each with a 5s timeout). The file kernels (typecheck/lint/test_smoke) run over the files the model just touched; the text kernels (em-dash, AI-isms, citations, arithmetic) run over the response text itself. The full kernel set: typecheck (real npx tsc --noEmit on touched .ts, parses TSxxxx errors and blocks), lint (flags console.log/debugger/.only/eslint-disable), test_smoke (runs your test:smoke / test:fast or pytest on touched files), style_lint, em_dash_check (blocks every em-dash), ai_ism_check (flags filler like "delve"/"tapestry"/"leverage"), citation_presence (warns when long legal/research/medical output ships no citation), and arithmetic_recheck (re-evaluates asserted X op Y = Z equations and blocks mismatches). These checks run after the turn; blocking issues are auto-prepended to the next turn so the model fixes them on the following response.
A 33-profile domain council. Switch the active persona mid-session with /mode — 6 hand-tuned profiles (code, legal, finance, design, research, writing) plus 27 template-generated baselines, each carrying its own verifier set and tool policy. Read-only profiles (e.g. medical, therapy) drop Write/Edit/Bash entirely.
Stoa signed-receipt cap tool. The built-in Stoa tool reaches any Stoa-registered SaaS capability (send a Slack message, open a GitHub issue, charge via Stripe) and returns the server's signed, cost-stamped receipt — an auditable record of every external action, not a generic bridge. The CLI displays whatever signature algorithm and value the server returns.
One-command import from Claude. theron import-claude <export.zip> reads a Claude data export locally, extracts your voice preferences, recurring proper-nouns, and first-person facts (user messages only — raw conversations never leave your machine), confirms, then uploads just those to Theron memory.

What it does

Streams from theron.tryvext.com and runs an agentic tool loop: each turn the model can call tools, the CLI runs them locally, feeds results back, and loops (up to 20 inner iterations) until the turn ends.
8 local tools execute in your working directory: Read, Write, Edit, Bash, Glob, Grep, LS, and Stoa. Read caps large files, Bash has a 120s default / 600s max timeout with a byte cap, Edit does exact-unique-substring replacement.
Confirmation gating. Write, Edit, Bash, and Stoa prompt (y/N) before running; Read, Glob, Grep, LS never prompt. Pass --yes (or /yolo in-session) to auto-approve. In plan mode (--plan / /plan) those four tools are hard-denied at the executor regardless of --yes, so the run stays strictly read-only.
Onboarding wizard (theron onboard): logs you in, picks your top-3 specialists, installs a cl shell alias, opens Microsoft 365 + Google Workspace OAuth, links the Office add-in sideload, and optionally imports a Claude export — in one flow.

Workflow features

These mirror the day-to-day ergonomics most terminal coding assistants expose. Every one is client-side and works with the existing chat endpoint.

Custom slash commands. Drop a markdown file at ./.theron/commands/<name>.md (project) or ~/.theron/commands/<name>.md (global) and typing /<name> sends that file's body as the turn's prompt. The body supports $ARGUMENTS (the full argument string) and $1, $2, … (whitespace-split positionals); a placeholder with no matching argument expands to empty, and a literal $word is left untouched. An optional --- description: … --- frontmatter line sets the /help blurb and is stripped from the prompt. Project commands override global ones on a name collision; a command whose name collides with a built-in (/clear, /help, …) is rejected at load so it can never shadow the built-in. /commands lists them; /commands reload re-scans without restarting. The substituted text is sent to the model as a prompt — it is never passed to a shell.
Plan mode. Start with --plan, or toggle /plan mid-session. In plan mode the model is sent only the read-only tool subset (Read, Glob, Grep, LS) and any Write / Edit / Bash / Stoa call is hard-denied at the executor before the confirmation/--yes check — so no write can run even under --yes//yolo. A plan-mode instruction is prepended to the turn asking the model to investigate read-only and produce a numbered plan. Type approve (or /plan again) to leave plan mode and restore the normal tool policy.
Session resume. Every interactive session is saved under ~/.theron/sessions/<id>.json, where <id> is a stable hash of the working directory, after every turn (written atomically; capped at 5 MB with oldest-message eviction). theron --continue resumes the most-recent session for the current directory; theron --resume [id] resumes a specific session, or shows a numbered picker when no id is given. /sessions lists saved sessions. /clear resets the on-disk session too. A missing or corrupt session file fails open — the CLI starts fresh rather than crashing.
Headless mode (-p / --print). Run one full agentic turn non-interactively and exit — the prompt comes from the positional argument or, if omitted, from stdin. --output-format text (default) prints just the answer; --output-format json prints a single JSON object {answer, tools_used, verifier, cost, session_id}. No banner, spinner, or chips reach stdout, so the output pipes cleanly. The exit code is 0 on a completed turn and 1 on a stream/tool error. cost is always null: the streaming wire format carries no usage/cost frame, and the CLI never fabricates a number.
@-file references. Write @path/to/file in a prompt and, when the token resolves to an existing readable file inside the working directory, its contents are read and inlined as a fenced block labeled with the path (capped at 32 KB, head kept). Path traversal is refused (@../../../etc/passwd is rejected), absolute paths are not auto-inlined (use the Read tool, which prompts), and likely-secret files (.env*, *credentials*, *.pem, id_rsa, …) and binaries are skipped. A token that doesn't resolve to a file — including a bare @specialist name — is left untouched for the council's @-mention router.
Markdown rendering. --render pretty-prints the assistant's reply once the turn ends (--no-render to disable, /render to toggle). It is on by default for an interactive TTY and forced off when piped, headless, or NO_COLOR is set, so plain text always pipes cleanly. When rendering is on the raw token stream is buffered and the rendered block is emitted exactly once, so the answer is never printed twice.

Project memory (`THERON.md`)

The CLI auto-loads a per-project instructions file and injects it into every turn as authoritative repo context — so the model knows your build command, code style, and house rules without you re-typing them each session.

It walks up from the working directory (up to 8 levels) and, at each ancestor, takes the first of THERON.md, CLAUDE.md, or AGENTS.md that exists. The closest ancestor wins, so a package's file overrides the monorepo root's. Because CLAUDE.md / AGENTS.md are recognized as fallbacks, most repos get picked up with zero setup; add a THERON.md to override just for Theron.
A global ~/.theron/THERON.md (your cross-project house style) loads first, then the nearest project file is appended after it.
Each source is capped at 32 KB (head kept, truncation marked); a missing or unreadable file is silently skipped and never breaks the session.

Quickstart

theron                            # start interactive chat in the current dir
theron "fix the bug in foo.ts"    # one-shot prompt, exits on end-turn (pipeable)
theron --mode legal               # start in the Legal profile
theron --mode list                # see all 33 profiles
theron --yes                      # auto-approve every tool call (yolo mode)
theron --plan                     # plan mode — read-only tools, propose a plan
theron --continue                 # resume the most-recent session for this dir
theron --resume                   # pick a saved session from a list
theron -p "summarize this repo"   # headless: one turn, print the answer, exit
theron -p "list the bugs" --output-format json   # headless, single JSON object
echo "what changed?" | theron -p --output-format json   # prompt from stdin

Top-level commands

| Command | What it does | |---|---| | theron | start interactive chat | | theron "<prompt>" | one-shot mode (runs the prompt, exits, pipeable) | | theron onboard | onboarding + migration wizard | | theron import-claude <zip> | ingest a Claude data export into your memory (parsing is local) | | theron connections | list connected SaaS accounts | | theron login | sign in (stores key in ~/.theron/credentials) | | theron logout | clear stored credentials | | theron --version | print version | | theron --help | full help |

In-REPL slash commands

/help            Show the menu (also lists your custom commands)
/clear           Reset the current conversation (and its saved session)
/yolo            Toggle auto-approve for tool calls
/plan            Toggle plan mode (read-only tools); 'approve' exits plan mode
/render          Toggle pretty markdown rendering of the reply at end of turn
/commands        List custom slash commands; /commands reload re-scans them
/sessions        List saved sessions (resume with `theron --resume <id>` / `--continue`)
/cwd             Show current working directory
/cd <path>       Change working directory
/tools           List available tools
/mode <slug>     Switch domain profile
/mode list       Show all 33 profiles
/suggest         Recommend a profile for what you're working on
/pin <spec>      Pin a council specialist for the next turn (@legal, @code, …)
/unpin           Clear pinned specialists
/cap list        Show registered Stoa caps you can invoke as tools
/status          Show cwd / mode / api / auth / yolo / plan / render / session state
/login           Tells you to exit and run `theron login`
/logout          Clear stored credentials
/connections     List connected SaaS accounts (alias: /integrations)
/bug             Print where to send CLI feedback
/quit            Exit (or Ctrl-C)
/<custom>        Run a command from ./.theron/commands or ~/.theron/commands

In a prompt, @path/to/file inlines a readable file from the working directory (see Workflow features above); @specialist still pins a council member.

Authentication

theron login saves your API key to ~/.theron/credentials (file mode 0600, directory mode 0700). The key is resolved in this priority order (first wins):

--api-key CLI flag
THERON_API_KEY env var
~/.theron/credentials

Anonymous calls work — signing in unlocks higher rate limits. Get an API key at https://theron.tryvext.com/settings/api-keys.

Error handling

Every network path either succeeds, retries, or surfaces a clear error:

Not authorized (401 / 403) — a friendly message telling you to run theron login or check your key.
Network failure — auto-retries with exponential backoff (1s → 2s → 4s, up to 3 retries).
Model busy (408 / 429 / 5xx) — auto-retries on the same backoff schedule.
Stream timeout — 30s connect / 5 min total hard cap; surfaces an interrupted-stream error rather than hanging.
Tool failure — returned to the model as a structured tool result so it can recover; the REPL does not crash.

Malformed tool arguments coming back from the model are repaired before execution (string/double-encoded/special-token-contaminated args are normalized).

Environment

| Variable | Effect | |---|---| | THERON_API_KEY | overrides the stored API key | | THERON_API_URL | overrides the default chat API URL (https://theron.tryvext.com) | | THERON_STOA_BASE | overrides the Stoa cap proxy base (https://theron.tryvext.com) | | NO_COLOR | disables ANSI color output |

Support

Product + docs: https://tryvext.com
Questions, bugs, feedback: email [email protected] or reach us at https://tryvext.com.