# xsw632/chipagent architecture

> Architecture diagram of the GitHub repository xsw632/chipagent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xsw632/chipagent
- Repository: https://github.com/xsw632/chipagent

## Overview

#### 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: [`MyDesign/ALU8/workspace/generated/ALU8.v`](https://github.com/xsw632/chipagent/blob/main/MyDesign/ALU8/workspace/generated/ALU8.v) (Generated RTL and FIRRTL), [`skills/workflow/SKILL.md`](https://github.com/xsw632/chipagent/blob/main/skills/workflow/SKILL.md) (Slash-command skills), [`agents/requirement-parser.md`](https://github.com/xsw632/chipagent/blob/main/agents/requirement-parser.md) (Generation agents), [`scripts/simulate.sh`](https://github.com/xsw632/chipagent/blob/main/scripts/simulate.sh) (Simulation runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_plugin["Plugin control plane"]
  node_installer["npm installer<br/>Node installer<br/>[install.js]"]
  node_plugin_manifest["Plugin registration<br/>Claude plugin manifest<br/>[plugin.json]"]
  node_skills["Slash-command skills<br/>Claude skill control plane<br/>[SKILL.md]"]
  node_agents["Generation agents<br/>Agent prompts"]
end

subgraph group_design["Design workspace"]
  node_workspace[("Per-design workspace<br/>Filesystem boundary")]
  node_spec["Hardware contract<br/>Structured specification"]
  node_chisel_source["Chisel design source<br/>Scala/Chisel RTL<br/>[ALU.scala]"]
  node_chisel_emitter["Verilog emitter<br/>Scala main<br/>[Generate.scala]"]
  node_generated_rtl["Generated RTL and FIRRTL<br/>Verilog artifacts<br/>[ALU8.v]"]
end

subgraph group_verification["RTL verification"]
  node_compile["Compile RTL<br/>Bash wrapper<br/>[compile.sh]"]
  node_lint["Lint RTL<br/>Verilator wrapper<br/>[lint.sh]"]
  node_testbench_agent["Testbench agent<br/>Agent prompt"]
  node_simulation["Simulation runner<br/>Verilator wrapper<br/>[simulate.sh]"]
  node_sim_artifacts["Simulation logs and VCD<br/>Verification artifacts<br/>[ALU8.vcd]"]
  node_debug_parser["Waveform parser<br/>Python utility<br/>[parse_vcd.py]"]
end

subgraph group_pnr["Physical design"]
  node_mcp_server{{"PnR MCP server<br/>TypeScript/Node server<br/>[index.ts]"}}
  node_mcp_stage_tool["Stage execution tool<br/>MCP tool<br/>[run-stage.ts]"]
  node_pnr_inputs["PnR config and constraints<br/>OpenROAD inputs<br/>[config.mk]"]
  node_physical_flow["OpenROAD physical flow<br/>EDA pipeline"]
  node_pnr_reports["QoR reports<br/>PnR reports<br/>[6_finish.rpt]"]
  node_gds["Final GDS<br/>Physical design output<br/>[6_final.gds]"]
end

node_installer -->|"installs"| node_plugin_manifest
node_plugin_manifest -->|"registers"| node_skills
node_skills -->|"delegates reasoning to"| node_agents
node_agents -->|"writes"| node_spec
node_spec -->|"stored in"| node_workspace
node_agents -->|"generates"| node_chisel_source
node_chisel_source -->|"compiled by"| node_compile
node_compile -->|"runs"| node_chisel_emitter
node_chisel_emitter -->|"emits"| node_generated_rtl
node_generated_rtl -->|"stored in"| node_workspace
node_generated_rtl -->|"checked by"| node_lint
node_spec -->|"guides"| node_testbench_agent
node_testbench_agent -->|"provides C++ testbench"| node_simulation
node_generated_rtl -->|"simulated with"| node_simulation
node_simulation -->|"emits"| node_sim_artifacts
node_sim_artifacts -->|"parsed by"| node_debug_parser
node_skills -->|"invokes for PnR"| node_mcp_server
node_mcp_server -->|"exposes"| node_mcp_stage_tool
node_mcp_stage_tool -->|"runs"| node_physical_flow
node_generated_rtl -->|"RTL input"| node_physical_flow
node_pnr_inputs -->|"configures"| node_physical_flow
node_physical_flow -->|"produces"| node_pnr_reports
node_physical_flow -->|"exports"| node_gds

click node_installer "https://github.com/xsw632/chipagent/blob/main/bin/install.js"
click node_plugin_manifest "https://github.com/xsw632/chipagent/blob/main/.claude-plugin/plugin.json"
click node_skills "https://github.com/xsw632/chipagent/blob/main/skills/workflow/SKILL.md"
click node_agents "https://github.com/xsw632/chipagent/blob/main/agents/requirement-parser.md"
click node_chisel_source "https://github.com/xsw632/chipagent/blob/main/chisel-project/src/main/scala/chipagent/ALU.scala"
click node_chisel_emitter "https://github.com/xsw632/chipagent/blob/main/chisel-project/src/main/scala/chipagent/Generate.scala"
click node_generated_rtl "https://github.com/xsw632/chipagent/blob/main/MyDesign/ALU8/workspace/generated/ALU8.v"
click node_compile "https://github.com/xsw632/chipagent/blob/main/scripts/compile.sh"
click node_lint "https://github.com/xsw632/chipagent/blob/main/scripts/lint.sh"
click node_testbench_agent "https://github.com/xsw632/chipagent/blob/main/agents/testbench-generator.md"
click node_simulation "https://github.com/xsw632/chipagent/blob/main/scripts/simulate.sh"
click node_sim_artifacts "https://github.com/xsw632/chipagent/blob/main/MyDesign/ALU8/workspace/sim/logs/ALU8.vcd"
click node_debug_parser "https://github.com/xsw632/chipagent/blob/main/scripts/parse_vcd.py"
click node_mcp_server "https://github.com/xsw632/chipagent/blob/main/mcp-server/index.ts"
click node_mcp_stage_tool "https://github.com/xsw632/chipagent/blob/main/mcp-server/tools/run-stage.ts"
click node_pnr_inputs "https://github.com/xsw632/chipagent/blob/main/MyDesign/ALU8/workspace/pnr/config.mk"
click node_pnr_reports "https://github.com/xsw632/chipagent/blob/main/MyDesign/ALU8/workspace/pnr/reports/sky130hd/ALU8/base/6_finish.rpt"
click node_gds "https://github.com/xsw632/chipagent/blob/main/MyDesign/ALU8/workspace/pnr/results/sky130hd/ALU8/base/6_final.gds"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_installer,node_plugin_manifest,node_skills,node_agents toneBlue
class node_workspace,node_spec,node_chisel_source,node_chisel_emitter,node_generated_rtl toneAmber
class node_compile,node_lint,node_testbench_agent,node_simulation,node_sim_artifacts,node_debug_parser toneMint
class node_mcp_server,node_mcp_stage_tool,node_pnr_inputs,node_physical_flow,node_pnr_reports,node_gds toneRose
```

## Components

### Plugin control plane

- [npm installer](https://github.com/xsw632/chipagent/blob/main/bin/install.js): Node installer · Installs the Claude Code plugin. · `bin/install.js`
- [Plugin registration](https://github.com/xsw632/chipagent/blob/main/.claude-plugin/plugin.json): Claude plugin manifest · `.claude-plugin/plugin.json`
- [Slash-command skills](https://github.com/xsw632/chipagent/blob/main/skills/workflow/SKILL.md): Claude skill control plane · Workflow, generation, debug, and PnR commands drive the pipeline. · `skills/workflow/SKILL.md`
- [Generation agents](https://github.com/xsw632/chipagent/blob/main/agents/requirement-parser.md): Agent prompts · Specialized prompts normalize requirements and generate Chisel. · `agents/requirement-parser.md`

### Design workspace

Per-design durable inputs, generated artifacts, and results.

- **Per-design workspace**: Filesystem boundary · Isolates each design's specification, RTL, simulation, and PnR state.
- **Hardware contract**: Structured specification
- [Chisel design source](https://github.com/xsw632/chipagent/blob/main/chisel-project/src/main/scala/chipagent/ALU.scala): Scala/Chisel RTL · `chisel-project/src/main/scala/chipagent/ALU.scala`
- [Verilog emitter](https://github.com/xsw632/chipagent/blob/main/chisel-project/src/main/scala/chipagent/Generate.scala): Scala main · Generic Chisel/FIRRTL emission entry point. · `chisel-project/src/main/scala/chipagent/Generate.scala`
- [Generated RTL and FIRRTL](https://github.com/xsw632/chipagent/blob/main/MyDesign/ALU8/workspace/generated/ALU8.v): Verilog artifacts · Includes annotations, FIRRTL IR, and emitted Verilog. · `MyDesign/ALU8/workspace/generated/ALU8.v`

### RTL verification

- [Compile RTL](https://github.com/xsw632/chipagent/blob/main/scripts/compile.sh): Bash wrapper · Runs sbt, Chisel, and FIRRTL. · `scripts/compile.sh`
- [Lint RTL](https://github.com/xsw632/chipagent/blob/main/scripts/lint.sh): Verilator wrapper · `scripts/lint.sh`
- [Testbench agent](https://github.com/xsw632/chipagent/blob/main/agents/testbench-generator.md): Agent prompt · `agents/testbench-generator.md`
- [Simulation runner](https://github.com/xsw632/chipagent/blob/main/scripts/simulate.sh): Verilator wrapper · Builds RTL with the generated C++ testbench. · `scripts/simulate.sh`
- [Simulation logs and VCD](https://github.com/xsw632/chipagent/blob/main/MyDesign/ALU8/workspace/sim/logs/ALU8.vcd): Verification artifacts · `MyDesign/ALU8/workspace/sim/logs/ALU8.vcd`
- [Waveform parser](https://github.com/xsw632/chipagent/blob/main/scripts/parse_vcd.py): Python utility · Externalizes VCD parsing for debug analysis. · `scripts/parse_vcd.py`

### Physical design

- [PnR MCP server](https://github.com/xsw632/chipagent/blob/main/mcp-server/index.ts): TypeScript/Node server · Persistent tool boundary between plugin orchestration and EDA execution. · `mcp-server/index.ts`
- [Stage execution tool](https://github.com/xsw632/chipagent/blob/main/mcp-server/tools/run-stage.ts): MCP tool · `mcp-server/tools/run-stage.ts`
- [PnR config and constraints](https://github.com/xsw632/chipagent/blob/main/MyDesign/ALU8/workspace/pnr/config.mk): OpenROAD inputs · `MyDesign/ALU8/workspace/pnr/config.mk`
- **OpenROAD physical flow**: EDA pipeline · Synthesis through floorplan, placement, CTS, routing, fill, and GDS export.
- [QoR reports](https://github.com/xsw632/chipagent/blob/main/MyDesign/ALU8/workspace/pnr/reports/sky130hd/ALU8/base/6_finish.rpt): PnR reports · `MyDesign/ALU8/workspace/pnr/reports/sky130hd/ALU8/base/6_finish.rpt`
- [Final GDS](https://github.com/xsw632/chipagent/blob/main/MyDesign/ALU8/workspace/pnr/results/sky130hd/ALU8/base/6_final.gds): Physical design output · `MyDesign/ALU8/workspace/pnr/results/sky130hd/ALU8/base/6_final.gds`

## Connections

- 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