Repository navigation
FAQ
You launched it from the harness's own folder. The directory you launch from is the project, and the harness may not be its own project. cd to the folder you want to work in and launch from there, or name it with AGENT_WORKSPACE=~/my-project. See Getting Started.
Python 3.11 or newer, with its venv module, for every install. The npm, yarn, bun and pnpm routes also need Node.js 18 or newer for the launcher. An older Python is refused at install time.
An unknown key in settings.json stops the harness on purpose, naming the file and the key, so a typo never reads as a setting. Fix the spelling, or check the list of every key.
Five well-formed keys are refused by name, with a reason, because a project's settings.json outranks yours and a cloned repository must not be able to set them: shell_approval_mode, ensemble_models, critic_model, embedder_model and research.granted_tools. Set the first four in config.yaml (or with /critic and /embedder). Grants exist only as per-run flags.
No provider key is set up yet, and both shells say so at launch. In the TUI, run /connect; otherwise add the key to providers.json. See Getting Started.
read, view_image, write, edit, shell and the shell session tools are off in a fresh install, and only you can turn them on, in config.yaml or with /config in the TUI. Tool Permissions explains each one first.
-
Relaunch.
config.yamlis read once, at startup. -
view_imageis offered only when the provider is markedaccepts_imagesinproviders.json, and never in a research pass. -
shellrefuses any command that may run code until Docker or Podman is running, unless you enable the weaker fallback. See Shell and Sandbox. -
An active agent may leave the tool out of its
allowed_tools./agent defaultgoes back to no agent. - A piped CLI run cannot ask you anything, so tools that need approval are hidden from it entirely.
They run without asking only inside the workspace, which by default is the workspace folder in the directory you launched from. Everything else asks, including the rest of your project. To let them work across the project without a prompt per file, launch with AGENT_WORKSPACE set to the project folder, knowing that the model can then change any file there without asking. A path through a .venastine folder is always refused.
Use forward slashes. A backslash counts as an escape character, so cat sub\dir\notes.txt is sent to the container, where that path does not exist. cat sub/dir/notes.txt works.
Under the shipped tiered mode, only a read-only command whose arguments all stay inside the workspace runs without asking. An argument that looks like a path outside it, a quoted or escaped argument, or a program not on the inert_commands list each makes it ask. Shell and Sandbox explains why the check is that strict.
They load only after you trust the project, and trust is tied to the files' contents, so it is asked again after they change. If you answered no, or the run had no terminal to ask in, they stay absent. In a script, --trust-project grants it and prints what it trusts.
Work through the checklist. The usual causes are an agent in a subfolder of agents/, frontmatter that does not start on the first line, a name that a built-in already uses, or no relaunch after the edit. Every file the loader skips is logged with the reason.
-
pnpm puts every install in a new directory, so
config.yamledits do not survive an update. Use npm, yarn or bun if you rely on them. - npm merges your values back after an update, except an edit made after your last session that you never launched before updating.
- The GitHub installer carries them forward on every rerun.
settings.json and everything else in ~/.config/venastine survive every update.
PRIVACY.md lists everything stored on your machine, what leaves it and when, and how to delete each part. There is no telemetry. venastine --venastine-doctor prints where this install keeps its database, log and keys.
venastine --venastine-doctor prints its location. In a clone it is logs/app.log in the directory you launched from. Set AGENT_LOG_LEVEL=DEBUG for more detail. Secret-shaped strings are redacted on the way into the file.
There is no default spend ceiling. max_token_budget in settings.json caps the tokens billed by each chat turn, each research pass and each /init, so a ten-pass run can bill up to ten times that figure. Spending limits set at your provider are the stronger control: they see the same bill and cannot be skipped by a code path.
In the CLI, press Ctrl+C. A run is saved pass by pass, so one you stop, or one that crashes, still leaves its record up to the last pass it finished.
UNVERIFIED covers a claim scoring below 0.3, any factual claim the run could not ground against a source whatever its score, and a claim still flagged after two rounds of revision. It means "not checked", not "false". Open the claim with /claims (or Ctrl+L) to see its score breakdown and sources.
Use /copy: the last answer by default, or report, claims, conversation or all. Some terminal multiplexers drop clipboard writes silently, so /copy --file <path> is the route that always works. Shift+drag usually lets your terminal select text directly.
- A bug, a missing feature, or a doc that is wrong: open an issue.
- A security vulnerability: never in a public issue. Report it privately, as SECURITY.md describes.
Checked against release 0.3.12 (commit f33ef8a). Where this page and the README disagree, the README is the reference.
Start here
Guides
Reference