via

A Rust terminal application that bridges Neovim and AI agents via libghostty's
VT engine.

Why via?

Via is my attempt at making terminal-only AI-assisted coding better. There are
plenty of Neovim plugins that put the AI assistant in a side pane, but my
experience working with them wasn't very enjoyable: too much flickering, weird
pane positioning, and so on. I thought wrapping Neovim + an agent in a dedicated
terminal window could deliver a smoother UX.

The idea is simple: glue the best code editor together with the AI coding
harness of your choice, and add a few features that make the combination feel
like a lightweight IDE.

By default you get an editor pane and an agent pane that automatically adjust
when the window is resized, plus simple shortcuts to switch panes or give either
one fullscreen focus.

It is currently my daily driver for AI-assisted coding. I use it mostly with
cursor-agent (~80%) and opencode (~20%), and I also test other agents like
claude-code and crush.

Neovim to Agent

• Send the current selection or buffer with <leader>ab (or :ViaBufferSend)
• Multiple agents via the ACP protocol
• Agent orchestration (e.g. spawn a reviewer, take the feedback, apply changes)

Agent to Neovim

• Hold Ctrl in the agent pane to highlight clickable filenames, symbols, and
  OSC 8 hyperlinks.
• Ctrl+click on a filename to open that file in Neovim and focus the Neovim pane
  (enter fullscreen Neovim if the agent was fullscreen; otherwise keep the
  split).
• Ctrl+click on a symbol to open the symbol search pane in Neovim with the same
  focus behavior.
• Ctrl+click on an external OSC 8 hyperlink to open it in the system browser.

Multi-agent orchestration

The default layout is Neovim plus one interactive PTY agent
(--agent opencode). For everyday edits you work in that pane; no ACP process
runs at startup.

Orchestration is opt-in. Spawn an ACP orchestrator and helpers when you need
automatic multi-agent handoff:

via agent spawn --id orchestrator          # preset role: orchestrator
via agent spawn --id reviewer              # preset role: reviewer
via agent spawn --id coder                 # preset role: coder
via agent send --to reviewer -m "review this diff"

Spawned agents resolve to ACP when the configured driver supports it (opencode
→ opencode acp). If your main driver doesn't support ACP (e.g. claude, crush),
you can pick a different agent for orchestration with --acp-agent. The primary
PTY pane keeps the id agent; the coordinator is orchestrator.

Design policy: Via provides the transports (panes, bus, ACP). Agents
orchestrate themselves using skills and the via agent CLI; multi-agent
workflows are not encoded in the mediator.

Configure spawn defaults in ~/.config/via/via.conf:

[agents.reviewer]
role = "reviewer"
# command = "cursor-agent acp"  # optional override

[agents.coder]
role = "coder"

Then via agent spawn --id reviewer picks up the preset role and resolves the
launch command from your primary agent.

Navigation

• Alt+2..9 focuses the corresponding agent pane (Alt+2 is the first agent).
• Alt+Shift+1..9 maximizes that pane (Alt+Shift+1 for the editor, Alt+Shift+2
  for the first agent, etc.).
• Alt+J toggles the split direction.

Lua API for plugins

require('via') is available inside any via-launched Neovim session (the module
is injected into ~/.local/share/via/lua/ at startup). Example usage:

local via = require('via')
via.agent.spawn("reviewer", "reviewer")                 -- spawn a reviewer pane
via.agent.del("reviewer")                               -- terminate a sub-agent when done
via.agent.send("reviewer", "please review this diff", false) -- send without stealing focus
via.agent.send("orchestrator", "hello orchestrator")    -- send after spawning orchestrator
for _, agent in ipairs(via.agent.list()) do print(agent.id) end -- discover running agents

Agent-to-agent communication (the agent bus)

Agents running inside via can discover, spawn, and message each other through
the via agent CLI (documented for agents in the bundled via-agents skill).
Each agent pane gets VIA_AGENT_ID and VIA_AGENT_ROLE in its environment.

via agent whoami                                  # this agent's id/role/session
via agent list                                    # agents running in this session
via agent spawn --id reviewer --role reviewer     # ask via to open a reviewer pane
via agent send --to reviewer -m "review this"     # queue a message + deliver it
via agent inbox                                   # read (and clear) your mailbox

Coordination notes:

• PTY panes (agent, or explicit non-ACP spawns) are mailbox-only on send.
• ACP spawned agents receive prompts automatically.
• Orchestration spawns require a known ACP mapping for the configured driver.

Work in progress

This is still an experimental project. Although I use it as my daily "IDE", it
has some rough edges. Some things I have planned:

• Review process: make it easier to switch between agent/review and send
  feedback to the agent directly from the Neovim pane (may use an existing
  Neovim plugin for this)

Runtime requirements

via is primarily developed and tested on Linux (Wayland compositors such as
Hyprland on Omarchy, with an X11 fallback via winit). Other Linux distributions
and operating systems (macOS, Windows) are not regularly tested; you will likely
need to build from source. See CONTRIBUTING.md for
prerequisites and platform notes.

Build requirements

• Rust
• Zig 0.15.2 — required by the vendored libghostty-vt
  build.
• git (used by the libghostty-vt-sys build script to fetch ghostty sources).

If you use mise, the project's .mise.toml pins the
correct Zig version automatically:

mise install

Otherwise install Zig 0.15.2 manually and put it on your PATH.

Build

cargo build --release
./target/release/via

libghostty-vt is statically linked into the binary, so no runtime library
search path setup is needed.

Development

cargo test                 # unit tests live next to the code
cargo fmt -- --check
cargo clippy -- -D warnings

See CONTRIBUTING.md for the full development guide
(prerequisites, how to run a local session, good first areas, benchmarks, etc.)
and ARCHITECTURE.md for an overview of the Mediator/UI/ACP
data flows and performance-sensitive surfaces.

cargo test is the primary regression guard today; we are expanding Criterion
micro-benchmarks for layout calculations and link/OSC 8 scanning (the two most
user-visible hot paths).

Configuration

User-facing settings can be provided as CLI flags, environment variables, or in
~/.config/via/via.conf using TOML syntax. Precedence is:

CLI flags > environment variables > via.conf > built-in defaults

Example config:

nvim = "nvim"
agent = "opencode"          # PTY primary; ACP resolved only for spawned helpers
acp_agent = "cursor-agent acp" # Use cursor instead of opencode for the acp agents
agent_pane_cols = "80:120"
review_backend = "nvim"
plugin_dir = "~/my-via-plugin"

Equivalent CLI/env names:

• --nvim / VIA_NVIM
• --agent / VIA_AGENT
• --acp-agent / VIA_ACP_AGENT
• --agent-pane-cols / VIA_AGENT_PANE_COLS
• --review-backend / VIA_REVIEW_BACKEND
• --plugin-dir / VIA_PLUGIN_DIR

plugin_dir points at a local directory with extra agent skills (a skills/
subdirectory of SKILL.md files). via overlays them on top of its built-in base
skills when installing the plugin, so you can ship your own agents/workflows
without modifying via.

Use --persist to write the resolved user-facing config to via.conf before
running. For example, this writes agent = "opencode" (PTY primary) plus
defaults:

via --agent opencode --persist

Neovim bridge scripts (nvim/*.lua) are embedded at compile time; the context
bridge is written to via's data directory ($XDG_DATA_HOME/via, or
~/.local/share/via) when needed. Override with VIA_NVIM_CONTEXT_BRIDGE if
you want to load a custom script from disk during development.

Release

Create and publish a GitHub release for a tag such as v0.1.0. The release
workflow builds via in release mode, packages the binary and README into
via-<tag>-linux-x86_64.tgz, and uploads the archive plus its SHA-256 checksum
to the release.

Detached mode

On Linux, via detaches to avoid keeping the terminal waiting for it to finish.
Runtime files for each live process live under
$XDG_DATA_HOME/via/instances/<pid>/ (default
~/.local/share/via/instances/<pid>/). Stale instance directories can be pruned
in bulk from that folder.

The runtime root is also exposed as VIA_RUNTIME_ROOT for scripts. To skip
detaching and keep the terminal attached (for example during development), set
VIA_FOREGROUND to any value.

Agent pane width

With a PTY agent, vertical split mode keeps the agent at its minimum width
(default 80 columns, up to 100) and gives any extra columns to the editor.
Override with:

VIA_AGENT_PANE_COLS=60:120 cargo run
cargo run -- --agent-pane-cols 100

A single value pins the agent pane to that width; min:max gives a range.

The editor pane keeps at least 80 columns. When the window cannot fit both that
and the agent minimum (default 80 + 80 = 160 columns total), via collapses to
editor fullscreen. Widening enough to fit both restores the split unless you
chose fullscreen manually (Alt+Shift+1).

Font Rendering Tweaks

via follows the window scale factor reported by winit/Wayland when converting
Ghostty's point-based font-size into physical pixels. On fractional-scale
setups this can differ from the compositor scale you configured, so font output
can change significantly between displays.

Use these environment variables to test font rendering without code changes:

VIA_FONT_SCALE=1.6 cargo run
VIA_FONT_HINTING=enabled cargo run
VIA_FONT_COVERAGE_BOOST=0 cargo run

Possible tweaks:

• VIA_FONT_SCALE: overrides the reported window scale used for font DPI, e.g.
  1.33, 1.6, or 2.0.
• VIA_FONT_PIXEL_SCALE: multiplies the computed glyph pixel size after DPI
  conversion.
• VIA_CELL_WIDTH_SCALE: multiplies the computed terminal cell width only.
• VIA_CELL_HEIGHT_SCALE: multiplies the computed terminal cell height only.
• VIA_BASELINE_RATIO: controls baseline placement inside each cell. Default:
  0.73.
• VIA_FONT_HINTING: sets cosmic-text metrics hinting. Values: enabled or
  disabled.
• VIA_FONT_COVERAGE_BOOST: controls via's glyph coverage boost. Default:
  0.2; use 0 to disable.
• VIA_FONT_SHAPING: selects cosmic-text shaping. Values: advanced or
  basic.

Contributing

See CONTRIBUTING.md for build instructions, testing,
architecture pointers, and how to submit changes. Issues and PRs are welcome —
small, focused contributions (layout, links, ACP surface, review backends,
diagnostics, docs, tests) are especially appreciated.

License

Licensed under the Apache License, Version 2.0. See the LICENSE file
for details.