Repository navigation
Getting Started
This page takes you from a fresh install to a first chat and a first research run.
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.
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.
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.
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
/threadsin 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.
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.
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.
- Tool Permissions: turn on file access or the shell, and see what each tool can do.
- Writing Agents and Skills: add your own agents and skills.
- MCP Servers: connect third-party tools.
Checked against release 0.3.12 (commit f33ef8a). The README's Running it section is the reference.
Start here
Guides
Reference