Skip to content

The AI assistant

The assistant plans your design with you, then writes RTL and testbenches, runs your tools and reads their results. It works only through actions that Chipforge shows you. In Manual mode it asks before it changes anything. In Auto mode it edits files and runs lint and simulations without asking, and still asks before builds, IP generation, target changes, programming a board and shell commands.

  • On the Plan page, the conversation fills the page.
  • On the other project pages, select Toggle AI panel in the top bar. The AI Assistant panel opens on the right. Select New chat to start a chat, or Chat history to go back to an earlier chat in this project.

Type in the box at the bottom and press Enter to send. Shift+Enter starts a new line. To give the assistant a file, type @ and pick a project file, select Attach a project file, or drag a file onto the box. You can also attach images and documents such as PDFs and datasheets.

The assistant works through a fixed set of actions. The desktop app carries out each one on the machine where your project is. The assistant can:

  • read and list the files in your project;
  • create and edit files;
  • lint your HDL, and run simulations;
  • run synthesis, implementation and bitstream generation;
  • browse the Vivado IP catalog and generate IP;
  • search for FPGA parts and boards, and set the project’s target and toolchain;
  • find connected boards and program them;
  • run shell commands in your project folder.

The assistant sees your messages and attachments, the approved plan, your project’s target and simulator, the design decisions you’ve agreed in earlier chats, and the files it reads. All of this, and the output of the tools it runs, is sent to the Chipforge service and to the AI model as part of the chat. Chipforge chooses the model; you can’t change it.

Each chat is also saved in your project, under chipforge/chats/.

Under the message box, Agent mode sets how much the assistant does without asking. Each project remembers its own mode. When you approve a plan, the button you choose sets it.

Manual Auto
Read and list files, browse the IP catalog, search parts, find boards Doesn’t ask Doesn’t ask
Create and edit files Asks Doesn’t ask
Lint and simulate Asks Doesn’t ask
Synthesis, implementation and bitstream; generating IP; changing the target or toolchain; programming a board; running a shell command Asks Asks

Manual is the default.

When the assistant needs your approval, a card appears above the message box, and the assistant waits for your answer. The card says what the assistant wants to do, and shows the file, run or full command.

  • Approve lets the assistant do this one thing.
  • Always allow this session approves this action, and lets the assistant do the same kind of action without asking again for the rest of this chat. For shell commands, that means any command, not only the one on the card.
  • Deny refuses, and stops what the assistant is doing.
  • Reply instead refuses and lets you tell the assistant what to do instead. The assistant carries on with your reply.

In Manual mode, a file edit comes as a card showing the change. Select Accept to write it to the file, or Open in editor → to look at it in full first. Nothing is written until you accept.

When the assistant has a question, it shows a card of options. Pick one, or write your own answer, and select Answer.

The assistant can run a shell command in your project folder after you approve it. The card names the machine: “Run a shell command on your machine.” or “Run a shell command on” followed by the name of your remote server.

  • On your computer, a command runs in your own shell, with your environment: your login shell on macOS and Linux, and PowerShell on Windows. A login bash reads ~/.bash_profile or ~/.profile, but not ~/.bashrc, so set up your tools in one of the former.
  • On a remote server, a command runs through the companion there, under your account on the server. The server needs companion 0.3.3 or later.

The Agent tab of the bottom panel lists every command the assistant ran, with its output. Press Ctrl+J, or Cmd+J on a Mac, to open the panel. A command that runs too long is stopped, and the tab says its output is partial.

Chipforge records each command the assistant runs, in full, in a log that stays on the machine where it ran:

  • on your computer, in the audit folder of Chipforge’s data folder: %LOCALAPPDATA%\dev.chipforge.desktop\audit on Windows, ~/Library/Application Support/dev.chipforge.desktop/audit on macOS, and ~/.local/share/dev.chipforge.desktop/audit on Linux;
  • on a remote server, in ~/.config/Chipforge/agent/audit.

Administrators can turn off the assistant’s commands, and the terminal, for an installation of the desktop app by setting the environment variable CHIPFORGE_SHELL=off. On a remote server, starting the companion with CHIPFORGE_AGENT_EXEC=0 turns off the assistant’s commands there.

While the assistant works, the send button becomes Stop. Select it to stop the assistant. It stops once the step in progress is over.

After a run, the chat lists the files it changed. Select Undo next to a file to put it back as it was before the run, or Undo all. If you’ve changed a file since, Chipforge asks whether to Overwrite your changes or Keep current.

Undo puts files back. It doesn’t reverse commands the assistant ran, IP it generated or a board it programmed.

  • The assistant stops partway, with a note on where it stopped. It reached its limit of steps for one message. Send another message to let it carry on.
  • “This chat hit its limit. Please continue in a new chat.” Select Continue in new chat. The new chat starts with a short handover of where the work stands, which you can edit before you send your first message. Once a chat is about half full, a ring in the message box shows how much room is left.
  • “Run failed: …” Something stopped the run. If the reason is “The AI service is temporarily unavailable. Please try again in a moment, or contact support if it persists.”, try again shortly.
  • “Connection to the agent was lost. …” The app lost its link to the Chipforge service. The run may still be going. Wait, or select Stop.

For other messages, see Troubleshooting.