How xsw632/chipagent works
Purpose and entry points
ChipAgent is a Claude Code plugin for converting natural-language hardware descriptions into simulation-verified Verilog, with optional synthesis/place-and-route (PnR). Installation is npm-driven through package.json and bin/install.js; plugin registration is defined in .claude-plugin/plugin.json. User entry points are Claude slash-command skills, notably skills/workflow/SKILL.md, skills/generate/SKILL.md, skills/debug/SKILL.md, and skills/pnr/SKILL.md.
Workflow orchestration
The full workflow skill coordinates staged, filesystem-based execution: requirements parsing → Chisel generation → compilation → linting → testbench generation → simulation → reporting. Skills provide the command-level control plane and delegate reasoning-intensive steps to specialized agent prompts:
• skills/workflow/SKILL.md
• agents/requirement-parser.md
• agents/chisel-generator.md
The primary durable design boundary is a per-design workspace such as MyDesign/ALU8/workspace/, separating generated RTL, simulation, PnR inputs/results, QoR history, and structured spec.
Specification and RTL generation
Natural language is normalized into a structured hardware contract (spec.json), then an agent produces Chisel/Scala source. The Chisel project is an sbt/JVM subproject, with its generic Verilog emission main in chisel-project/src/main/scala/chipagent/Generate.scala; example/generated design source lives beside it, e.g. chisel-project/src/main/scala/chipagent/ALU.scala. Outputs include FIRRTL annotations/IR and Verilog, exemplified by MyDesign/ALU8/workspace/generated/ALU8.anno.json, .fir, and .v.
Build, lint, and simulation
Shell wrappers form the execution boundary to local EDA tooling:
• Compilation: scripts/compile.sh invokes sbt/Chisel/FIRRTL to emit RTL.
• Linting: scripts/lint.sh invokes Verilator.
• Simulation: scripts/simulate.sh compiles generated Verilog plus a generated C++ testbench and emits logs/VCD traces.
Testbench generation is agent-directed (agents/testbench-generator.md) and results are stored under the workspace simulation area, e.g. MyDesign/ALU8/workspace/sim/tb_ALU8.cpp and MyDesign/ALU8/workspace/sim/logs/ALU8.vcd. Debug tooling consumes spec, RTL, logs, and waveform data; VCD parsing is externalized to scripts/parse_vcd.py.
MCP backend and PnR control plane
PnR commands access a persistent MCP backend rather than directly embedding all tool logic in skills. The principal server is TypeScript/Node (mcp-server/index.ts) with discrete tools for environment checks, configuration, stage execution, report retrieval, failure diagnosis, cleanup, and run comparison:
• mcp-server/tools/check-environment.ts
• mcp-server/tools/run-stage.ts
• mcp-server/tools/diagnose-failure.ts
A Python Docker-oriented counterpart (mcp-server-docker-python/server.py) includes ORFS metric parsing (mcp-server-docker-python/orfs_metrics.py). This boundary isolates Claude/plugin orchestration from host- and container-specific EDA execution.
Physical-design pipeline and artifacts
PnR is configured from generated RTL plus SDC constraints and runs an OpenROAD-flow-style staged pipeline: Yosys synthesis, floorplan/PDN, placement, CTS, routing, fill, and GDS export. Design-local PnR inputs are represented by MyDesign/ALU8/workspace/pnr/config.mk and MyDesign/ALU8/workspace/pnr/constraint.sdc. Stage logs, reports, and final physical outputs are persisted independently; e.g. MyDesign/ALU8/workspace/pnr/reports/sky130hd/ALU8/base/6_finish.rpt and MyDesign/ALU8/workspace/pnr/results/sky130hd/ALU8/base/6_final.gds.
Runtime and external dependencies
Core runtime spans Node/npm (plugin installer and TypeScript MCP server), Python (waveform and Docker/MCP utilities), Bash, JVM/Scala/sbt, Chisel 3.6.1/FIRRTL, and Verilator. Physical design additionally depends on Yosys, OpenROAD/OpenROAD-flow-scripts, Sky130HD technology data, and optionally Docker. Chipyard-specific skills (skills/chipyard/SKILL.md, skills/chipyard-rtl/SKILL.md, skills/chipyard-pnr/SKILL.md) add environment detection and RTL/PnR paths for Chipyard designs.
Main entry points: ALU8.v Generated RTL and FIRRTL · SKILL.md Slash-command skills · requirement-parser.md Generation agents · simulate.sh Simulation runner
Components 21
Plugin control plane
- npm installer · Installs the Claude Code plugin.
bin/install.js - Plugin registration
.claude-plugin/plugin.json - Slash-command skills · Workflow, generation, debug, and PnR commands drive the pipeline.
skills/workflow/SKILL.md - Generation agents · Specialized prompts normalize requirements and generate Chisel.
agents/requirement-parser.md
Design workspace
Per-design durable inputs, generated artifacts, and results.
- Per-design workspace · Isolates each design's specification, RTL, simulation, and PnR state.
- Hardware contract
- Chisel design source
chisel-project/src/main/scala/chipagent/ALU.scala - Verilog emitter · Generic Chisel/FIRRTL emission entry point.
chisel-project/src/main/scala/chipagent/Generate.scala - Generated RTL and FIRRTL · Includes annotations, FIRRTL IR, and emitted Verilog.
MyDesign/ALU8/workspace/generated/ALU8.v
RTL verification
- Compile RTL · Runs sbt, Chisel, and FIRRTL.
scripts/compile.sh - Lint RTL
scripts/lint.sh - Testbench agent
agents/testbench-generator.md - Simulation runner · Builds RTL with the generated C++ testbench.
scripts/simulate.sh - Simulation logs and VCD
MyDesign/ALU8/workspace/sim/logs/ALU8.vcd - Waveform parser · Externalizes VCD parsing for debug analysis.
scripts/parse_vcd.py
Physical design
- PnR MCP server · Persistent tool boundary between plugin orchestration and EDA execution.
mcp-server/index.ts - Stage execution tool
mcp-server/tools/run-stage.ts - PnR config and constraints
MyDesign/ALU8/workspace/pnr/config.mk - OpenROAD physical flow · Synthesis through floorplan, placement, CTS, routing, fill, and GDS export.
- QoR reports
MyDesign/ALU8/workspace/pnr/reports/sky130hd/ALU8/base/6_finish.rpt - Final GDS
MyDesign/ALU8/workspace/pnr/results/sky130hd/ALU8/base/6_final.gds
Connections 23
- npm installer → Plugin registration: installs
- Plugin registration → Slash-command skills: registers
- Slash-command skills → Generation agents: delegates reasoning to
- Generation agents → Hardware contract: writes
- Hardware contract → Per-design workspace: stored in
- Generation agents → Chisel design source: generates
- Chisel design source → Compile RTL: compiled by
- Compile RTL → Verilog emitter: runs
- Verilog emitter → Generated RTL and FIRRTL: emits
- Generated RTL and FIRRTL → Per-design workspace: stored in
- Generated RTL and FIRRTL → Lint RTL: checked by
- Hardware contract → Testbench agent: guides
- Testbench agent → Simulation runner: provides C++ testbench
- Generated RTL and FIRRTL → Simulation runner: simulated with
- Simulation runner → Simulation logs and VCD: emits
- Simulation logs and VCD → Waveform parser: parsed by
- Slash-command skills → PnR MCP server: invokes for PnR
- PnR MCP server → Stage execution tool: exposes
- Stage execution tool → OpenROAD physical flow: runs
- Generated RTL and FIRRTL → OpenROAD physical flow: RTL input
- PnR config and constraints → OpenROAD physical flow: configures
- OpenROAD physical flow → QoR reports: produces
- OpenROAD physical flow → Final GDS: exports