actoviq-circuit-agent

English | 简体中文

Interactive ngspice-based circuit-design Agent built on the published actoviq-agent-sdk package.

This project turns natural-language requirements into SPICE-oriented schematic design artifacts. It currently focuses on principle schematic design, netlist generation, ngspice simulation, SVG schematic rendering, and engineering report writing. It is not yet a PCB layout, IC layout, signoff, or production-hardware validation tool. Future work will add more practical design automation, richer component libraries, stronger schematic layout quality, and deeper verification flows.

What It Does

• Accepts natural-language circuit requirements from the terminal.
• Starts in a lightweight TUI by default for chat, slash commands, design, and revision workflows.
• Streams each agent stage in real time.
• Supports /allow manual, /allow execution, and /allow all confirmation policies.
• Generates English-safe job slugs even when the requirement is written in Chinese.
• Designs primitive-oriented SPICE netlists, runs ngspice verification, and renders netlistsvg schematics.
• Bundles circuit templates, Python helpers, and render assets inside this package.

Quick Start

1. Install the CLI

After the package is published, install it globally:

npm install -g actoviq-circuit-agent

For local source development:

npm install
python -m pip install schemdraw

2. Install and Configure ngspice

actoviq-circuit-agent does not bundle ngspice. Install ngspice separately, then configure it with either NGSPICE_BIN or your system PATH.

Recommended on Windows:

[Environment]::SetEnvironmentVariable(
  'NGSPICE_BIN',
  'C:\path\to\ngspice.exe',
  'User'
)

Open a new terminal after setting a permanent environment variable.

Temporary PowerShell session:

$env:NGSPICE_BIN='C:\path\to\ngspice.exe'

macOS/Linux:

export NGSPICE_BIN=/usr/local/bin/ngspice

You can also add ngspice to your system PATH.

Resolution priority:

1. Python script argument --ngspice-bin
2. Environment variable NGSPICE_BIN
3. Packaged embedded/circuit-design/tool_paths.json
4. ngspice found on system PATH

For npm users, prefer NGSPICE_BIN or PATH. Do not edit files inside the installed npm package.

3. About Red Error Messages

During agent execution you may see red error messages in the terminal. These are produced by agent tool calls and exist to show whether the agent can detect and self-correct errors. They do not mean the workflow has failed. The agent often retries with alternative approaches and continues normally. If the workflow reaches the final summary stage, the design is complete regardless of intermediate tool errors.

4. Configure the Actoviq Provider

actoviq-circuit-agent talks to the model through an Anthropic-compatible API (the same request/response format as https://api.anthropic.com/v1/messages). Any provider that exposes that interface — Anthropic itself, an enterprise gateway, or a self-hosted proxy — works as long as it accepts an Anthropic-style auth header and returns Anthropic-style streaming responses.

Create an Actoviq config in the directory where you will run the CLI, or use ~/.actoviq/settings.json.

mkdir my-circuit-workspace
cd my-circuit-workspace
copy C:\path\to\agent.settings.example.json .\actoviq.settings.json

Edit actoviq.settings.json and fill in your provider endpoint, token, and model names. Never commit real API keys.

5. Start the Agent

Run the CLI from the directory you want to use as the workspace:

actoviq-circuit-agent

The current directory becomes the workspace. Outputs are written to:

./jobs/<job-id>/
./sessions/

Inside the TUI:

/help
/allow execution
/design Design an op-amp gain stage followed by an RC filter and active-low comparator output.

Use /allow all for fully automatic stage transitions, or /allow manual to confirm every stage.

6. One-Shot Run

actoviq-circuit-agent --approval-policy execution --job-name rc-demo --requirement "Design a 1 kHz RC low-pass filter and output the netlist, simulation report, and SVG schematic."

For source checkout development, replace actoviq-circuit-agent with:

npm run dev -- --approval-policy execution --job-name rc-demo --requirement "Design a 1 kHz RC low-pass filter and output the netlist, simulation report, and SVG schematic."

Run From Source

npm run dev

The default entry opens the TUI. Type normal questions to chat with the general agent, or use slash commands:

/help
/allow execution
/design Design a 1 kHz RC low-pass filter
/modify Increase the output drive and redraw the schematic

Use the previous one-shot requirement prompt with:

npm run dev -- --legacy-cli

Source smoke run:

npm run dev -- --auto-approve --job-name rc-demo --requirement "Design a 1 kHz RC low-pass filter and output the netlist, simulation report, and netlistsvg schematic."

Linked Local CLI

For editable local installation:

npm link
actoviq-circuit-agent --help

When installed with npm link, the command uses the directory where you run it as the workspace root. Outputs go to:

./jobs/<job-id>/
./sessions/

Override that behavior with:

$env:ACTOVIQ_CIRCUIT_AGENT_WORKSPACE_ROOT='C:\path\to\workspace'

Config Resolution

Actoviq config is loaded in this order:

1. --config <path> or ACTOVIQ_AGENT_CONFIG_PATH
2. ./agent.settings.local.json in the current working directory
3. ./actoviq.settings.json in the current working directory
4. agent.settings.local.json in the package checkout
5. ~/.actoviq/settings.json

Do not commit real API keys. Use agent.settings.example.json as the template.

Large Circuit Partitioning

Large designs are partitioned by function during the design stage. The workflow writes planning/module-plan.json and design/module-manifest.json, then reuses those module boundaries during rendering. The final netlistsvg output is a single SVG sheet with labelled module/submodule sections; cross-module connectivity is represented by matching net labels and visible ports instead of long cross-sheet wires.

Rendering

The workflow generates schematics via the netlistsvg backend:

• render/netlistsvg.svg: primary schematic output for all circuits.

netlistsvg is a Node.js package required for rendering. Install it once:

npm install -g netlistsvg

Standalone Skill (Claude Code / Codex / Cursor)

The skills/circuit-design-ngspice/ directory contains a portable, agent-runtime-agnostic skill that captures the same circuit-design workflow without depending on actoviq-agent-sdk. It can be used directly inside Claude Code, OpenAI Codex, Cursor, or any AI coding tool that can read a Markdown prompt and execute shell commands.

Installing the Skill

Copy or symlink the skill directory into the agent's skill/plugin folder.

Claude Code:

# Option A: register as a custom slash command
mkdir C:\Users\<you>\.claude\skills\circuit-design-ngspice
xcopy /E skills\circuit-design-ngspice C:\Users\<you>\.claude\skills\circuit-design-ngspice\

Codex / OpenAI:

# The agents/openai.yaml provides the interface contract.
# Copy the entire skill directory into the Codex skills path.

Manual use with any agent:

Load SKILL.md into the agent's context and tell it to follow the instructions. All Python scripts are under skills/circuit-design-ngspice/scripts/ and accept standard argparse arguments.

Configuring ngspice for the Skill

The skill resolves ngspice in this order:

1. --ngspice-bin argument passed directly to Python scripts
2. NGSPICE_BIN environment variable
3. tool_paths.json in the skill root directory
4. system PATH

To configure it permanently, either set the environment variable (see section 2 above) or edit the skill's tool_paths.json:

{
  "ngspice_bin": "E:/Program/ngspice-45.2_64/Spice64/bin/ngspice.exe"
}

The skill reads tool_paths.json from its own directory, so each copy of the skill can point to a different ngspice installation.

Installing netlistsvg for the Skill

The render_netlistsvg.py script requires the netlistsvg CLI on your system PATH:

npm install -g netlistsvg

Verify it is reachable:

netlistsvg --help

Running a Design with the Skill

Tell the agent to load SKILL.md and provide a circuit requirement:

Please follow the circuit-design-ngspice skill in skills/circuit-design-ngspice/SKILL.md.
Design a 1 kHz RC low-pass filter and render the schematic.

The agent will create a workspace directory, run the 8-step workflow, and produce all design artifacts including design/design.final.cir, render/netlistsvg.svg, and reports/final-summary.md.

Validation

npm test
npm run build
npm run pack:dry-run