Repository navigation
Installation
Every local install needs Python 3.11 or newer, including its venv module. No installer downloads Python for you. The npm, yarn, bun and pnpm routes also need Node.js 18 or newer, which only runs the launcher.
| Route | Needs | Best for |
|---|---|---|
| GitHub installer | Python 3.11+ | Most people. No Node, npm, Git or administrator access |
| npm, yarn, bun or pnpm | Python 3.11+ and Node.js 18+ | People who already manage command-line tools with a Node package manager |
| A clone | Python 3.11+ and Git | Working on the harness itself |
To try it before installing anything, use the hosted demo.
On Linux or macOS (Bash and curl):
curl -fsSL https://raw.githubusercontent.com/YahyaHammad/Venastine-Research-Harness/main/install.sh | bashOn Windows (PowerShell):
irm https://raw.githubusercontent.com/YahyaHammad/Venastine-Research-Harness/main/install.ps1 | iexYou can also download and read the scripts before running them. They download the shared Python installer completely, then run it. It resolves main to a full commit ID, downloads that source archive, and installs the runtime dependencies in an isolated environment. When uv is on your PATH it installs them, copying files rather than linking them out of its cache, and pip does otherwise, or if uv fails. With no Python 3.11+ on your PATH, the scripts also ask uv for one it already has, and never download one.
-
The source goes under
~/.local/share/venastine/app. -
The
venastinecommand goes in~/.local/bin(venastine.cmdon Windows). -
The Python environments go in
~/.config/venastine/runtime/github-*.
When ~/.local/bin is not on your PATH yet, the installer puts it there for the terminals you open afterwards:
- Windows: it appends it to your user PATH, and to the PowerShell window that ran the installer.
-
macOS and Linux: it adds a marked block to your shell's startup file:
~/.zshrc,~/.bashrc, fish'sconf.d/venastine.fish, or~/.profilefor other shells, plus the bash login file you already have on macOS.
Running it again adds nothing twice. To leave PATH alone, set VENASTINE_NO_MODIFY_PATH=1 or pass --no-modify-path. If another venastine (an npm install, say) comes first on your PATH, the installer names it and prints the new command's full path instead.
Credentials and conversation state follow the same rules as an npm install: keys in ~/.config/venastine/providers.json unless the directory you are in has its own, and threads and memories in ~/.config/venastine/.
Set these before running either command.
| Variable | What it does |
|---|---|
VENASTINE_REF |
Install a branch, tag or full commit ID instead of main. Refs older than the installer (without bin/venastine.py) cannot use it |
VENASTINE_INSTALL_DIR |
Where the source goes |
VENASTINE_BIN_DIR |
Where the venastine command goes |
VENASTINE_PYTHON |
Which Python executable to use |
VENASTINE_NO_MODIFY_PATH=1 |
Leave PATH alone |
VENASTINE_NO_UV=1 |
Install with pip even when uv is on your PATH |
The installer itself always comes from main, even when you choose another source ref. Bash can also pass options straight through:
curl -fsSL https://raw.githubusercontent.com/YahyaHammad/Venastine-Research-Harness/main/install.sh | bash -s -- --ref mainFrom a checkout, python scripts/install.py --help lists the same options without downloading or installing anything.
Close any running Venastine sessions, then run the installer again. It builds a fresh environment before replacing the active source, and carries your config.yaml edits forward. Previous source trees (previous-*) stay under the install directory for recovery, so updates use more disk space over time. An unrelated existing directory or command is never replaced.
Remove these four things:
- the
venastinecommand; - the install directory;
- the
github-*runtime directories it created under~/.config/venastine/runtime; - the PATH entry it added: from your user PATH on Windows, or the block between the
venastine GitHub installermarkers in your shell's startup file.
Your other state in ~/.config/venastine (keys, settings, conversations and memories) and the reports in your projects stay until you delete them. PRIVACY.md lists every file the harness keeps.
npm install -g @yahyahammad/venastinenpm handles the setup for you. It delivers the harness as a folder of source, with no bundled binary, and Python still runs it, so the only thing you provide is an interpreter on PATH. The rest happens on first launch: the launcher finds a suitable Python, tells you which one and what it is about to install, and builds an isolated environment with the pinned dependencies once you agree, with uv when it is on your PATH. It asks every time it would install something, never installs during npm install itself, and refuses rather than proceeding when there is no terminal to ask in.
Two things differ from a clone, both so that a command you run from anywhere behaves sensibly:
-
Credentials fall back to
~/.config/venastine/providers.jsonwhen the directory you are in has noproviders.jsonof its own. A local one still wins, so per-project keys keep working. -
Conversation state (
app.dband the log) lives in~/.config/venastine/, so threads and memories follow you between directories. Research reports still land in./outputbeside the work that produced them, and the file tools' workspace stays in the current directory, because it is a permission boundary.
Updating keeps your settings. npm update -g @yahyahammad/venastine replaces the package directory, config.yaml with it, so the launcher merges your own values back in before the harness starts and prints what it kept. Settings you never touched pick up the new version's defaults. A value the new version no longer accepts is dropped and named, rather than costing you the rest. The one case it cannot help with is an edit made after your last session and never launched before you updated.
To uninstall, run npm uninstall -g @yahyahammad/venastine. Your state in ~/.config/venastine stays until you delete it.
The same package installs from the npm registry with the other package managers, and everything above about the launcher applies to each.
yarn global add @yahyahammad/venastinebun add -g --backend=copyfile @yahyahammad/venastinepnpm add -g --config.package-import-method=copy @yahyahammad/venastineTo update, run the same command with @latest after the package name.
- yarn means Yarn 1 (classic). Yarn 2 and later have no global install.
- bun and pnpm need the copy flag, on updates too. By default both hardlink the package's files out of a shared cache or store. The harness protects its own source from tool writes, and a hardlink would give that source a second name in a folder it does not protect. The flag makes them copy, as npm and yarn do.
-
pnpm does not carry
config.yamledits across an update. It puts every install in a new directory, and the harness keys your savedconfig.yamlvalues by that directory, so after an update the values you set with/configor by editing the file are back at the shipped defaults. What lives in~/.config/venastine(settings.json, keys, conversations and memories) is unaffected. If you rely onconfig.yamledits, install with npm, yarn or bun instead.
git clone https://github.com/YahyaHammad/Venastine-Research-Harness.git
cd Venastine-Research-Harness
pip install -r requirements.txtThis is the contributor route, and the one the README's examples assume (python main.py). Two extras are optional:
-
pip install -e ".[documents]"addsmarkitdown, which lets thereadtool convert PDF, DOCX, PPTX, XLSX and HTML files to Markdown.readis off by default (see Tool Permissions). -
pip install -e ".[pdf]"adds the PDF export of research reports.
Then create the two credential files from their templates:
cp providers.json.example providers.json # then add your model provider's API key
cp .env.example .env # then fill in only the keys your tools needThey are kept apart on purpose: providers.json holds model provider keys, read by one module at model-call time, and .env holds tool API keys (a GitHub token, an NVD key), handed to code that talks to third parties. Both are gitignored. In the TUI, /connect writes providers.json for you (see Getting Started).
To run the test suite, install requirements-test.txt too and run pytest. It is fully offline and needs no API keys.
venastine --venastine-doctorIt prints the installed version, the commit, the interpreter and the paths the harness uses. An npm-family install prints the path of config.yaml itself; a GitHub install prints its package root, and config.yaml is the file at the top of it. In a clone, it is config.yaml at the top of the checkout. That is the file to edit when a guide here says to change a config.yaml setting.
Next: Getting Started.
Checked against release 0.3.12 (commit f33ef8a). The README's Setup section is the reference.
Start here
Guides
Reference