The GDSFactory+ AI Agent is an assistant built into VS Code that helps you troubleshoot issues, design components, run verification checks, and work with GDSFactory+ features — all through a chat interface.

Getting Started¶

Enabling the Agent¶

The AI Agent must be enabled for your organization. Organization administrators can enable or disable the agent feature through the GDSFactory+ customer portal.

The first time you open the agent, you will be asked to accept the Terms & Conditions. This is a one-time step per user.

Opening the Agent¶

The primary way to open the agent is the wand button in the top-left toolbar of the GF+ sidebar.

You can also open the agent via:

• Status bar: Click GF+ Agent [Beta] in the bottom-right status bar
• Command palette: Run GDSFactory+: Open Agent
• Configuration panel: Click Ask Assistant when you see setup errors
• Issue report: Click Open Assistant in the issue report form

The agent opens as an editor tab in your main editor area.

Using Your Own API Key (optional)¶

The agent works out of the box — no setup required. It uses your GDSFactory+ subscription to provide AI credits at no extra cost.

If you prefer to use your own Anthropic API key instead, open the Settings tab in the agent chat. Switch the provider to Anthropic, then paste your key and click Save Key.

When using your GDSFactory+ subscription, the Settings tab also shows your token budget — a usage bar with tokens used, cap, and remaining for the current period.

The Chat Interface¶

The agent chat has three tabs:

• Chat — Your active conversation
• Sessions — Previous conversations you can resume
• Settings — AI provider and model configuration

Model and Effort¶

Next to the input area, a picker lets you choose the Claude model and reasoning effort:

• Model: Haiku 4.5 (fast, light), Sonnet 4.6 (default, balanced), or Opus 4.6 (most capable)
• Effort: Low, Medium, High (default), or Max — controls how much reasoning the model does per response

Lower model and effort settings are faster and use fewer tokens.

Context Window¶

A bar at the bottom of the chat shows how much of the conversation context is used. Long conversations gradually fill this up; start a new session when it gets high.

Sending Messages¶

Type your message in the input area at the bottom and press Enter to send. Use Shift+Enter for a new line.

The agent responds with streaming text — you'll see the response appear token by token. While the agent is working, you can:

• Press Escape or click the stop button to cancel
• Type a new message and press Enter to interrupt and redirect

Quick Actions¶

Pre-built prompts are available as clickable buttons above the input area. The available actions change depending on which modes are active:

Modes¶

Modes teach the agent about specific capabilities. When a mode is active, the agent gains specialized knowledge and workflows for that domain.

Select modes using the toggle chips at the top of the chat. You can have multiple modes active at once.

Available Modes¶

How Modes Work¶

• Click a mode chip to toggle it on or off
• When you send your first message with modes selected, the agent loads that knowledge before responding
• Toggle a mode on mid-conversation and it loads immediately
• Your mode selection is remembered for the session

Some entry points auto-load modes for you. For example, clicking Ask Assistant in the Configuration panel automatically activates Support mode.

What the Agent Can Do¶

The agent has access to tools that let it inspect and interact with your GDSFactory+ environment.

Diagnostics (Support mode)¶

• Check extension status: See the health of your Python environment, server, watcher, and all setup stages — the same information shown in the Status Panel and Configuration Panel
• Read logs: Access recent server and watcher logs to identify errors
• Execute fixes: Restart the server, reconfigure settings, install packages, and resolve setup issues

Component Design (Design mode)¶

• Build cells: Write Python cell factories, build them, and open the GDS viewer to inspect the result
• Explore the PDK: List available cells, inspect their ports and settings
• Iterate on errors: When a build fails, the agent reads the error, fixes the code, and rebuilds automatically

Verification (Verification mode)¶

• Run DRC: Check your layout against the PDK's design rules
• Check connectivity: Verify that ports are properly connected
• Run LVS: Compare your layout against a schematic netlist

General¶

• Inspect files: Read your project files, configuration, and Python code
• Run VS Code commands: Open viewers, trigger builds, switch panels
• Set up projects: Download and configure sample projects to get you started

Safety & Confirmations¶

The agent asks for your permission before taking any action that modifies your environment.

Auto-allowed (no confirmation needed)¶

• Reading files, logs, and status
• Running diagnostics
• Opening UI panels and viewers
• Loading modes and workflows

Requires confirmation¶

When the agent needs to do something that changes your system, you'll see a confirmation prompt:

Examples of actions that require confirmation:

• Creating or editing files
• Restarting the server or watcher
• Installing packages
• Downloading sample projects

You can choose:

• Allow — approve this specific action
• Deny — reject and let the agent try a different approach
• Allow All — auto-approve similar actions for the rest of this session

Allow All tracks file writes and shell commands separately — approving all file writes does not also approve shell commands, and vice versa. When active, a yellow banner appears at the top of the chat with a Revoke button to turn it off.

Always blocked¶

Some actions are never allowed, even with Allow All active:

• Running commands as root (sudo, doas)
• Destructive file operations (rm -rf)
• Pushing to git remotes
• Network requests to external URLs

Sessions & History¶

Your conversations persist across VS Code sessions.

Multiple conversations¶

You can have multiple agent tabs open at the same time, each running an independent conversation. Click the wand button or New Chat to start another one. The status bar shows how many sessions are active — for example, GF+ Agent (2 running) — and flags any that need your attention.

Use Cmd+Shift+A (Windows/Linux: Ctrl+Shift+A) to open a quick-pick list of all sessions and jump between them.

Browsing past sessions¶

Switch to the Sessions tab to see all conversations, grouped into active, recent (last 24 hours), and older. Each entry shows a status dot, the conversation title, and the message count.

Click a session to resume it. Click the trash icon to delete it.

All conversation data is stored locally on your machine.

Using the MCP Server with Other AI Assistants¶

The built-in agent is not the only way to use AI with GDSFactory+. The gfp-mcp package is a standalone Model Context Protocol server that connects any MCP-compatible AI assistant to your running GDSFactory+ projects. This includes tools like Claude Code, Claude Desktop, and Cursor.

The MCP server provides the same core design tools — building cells, exploring the PDK, running verification checks, and simulating components — but through your AI assistant of choice.

Installation¶

The MCP server auto-discovers running GDSFactory+ projects, so there is no project-specific configuration needed. Just install it in your preferred AI assistant:

Claude Code:

claude mcp add gdsfactoryplus -- uvx --from gfp-mcp gfp-mcp-serve

Cursor (in .cursor/mcp.json):

{
    "mcpServers": {
        "gdsfactoryplus": {
            "command": "uvx",
            "args": ["--from", "gfp-mcp", "gfp-mcp-serve"]
        }
    }
}

Claude Desktop (in claude_desktop_config.json):

{
    "mcpServers": {
        "gdsfactoryplus": {
            "command": "uvx",
            "args": ["--from", "gfp-mcp", "gfp-mcp-serve"]
        }
    }
}

Available Tools¶

For more details, see the gfp-mcp documentation.

Learn More¶

• Ask the Agent — Diagnose and fix setup issues
• Build a Component — Design a photonic component with the agent
• Troubleshooting — Common issues and solutions