Getting started

Vis is a coding agent that combines tools into Python programs. It can chain operations, run them in parallel, and inspect results before deciding what belongs in the conversation.

Install · First session · Configuration

Install

On macOS or Linux, run:

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

Public beta apps. Connect them to your Vis gateway: pairing instructions.

You can read the installer before running it. It installs the stable native engine, bundled Python and terminal client in ~/.local/bin. Installation requires curl and tar, not Java or Git. Use the installer's --jvm option only for source development.

For runtime options and manual setup, see Runtime distributions.

First session

Open a terminal in your project and start Vis:

cd /path/to/project
vis-agent

1. Add a provider in the provider picker and follow its sign-in instructions.
2. Select a model.
3. Enter a task, such as “Explain how this project is organized.”

Use an API key or a supported provider account. You can also connect a local model through Ollama or LM Studio. See Providers and models for setup details.

Vis can modify files and run commands in your workspace. Review its changes before committing them. Process jail and network policy explains filesystem and network permissions.

Work with a project

• Put shared project instructions in AGENTS.md. See Project instructions.
• Send follow-up instructions while a task runs. See Controlling a session.
• Add reusable workflows with Skills, or custom tools with Extending Vis.
• Use your phone or another machine through Remote access and the Companion app.

Update

vis-agent update

To check which runtime is installed, run vis-agent runtime.

Learn more

Guides

• Configuration — providers, models and project settings.
• Project instructions — tell the agent how your codebase works.
• Skills — reusable task instructions.
• Controlling a session — send follow-ups, cancel a task and exit.
• Drafts — let the agent work in an isolated copy and land its changes on a branch.
• Exporting sessions — save or share a session.
• Remote access and the Companion app — use Vis from your phone or another machine.
• Council — exchange project messages and explicit pings between active sessions.
• Reporting a bug — report a problem without exposing private data.

Extensions

• Extending Vis — choose a capability and build your first tool.
• Extension design — design and test typed tools.
• Installing and sharing extensions — layouts, installation, reload and distribution.
• Using an existing Python project — prepare editable uv packages for Vis.
• Extension API — declarations, tool contracts and host operations.
• Extension troubleshooting — diagnose loading and call errors.
• Asking the human — show a typed form and read the answer.
• Live views — show progress a person can watch and stop.
• Provider extensions — register an LLM provider from an extension.
• Python SDK — develop and test extensions outside Vis.

Concepts

• How Vis manages context — why the agent writes programs and folds history.
• Python sandbox — Python execution, packages and permissions.

Reference

• Process jail and network policy — rules for child processes.
• Content-block protocol — message and streaming formats.
• Runtime distributions — installation methods and updates.
• Building the native binary — GraalVM build, metadata and TLS proxies.

Edit on GitHub ↗