Skip to content

Getting Started

SolenopsisCampo edited this page Nov 8, 2026 · 1 revision

Getting Started

This page takes you from a fresh install to a first chat and a first research run.

Run it from your project folder

Launch the harness from the directory you want to work in, not from the harness's own. The directory you launch from is the project: workspace trust, the .venastine/ folder, where /init writes, and project-scoped memories all follow it. Launching from the install tree would make the harness its own project, and that is refused at startup with exit code 2.

cd ~/my-project
venastine --tui
Install Line-based CLI Full-screen TUI
GitHub installer, npm, yarn, bun, pnpm venastine venastine --tui
A clone python /path/to/clone/main.py python /path/to/clone/main.py --tui

To name the project from anywhere instead, set AGENT_WORKSPACE=~/my-project for the launch.

The line-based CLI is the default and is not going away. The TUI is a nicer shell over the same code. Most of the TUI's commands also work in the CLI, and the CLI's /help says where to find the rest.

On an npm-family install, the very first launch asks before building the harness's Python environment. That happens once.

Connect a model

Without a model provider key every model call fails, and both shells say so at launch.

In the TUI, /connect sets it up for you:

Command What it does
/connect Lists the providers it knows
/connect <name> Asks for that provider's API key in a masked prompt and saves it, readable only by you
/connect custom <NAME> <url> Adds any OpenAI-compatible endpoint, a local one included
/connect huggingface Signs in with your Hugging Face account instead of a key: a code to confirm on huggingface.co
/connect openrouter Signs in with OpenRouter, which makes a key you can delete at openrouter.ai/keys
/connect chatgpt Signs in to a ChatGPT Plus or Pro plan. Local installs only; then /model CHATGPT <model>
/disconnect <name> Asks first, then blanks the key and says where to revoke it, or signs you out of the ChatGPT plan

The next turn uses the new key, with no restart.

In the CLI, or to do it by hand, put the key in providers.json. A clone starts from providers.json.example. The npm and GitHub installs read ~/.config/venastine/providers.json, unless the directory you are in has its own.

Then choose a model. The shipped default is Anthropic's claude-sonnet-5. To use another, run /model <PROVIDER> <model> in the TUI, for example /model OPENAI gpt-5.1, and it is remembered for the next launch. For one launch only, pass --provider and --model. The provider is the entry's name in providers.json: ANTHROPIC, OPENAI, GOOGLE, DEEPSEEK, OPENROUTER, and so on.

The trust prompt

A repository can carry content the harness would load into the model's instructions: a root AGENTS.md and a .venastine/ folder of agents, skills, settings and MCP servers. The first time you launch in such a directory, you are shown what it contains and asked once. That includes the file list, settings.json and mcp.json verbatim, the opening of AGENTS.md, and every agent's and skill's description.

Until you say yes, that content is absent, not loaded and disabled. Trust is tied to the folder's path and its contents, so it is asked again when the files change. A folder with neither AGENTS.md nor .venastine/ has nothing to trust and is silent. For scripts and CI, --trust-project grants it without asking and prints what it trusts.

Your first chat

Type a message. A turn prints as it runs: the model's reasoning, what it said, and a line for each tool call as it starts.

  • Stopping a turn: press Escape in the TUI. In the CLI, press Ctrl+C twice within two seconds; the first press only says so. A tool call that is already running finishes first.
  • Quitting: /quit, or Ctrl+Q in the TUI. Ctrl+C twice also quits the TUI, and Ctrl+C or Ctrl+D at the CLI prompt exits.
  • Coming back: Ctrl+T or /threads in the TUI lists your conversations, and /resume <thread-id> opens any one by id. The CLI prints the thread id after the first response, and --thread <id> resumes it. Resuming replays the conversation, so you can see what you are picking up.

Out of the box the model can search the web, fetch pages, search arXiv and use six maths tools. It cannot read your files or run commands until you turn those on; Tool Permissions says how and what each one does.

Your first research run

The research mode runs a ten-pass pipeline that writes an answer, fact-checks it against sources, critiques it, and scores each claim.

venastine --mode research "does the claim about X hold up?"

In the TUI, type /research <query>. A ten-pass run takes minutes. It reports as it goes, and in the TUI a sidebar tracks the passes and a running tally of the tiers. /claims or Ctrl+L shows every claim with its tier and score breakdown, during the run as well as after it.

Every run writes a folder, output/<run_id>/, in your project. report.md is the final report, and the numbered files beside it are each pass's own output, so you can check how a score was reached.

Tier Meaning
HIGH score at least 0.8
MEDIUM score at least 0.55
LOW score at least 0.3
UNVERIFIED below 0.3, or any factual claim that could not be grounded, whatever its score
UNVERIFIED_COVERAGE not a claim: something the answer never addressed

The README explains how the pipeline works, and how a run can have a different model check the first one's work.

There is no default spend ceiling. max_token_budget in settings.json caps what each chat turn and each research pass may bill. Limits set at your provider are the stronger control.

Commands to know

These are the TUI's. The CLI has most of them (/connect, /disconnect, /config and /copy are TUI-only), and its /help lists its own.

Command What it does
/help Lists every command
/model [[PROVIDER] name] Switches provider and model; remembered for the next launch
/connect, /disconnect Adds or removes a provider key or sign-in
/agent [name|default] Runs the next turns as an agent, such as plan or build. Shift+Tab cycles through a few
/skill [name] Pins a skill's instructions into every following turn
/threads, /resume, /new Lists, reopens or starts conversations
/memories, /forget Lists or deletes durable memories
/config [key] [value] Browses and changes the harness's own settings in config.yaml
/copy Copies the last answer, the report or the conversation; --file <path> writes it to a file
/quit Leaves

The README has the full TUI command list and the CLI flag reference.

Next steps

Checked against release 0.3.12 (commit f33ef8a). The README's Running it section is the reference.

Clone this wiki locally