virtuoso-bridge-lite: Instructions file for Codex

AGENTS.md — AI Agent Guide for virtuoso-bridge-lite

Control Cadence Virtuoso via Python — remotely over SSH or locally on the same machine.

Two modes

Mode	When	Setup
Remote	Virtuoso on a server, you work locally	Set VB_REMOTE_HOST for one host, or explicit VB_*_HOST roles, then run virtuoso-bridge start
Local	Virtuoso on your own machine	Set VB_REMOTE_HOST=localhost, run virtuoso-bridge start, load the path it prints into CIW

Prerequisites

1. SSH: ssh my-server must work without a password prompt.
2. Virtuoso (for SKILL execution): a running Virtuoso process on the remote (or local) machine.
3. Spectre (for simulation only): spectre on PATH, or set VB_CADENCE_CSHRC to a cshrc that adds Cadence tools to PATH.

Virtuoso and Spectre are independent — you can run Spectre without the SKILL bridge, and vice versa.

Install (both modes)

Use uv + virtual environment — never install into the global Python.

uv venv .venv && source .venv/bin/activate   # Windows: source .venv/Scripts/activate
uv pip install -e .

Step-by-step setup (remote mode)

1. Generate config

# Preferred — fill host/user/jump in one shot:
virtuoso-bridge init [email protected] -J [email protected]

# Or — empty template (you edit `.env` manually in step 2):
virtuoso-bridge init

Both forms create ~/.virtuoso-bridge/.env. -J/--jump accepts [user@]host. VB_REMOTE_PORT / VB_LOCAL_PORT are auto-assigned by hashing the remote username (stable per remote user, so two users on the same host don't collide). Re-running init on an existing .env is a no-op; pass --force to overwrite.

2. Edit .env (only if step 1 did not already fill it in)

Where to put .env: --env FILE has the highest priority. Without it, the bridge walks from the current directory upward and uses the first .env that looks like a Virtuoso Bridge config (a VB_*_HOST role or VB_LOCAL_PORT), then falls back to ~/.virtuoso-bridge/.env.