Vectrex Studio has a real terminal inside the IDE. Type claude in it and Claude Code starts already connected to the running IDE: it can read your project, build and run it, look up the API, create assets the compiler has checked, and upload to or debug on the cartridge.
The integrated terminal
The terminal is a real shell, not a log view: xterm.js in the IDE, a native PTY (node-pty) in the Electron main process.
| Action | How |
|---|---|
| Show / hide the terminal | View → Terminal, or Ctrl+` |
| New terminal tab | The + button in the panel, or Ctrl+Shift+` |
| Rename a tab | Double-click its title |
| Close a tab | Its close button, or middle-click the tab (this kills the shell) |
| Restart an exited shell | Restart shell |
| Open Claude Code | The Claude button: a new tab running claude in the project folder |
Details worth knowing:
- Your shell, your environment. On macOS and Linux each terminal is a login shell, so it gets your full
PATH, aliases and prompt, the same as any other terminal. (An app started from the macOS Dock otherwise inherits a minimalPATH, and tools likeclaudewould not be found.) - It starts in the project folder. With no project open it starts in the default workspace,
~/VectrexStudio/projects, which is always the same folder. - Tabs survive. Switching tabs or hiding the panel keeps every shell and its scrollback.
- Links are clickable.
http(s)links printed in the terminal open in your browser.
If Claude Code is not installed, the Claude button prints the one-line install command for your system instead (curl … | bash on macOS and Linux, irm … | iex in PowerShell).
Claude Code inside the IDE
Typing claude in an IDE terminal starts Claude Code with the IDE's MCP server already registered. You configure nothing, and nothing is written into your project.
How it is connected: shell integration
Claude Code has one documented way to add an MCP server at start-up, the --mcp-config flag. The IDE's terminals define a small claude function that adds that flag. It is defined after your own startup files have run, so your shell otherwise behaves exactly as usual. This is the same technique VS Code uses for its shell integration:
| Shell | How the integration loads |
|---|---|
| zsh | Through a ZDOTDIR whose files source your own startup files. Your history stays in your own folder |
| bash | Through --init-file, which reproduces a login shell's startup (/etc/profile, then .bash_profile, .bash_login or .profile) |
| fish | Through --init-command |
| PowerShell | Through -NoExit -Command, after your profile |
Other shells (sh, dash, cmd.exe) run unchanged: there claude is plain Claude Code, without the IDE's tools.
Claude Code subcommands that are not a session (claude mcp, claude config, claude update, claude doctor and so on) run without the extra flag. The MCP config file lives in the app's own data folder.
Resumable sessions
Claude Code keys its sessions by folder: claude --resume lists only the sessions started in the current folder. The IDE's terminals always start in a predictable folder, the open project's folder or the default workspace, so claude --resume finds the conversations you had about that project. The IDE waits briefly for the last project to reopen before starting the first terminal, so it does not start in your home folder by accident.
What Claude Code is told
When Claude Code connects, the MCP server hands it a short set of instructions. They open with a checklist to follow before writing code:
- Call
ide_get_contextfirst. It carries the project's assets and its language API. - Make all art, sound, levels and animation with
asset_create. - Look the API up with
api_referenceinstead of searching the SDK or compiler sources. - Build and run with
ide_run.
They also explain what VPy, "the SDK" and the four targets mean, and which ide_run mode matches F7, F5, Shift+F5 and Shift+F7.
Pasting images and dropping files
A terminal carries only text, so the IDE turns images and files into paths:
- Paste a clipboard image (a screenshot, say) with Cmd+V on macOS, or Ctrl+Shift+V or Ctrl+V on Windows. The IDE saves it as a PNG in the system temp folder (
vectrex-studio-paste/, cleared after a day) and pastes its path. Claude Code attaches a pasted image path, so you can show it what the emulator draws. - Drag files onto the terminal to paste their paths the same way.
The MCP server
The MCP server exposes the IDE to AI assistants through the Model Context Protocol: Claude Code, Claude Desktop, or any MCP client.
Connection
MCP client ⇄ stdio ⇄ server.js ⇄ TCP 127.0.0.1 (authenticated) ⇄ the running IDE
- The AI client starts
server.jsand talks to it over stdio. server.jsconnects to the running IDE over TCP on127.0.0.1, port 9123 (or the next free one up to 9133).- Every connection must authenticate with a random token the IDE generates at startup and keeps in memory only. The port and token travel in
VECTREX_STUDIO_MCP_PORTandVECTREX_STUDIO_MCP_TOKEN, so only processes the IDE launches can drive it. The token changes every time the IDE starts. - The server runs on the IDE's own Electron binary, so you do not need a separate Node install.
- If the IDE is not running, the server still starts. Tool calls return a "Vectrex Studio is not running / not reachable" error, and the server reconnects on its own once the IDE is up.
The tool list is served by the IDE itself, so it always matches what the IDE implements. File access is confined to the open project's folder. The emulator, debugger and memory tools need the Emulator panel open. A tool reports success only when it actually did the thing. A failure comes back as a tool error with the reason.
Tools
| Group | Tools |
|---|---|
| IDE | ide_get_context, ide_run, settings_set_build_target, cartridge_upload, cartridge_debug, cartridge_debug_stop |
| Reference | api_reference |
| Editor | editor_list_documents, editor_read_document, editor_write_document, editor_save_document, editor_get_diagnostics, editor_replace_range, editor_insert_at, editor_delete_range |
| Compiler | compiler_build, compiler_build_and_run, compiler_get_errors |
| Emulator | emulator_run, emulator_get_state, emulator_stop |
| Memory | memory_dump, memory_list_variables, memory_read_variable, memory_write |
| Debugger | debugger_start, debugger_continue, debugger_pause, debugger_step_into, debugger_step_over, debugger_step_out, debugger_add_breakpoint, debugger_remove_breakpoint, debugger_list_breakpoints, debugger_clear_breakpoints, debugger_get_callstack, debugger_get_registers |
| Project | project_open, project_close, project_create, project_get_structure, project_read_file, project_write_file, project_create_vector, project_create_music, project_create_sfx |
| Assets | assets_list, asset_get_format, asset_create |
| Local | get_project_docs (answered by the server itself, works without the IDE) |
The ones you will see most
| Tool | What it does |
|---|---|
ide_get_context | The open project (kind VPy or C, entry, pinned SDK and whether it is installed), the selected target and the targets it can build, what F7 / F5 / Shift+F5 / Shift+F7 would do right now, the emulator state, the Arm toolchain status and the IDE version. With a project open it also lists the project's assets with the code that uses each one, and the language's calls on the selected target with short how-to recipes |
ide_run | Build and run, the same as the keys: build = F7, run = F5, simulate = Shift+F5, build_simulator = Shift+F7. It waits for the build and for the emulator to load the result, and returns the outcome with the tail of the build output. With no mode it picks simulate on rp2350, pitrex and uvm2 and run on m6809 |
api_reference | The full API of the open project's language, generated from the real sources: VPy from the compiler's builtin catalogue with per-target availability, C from the headers of the project's pinned SDK. Filter by topic or query |
assets_list | The project's assets by type, each with the exact code that uses it in the project's language |
asset_get_format | A type's format, a minimal valid example, its folder, editor, targets and usage |
asset_create | Writes assets/<folder>/<name>.<ext>, checks that what it references exists, and compiles it with the real compiler. On a compile error the file is removed (or the old one restored) and the compiler's message is returned. It refuses to overwrite an asset unless asked to |
project_create | A new VPy or C project from the same templates as File → New → Project, in the default workspace unless you give a location |
cartridge_upload | Build → Upload to Cartridge (UVMC2, USB) |
cartridge_debug / cartridge_debug_stop | Debug on Cartridge (UVMC2, USB) and stopping it |
settings_set_build_target | Sets the build target, like the Settings panel. It warns when the open C project has no recipe for that target |
Asset formats and the code that uses each one: see the "Using it from VPy and C" section of each editor page, for example Vector Editor. Cartridge upload and debugging: Cartridges and Debugging.
PyPilot, the built-in assistant
PyPilot is the AI assistant panel built into the IDE. It understands VPy and the Vectrex hardware, can write and edit code and create assets, and controls the IDE through the same tool handlers as the MCP server. It calls them from inside the app, so it needs no token.
Providers
Pick and configure a provider in PyPilot's Config panel. Keys, model and endpoint are saved per provider.
| Provider | Type | Notes |
|---|---|---|
| Ollama | Local | Runs on your machine. No API key, no cost, fully private |
| Anthropic Claude | Cloud | API key |
| OpenAI | Cloud | API key. gpt-4o / gpt-4o-mini |
| Google Gemini | Cloud | API key |
| DeepSeek | Cloud | API key. Free tier available |
| GitHub Models | Cloud | GitHub Personal Access Token |
| Groq | Cloud | API key. Fast inference, free tier available |
For local AI, install Ollama and pull a model:
brew install ollama
brew services start ollama
ollama pull qwen2.5:7b # recommended modelThen select Ollama (Local) in PyPilot's config panel. The Ollama Manager downloads, switches and deletes models without leaving the IDE.
Slash commands
| Command | Action |
|---|---|
/help | Show all commands |
/clear | Clear the current session |
/settings | Open provider configuration |
/generate [description] | Generate VPy code from a description |
/explain | Explain the current or selected code |
/fix | Suggest fixes for the current compiler errors |
/optimize | Optimize the selected code |
/vectrex [command] | Syntax and examples for a Vectrex built-in |
/examples | VPy code examples |
/assets | Guide to using .vec and .vmus assets |
PyPilot attaches the open file to every message, and you can attach more with the attach button. Each project has its own conversation history, with sessions you can create, rename, switch and delete. Concise mode gives shorter answers.
For the rest of the IDE configuration, see Settings.