Vis

Vis is a coding agent that writes Python into a sandboxed GraalPy runtime, keeps durable state outside the context window, and inspects/changes the host project through tools.

Install

One command installs vis-agent — the only Vis command there is.

curl -fsSL https://github.com/Blockether/vis/releases/latest/download/install-vis-agent | bash
vis-agent help

The installer and the vis-agent command are downloaded as release assets — raw.githubusercontent.com is blocked on many corporate networks, github.com is not. What they install is not tagged: vis-agent checks the source out at the newest commit of main, because a published tag can carry broken source and the fix lands on the branch first.

That installs the vis-agent command into ~/.local/bin (adding it to your PATH when needed). vis-agent then checks out the source it owns into ~/.vis/install/src and runs it with clojure -M:vis, so the install needs Java 25+, the Clojure CLI, and git. From then on vis-agent owns both:

vis-agent runtime show      # what is installed and selected
vis-agent update            # move the command and its runtime to the newest commit

Clojure library:

;; deps.edn
{:deps {com.blockether/vis {:mvn/version "0.1.27"}}}

com.blockether/vis already depends on every bundled extension, so that single coordinate gives the full agent. Depend on one package (com.blockether/vis-channel-tui, com.blockether/vis-provider-anthropic, com.blockether/vis-language-python, …) only when you embed a part of it.

Companion app (iPhone / Android)

Vis Companion is the phone client for a Vis gateway you run yourself — it drives the same sessions as the TUI (see Gateway & pairing). Both stores are in public testing; no invite, no tester list, just the link.

Platform	Public test link	Status
iOS / iPadOS	https://testflight.apple.com/join/4anYT4Wk	TestFlight public link, open to anyone with the URL (requires the free TestFlight app)
Android	https://play.google.com/apps/testing/com.blockether.viscompanion	Play open testing (beta track), package com.blockether.viscompanion

The app is useless on its own: it needs a gateway. Start one with vis-agent gateway, then pair by scanning the QR it prints. Feedback goes to karol@blockether.com (or the TestFlight feedback button).

Choose the runtime

vis-agent follows the releases by default: the published native runtime, or JVM source pinned to the newest vX.Y.Z tag. A live checkout is dev mode — opt in; it is never picked for you, not even from inside a Vis checkout.

Runtime	Runs
native	the private sidecar downloaded by vis-agent update
jvm	source pinned to the newest vX.Y.Z tag
dev	a live checkout (~/vis, or $VIS_DEV_CHECKOUT), tracking its branch
auto	no choice at all: native if installed, else tagged source

Dev mode is the one runtime Vis fetches a checkout for: with nothing at that path, vis-agent update clones the repository there on main.

vis-agent update native|jvm|dev             # acquire it, update it, select it
vis-agent runtime show
vis-agent runtime use native|jvm|dev|auto   # switch only (auto = forget the choice)
vis-agent --native|--jvm|--dev help         # one launch only
VIS_RUNTIME=dev vis-agent help              # one process only

A one-launch flag beats VIS_RUNTIME, which beats the persisted default in ~/.vis/runtime. vis-agent update updates whichever runtime is in effect — the newest release bundle, or the checkout Vis owns moved onto the newest tag — and naming a runtime (vis-agent update dev) updates that one and makes it the default, so switching never needs a second command. Only update --dev follows a moving branch, and any target that is not a vX.Y.Z release pins the owned source to that git ref. A selected runtime that is not installed is an error with the command that fixes it, never a silent substitution. There is no jar runtime: target/vis.jar is a build artifact. Full flag, update, state, and environment matrix: Runtime distributions.

License

Apache License 2.0 — see LICENSE.