Vibe-IC User Manual

Start here — one prompt is all you need

If you use Claude Code or Kimi Code, this section is all a human needs. Everything below — prerequisites, installation, commands — is written for the AI to read, not you. Just point your AI at this manual and go.

Read https://vibeic.ai/manual.html, and install vibe-ic plugin and vibeic-eda MCP

Here are my design documents in the folder ./my-design. Run the full vibe-ic flow on them with the sky130A PDK.

run vibe-ic benchmark VE-v2 and VE-Human

run vibe-ic plugin with vibeic-eda MCP for benchmark IC spm by using sky130A PDK

Capture this enhancement into the vibe-ic plugin and vibeic-eda MCP, then verify it

Read https://vibeic.ai/manual.html, and upgrade vibe-ic plugin and vibeic-eda MCP to the latest version

What is Vibe-IC

Vibe-IC is an open-source Claude Code plugin plus an MCP server for EDA tools. It lets you design chips in natural language: from a plain-language prompt or a set of existing design documents, it drives one automated flow all the way to GDSII. The flow is program-first — deterministic programs do the work and hold every gate — with an AI expert as the backup that reviews, fills gaps, and repairs failures. It is chip-agnostic (no per-chip hard-coding) and the plugin is Apache-2.0 licensed.

When the plugin loads, Claude becomes the IC Expert Agent — it knows the plugin's capability scope, all entry paths, and the expected result of every phase. You never have to be an IC engineer to start.

Prerequisites

Vibe-IC's EDA tools run inside a Docker container, and the plugin runs inside Claude Code. You need the following on your host machine before installing.

Also recommended: Linux (Ubuntu 22.04 or 24.04) and about 30 GB of free disk — the forked EDA Docker image is roughly 26 GB. A PDK is needed for physical design; SKY130 is the default, with GF180MCU, IHP-SG13G2, NanGate45 and ASAP7 plus custom PDKs supported. FPGA and lab hardware are optional.

Installation

Three steps: start the forked EDA Docker container, install the plugin (which bundles and auto-wires the MCP-EDA server), then confirm the wiring is green. No manual MCP configuration is required.

1. Start the forked EDA Docker
   The plugin's EDA tools run inside the enhanced vibeic-eda container. Pull it and start it named vibeic-eda — that is the exact name the MCP server expects (via EDA_CONTAINER). The identity bind-mount is required so Phase 3 paths resolve inside and outside the container.

   # point VIBEIC_DESIGNS at YOUR designs/project folder — it must already exist
   export VIBEIC_DESIGNS="/path/to/your/designs"  # your project / designs folder
   [ -d "$VIBEIC_DESIGNS" ] || { echo "VIBEIC_DESIGNS must be an existing directory"; exit 1; }
   # pull the forked EDA image (patched OpenROAD / yosys / magic / …)
   docker pull ghcr.io/vibeic/vibeic-eda:0.2.54
   docker rm -f vibeic-eda 2>/dev/null || true    # drop any old container of the same name
   docker run -d --name vibeic-eda \
     -v "$VIBEIC_DESIGNS:$VIBEIC_DESIGNS:rw" \
     -v "$VIBEIC_DESIGNS:/foss/designs:rw" \
     ghcr.io/vibeic/vibeic-eda:0.2.51 --skip sleep infinity
   docker exec vibeic-eda yosys --version         # sanity check — prints a version

   Prefer the stock upstream base? Pull hpretl/iic-osic-tools:latest and run it named vibeic-eda instead — the plugin drives either.
2. Install the vibe-ic plugin (one step)
   Add this repo as a Claude Code marketplace and install the plugin. This also bundles and auto-registers the MCP-EDA server — no separate claude mcp add is needed. Its npm dependencies install on first run.

   claude plugin marketplace add vibeic/vibe-ic
   claude plugin install vibe-ic

   Inside an interactive Claude Code session, the same two commands are:

   /plugin marketplace add vibeic/vibe-ic
   /plugin install vibe-ic@vibe-ic-marketplace

3. MCP auto-wire & health check
   The plugin ships .mcp.json, which starts the eda-tools MCP server and points it at the vibeic-eda container (EDA_CONTAINER=vibeic-eda). Every eda_* tool then runs inside the container. Confirm it is green by asking the agent to run the health tool — expect 14/14 checks passed:

   eda_doctor          # or: mcp_server_health_check

Optional — verify the install reproduces our numbers

A clean-platform verification script checks host tools → plugin structure → plugin self-checks → benchmark reproduce, and prints VERDICT: READY. Datasets are external; omit an env var to skip that benchmark.

RTLLM_DATASET=/path/to/RTLLM \
VEV2_DATASET=/path/to/verilog-eval/dataset_spec-to-rtl \
VEHUMAN_DATASET=/path/to/verilog-eval/dataset_code-complete-iccad2023 \
tools/release/verify_clean_platform.sh          # expect: VERDICT: READY

Quick start — your first design, end to end

There are two input modes. Both feed the same Phase 1 → 2 → 3 flow.

Mode A — an input folder (deterministic runner)

Put existing design docs under the project's input/docs/ (or a free-text spec that the doc track render-bridges), then run the top-level one-shot runner. It auto-detects Path A vs B and chains Phase 1 → 2 → Analog → 3.

python3 vibe-ic-marketplace/plugins/vibe-ic/programs/vibe_ic_one_shot_runner.py <project> --pdk sky130A
# → <project>/reports/vibe_ic_one_shot.json  (phases[], halted_at, verdict)

Inside an interactive Claude Code session the same run is one slash command:

/vibe-ic-all <project-dir>

Mode B — dialogue (natural language)

Open Claude with the plugin and describe your chip in plain language. Claude, as the IC Expert Agent, elicits the spec, fills gaps, and runs the flow.

claude "Design a temperature sensor IC: I2C interface, 12-bit,
        alert output, SOIC-8 package."

Where inputs go, where outputs land

Bring your own PDK, IP, device & FPGA

Vibe-IC follows the industry separation of tools from data: the vibeic-eda container ships the EDA tools, and everything foundry- or user-specific is supplied at run time, scoped to your project — never rebuilt into the image. Real PDKs and commercial IP are usually under NDA or licence and legally cannot be redistributed inside a shared image, so this is a hard rule, not a preference.

PDK — a built-in one, or your own

Pick a built-in reference PDK by name — sky130A, gf180mcuD, IHP SG13G2, plus the research / education PDKs NanGate45 (generic 45nm) and ASAP7 (7nm FinFET, predictive, BSD-licensed; not tapeout-capable) — or drop your own PDK views into the project and let the flow detect them. No image change either way.

# A built-in open reference PDK (batteries-included):
python3 .../programs/phase3_one_shot_runner.py <project> --pdk sky130A   # or gf180mcuD / nangate45 / asap7

# Your own PDK — drop the views under the project, then --pdk auto:
<project>/input/pdk/liberty/*.lib
<project>/input/pdk/lef/*.lef
<project>/input/pdk/gds/*.gds
python3 .../programs/phase3_one_shot_runner.py <project> --pdk auto   # site / metal / clk auto-detected

Through the MCP tools (eda_synth / eda_pnr / eda_gds / eda_sta) the same custom PDK is passed by path with pdk:"custom":

eda_pnr  pdk:"custom"  custom_lib:"…/my.lib"  custom_techlef:"…/my.tlef"
         custom_celllef:"…/my.lef"  custom_cellgds:"…/my.gds"
         custom_site:"CoreSite"  custom_metal_prefix:"Metal"
         custom_vdd:"VDD"  custom_vss:"VSS"

IC IP & hard macros

SRAM, OTP, ADC, PLL and other hard macros are project-local data. Place their views — LEF for PnR, Liberty for timing, GDS for streamout, Verilog for the gate view — under the project, and PnR integrates them across every backend step. Licensed vendor IP never enters the shared image.

Devices & FPGA boards

Physical instruments — oscilloscope, DE10-Lite / MAX10 FPGA, MD-905 — are not files. The container is given access to the host hardware at run time over USB / serial / network, and the device_* and eda_fpga_* tools drive them; nothing is baked in. An FPGA's board and part number are project data; the open synthesis toolchain is in the image, while a licensed vendor compiler (e.g. Quartus for the DE10-Lite) is an external / host install, not the shared image.

Does registering something change the image?

Commands reference

Five slash commands drive the flow, plus one for running open benchmarks. Each is a thin front door to a deterministic runner program; the AI then monitors the JSON report and close-loops any failing step.

Every command runs its program as python3 ${CLAUDE_PLUGIN_ROOT}/programs/<runner>.py, so you can also invoke the runner directly (as in Quick Start Mode A). If you call a command with no project path, it will ask for one — it never guesses.

Reading the gates

The flow is gate-enforced. Each stage ends with a compliance gate, and the whole flow has one sole acceptance criterion: a claim of complete is only valid when flow_compliance_check.py --strict returns Overall: PASS or PASS_WITH_WAIVERS. An individual gate passing is necessary but not sufficient.

Anti-fabrication — why you can trust a PASS

There is no silent PASS: every tool failure surfaces an actionable hint. Every tool call is logged to provenance.jsonl with its tool, version, input/output hash, exit code and duration, and canonical artifacts (L-docs, SOF, GDS, netlist, LEF, Liberty, each sign-off report) are attested by SHA256. That is what lets the gate distinguish a real result from a fabricated one.

Every one of those gates is defined in one file, phase1_phase2_phase3.yaml — 63 step entries, the exact command that verifies each one, and the 8 judgment dimensions the matrix above is built from. It is worth understanding on its own terms, including where it genuinely drives the flow and where it only declares intent.

Troubleshooting & FAQ

The 3-phase flow at a glance

One automated flow spans 3 Phases and 5 Stages. The digital main line runs Phase 1 → 2 → 3; the Analog (A1–A9) and Mixed-signal (M1–M4) tracks run in parallel and interleave where their deliverables belong. Each stage ends with a compliance gate — nothing advances until its gate passes.

This is the overview. For every step's exact input, output, and the EDA tool that runs it — all 3 Phases, 5 Stages, and the Analog / Mixed-signal tracks — open the Full Flow page.

Every step, in detail

Each phase decomposes into named stages, and each stage into concrete steps. A step is never a black box: it declares its input, its output, the exact EDA tool that runs it, and the gate that must pass before the next step starts. The Step Reference documents all of them — Phase 1 doc extraction (L1–L27), Phase 2 RTL / verify / synth / DFT / FPGA, Phase 3 PnR / DRC / LVS / STA / IR / EM / GDS, and the Analog A1–A9 and Mixed-signal M1–M4 tracks.

Vibe-IC Studio — the flow as a GUI

Prefer clicking to typing? Vibe-IC Studio is a web control surface over the same flow — it turns the "type a Claude prompt to drive the plugin" workflow into a deterministic dashboard. The whole flow lives on one page: every canonical step's input/output folders, produced files and verification result, with per-step Run / Re-run in any phase, and a choice of which model (Claude / GLM / Kimi) authors the AI-backed steps — all on a subscription account, no API key. Everything shown is discovered from the authoritative plugin and the benchmark-data tree, never invented.

Design philosophy

Three ideas shape everything Vibe-IC does. They are why a PASS is trustworthy and why the flow generalizes across chips instead of memorizing them.

1 · Open platform

The plugin is Apache-2.0, and the entire backend is real open-source EDA — no commercial-tool dependency for the core flow. Where a stock tool fell short we did not stop; we FORKED it (vibeic/OpenROAD, yosys, magic, netgen, iverilog, klayout, ngspice) and enhanced it, shipped as one reproducible container. You can self-host the whole stack, read every line, and contribute back upstream. No vendor lock-in, no black boxes.

2 · Program-first + AI-backup

Deterministic programs do the work and hold every gate; the AI expert is the backup, not the primary author. Where a step is genuinely a language task (spec → RTL), the AI authors — but always inside the runner's pipeline, wrapped by deterministic gates (hygiene, conformance, lint, synth, audit). The two run as a dual track: the program and an independent AI read the same problem, and every disagreement is converged. A recovery the AI finds is not left in a prompt — it is absorbed back into the program layer, so the next blind run auto-recovers it. That is why the same result reproduces across machines and sessions.

3 · Blind & correct-by-construction

Every step reads only the design INPUT — the prompt plus any provided context — never a hidden testbench, golden answer, or scoring oracle. A number earned this way measures real capability, not overfitting to an answer key. And nothing is a silent PASS: every gate re-computes its verdict, every tool call is logged to provenance with hashes, and canonical artifacts are SHA256-attested — so a fabricated result cannot pass as a real one.

Open-source vs commercial tools

Every commercial sign-off tool has an open-source counterpart that Vibe-IC already drives. For DRC on a foundry deck, STA, and LVS the substitution is strong; a few dimensions (crosstalk SI, foundry-rule extraction, ESD/latch-up) are honestly a conservative tier. The Rigor column is our own honest grade, not a vendor claim.

Our enhancements — the vibeic-eda forks

When a stock open-source tool crashed, produced a wrong result, or could not run a construct the flow needs, we treated it as an engineering backlog item against our fork — never as a reason to reach for a commercial tool. Across the 15 forks surveyed against commercial EDA, every forkable gap is now resolved: it is either a real gated fix, already covered by the upstream tool (with the citation shown), or honestly classified as an external trust requirement. Each landed change is committed to the fork and baked into the reproducible image. The scoreboard is public and tracked live. Scope, stated plainly: that survey covered 15 forks, which is not the whole toolchain. Measured and CLOSED 2026-07-31: fault — the DFT/ATPG engine this flow invokes — was used but never forked, so no guard could check it, no registry listed it and the daily upstream merge could not see it; the inherited binary had aged four years. It is now built from vibeic/Fault and ships in image 0.2.51, carrying our fix for chain --skip-synth exiting EX_OK while never creating the file -o asked for. The four forks absent from the daily merge (Xyce, slang, sv-elab, xschem) are in it. trilinos/Trilinos — the last entry on the pending list, held open on the belief that a whole-history push would fail at that size — is mirrored too. check_fork_only now reads 49 of 49 references ours, 0 pending, for the first time.

Where the fixes landed

Benchmark results

We publish only clean-room, blind, prompt-only numbers scored by each benchmark's OWN official harness. Every figure names the model and plugin version it was measured on, and every commercial-tool substitution is disclosed. These measure functional generation and open-source sign-off — not silicon.

Tool substitution (disclosed)

Synopsys VCS / Cadence Xcelium → iverilog (forked, SV-2012) + Verilator · Design Compiler → yosys + OpenROAD · PrimeTime → OpenSTA · Calibre → KLayout / magic / netgen · nvidia/cvdp-sim → the fully-open cvdp OSS image. The VerilogEval / RTLLM / CVDP simulation images are fully open-source (no tool substitution in scoring).