WalnutAI in VS Code: 10-Minute Setup Guide
Most VS Code extensions ask for five minutes and a restart. WalnutAI asks for ten, and by the end of it you'll have run a real session against your own codebase not a demo repo. This walkthrough covers every step in order: installing the extension, connecting your repo, running your first read-only exploration, moving into a planned task, and, once you're comfortable, running more than one agent at a time.
If you already have a WalnutAI account from the web app, the extension reuses it you're logging into the same account, just from inside your editor.
Before you start
VS Code 1.98.0 or later.
An active internet connection WalnutAI's models run server-side, not locally.
A free WalnutAI account. If you don't have one yet, sign up at app.walnutai.ai you can also create it during the install flow below.
A repo open in VS Code that you're comfortable letting an AI assistant read. You'll pick what it can change later.
Step 1: Install the extension
Open the Extensions view in VS Code (Ctrl+Shift+X / Cmd+Shift+X on Mac), search “Walnut AI,” and install the extension published by WalnutAI. Or skip the search: open Quick Open (Ctrl+P / Cmd+P), paste the install command below, and press Enter.
ext install WalnutAI.walnut
The extension is free to install. A Walnut icon appears in the Activity Bar on the side of VS Code once it's finished that's your entry point for everything from here on.
Step 2: Open the sidebar and log in
Click the Walnut icon in the Activity Bar to open the WalnutAI sidebar.
Sign in with your WalnutAI account. This authenticates against app.walnutai.ai the same login as the web app, so any team or project settings you've already configured there carry over.
Once signed in, the sidebar shows your available projects.
Step 3: Connect your repo and pick a project
Select the project that matches the repo you have open, or create a new one if this is the first time WalnutAI has seen this codebase. Connecting a repo doesn't hand over write access by default — what WalnutAI can read and change is controlled by the permission mode you're in, covered in the next section. File operations always require explicit approval unless you've switched to Auto mode yourself.
Step 4: Understand the three permission modes
Before running anything, it's worth knowing what each mode actually does — this is what decides whether WalnutAI asks first, acts automatically, or just looks around:
Mode | Description | |
Ask | WalnutAI proposes a change and waits for your approval before touching any file. | |
Auto | WalnutAI automatically applies changes it judges safe, without a prompt each time. | |
Plan | Read-only. WalnutAI explores the codebase and builds a plan before anything executes — use this for your first session on a new repo. |
Cycle between modes with Shift+Tab at any time, including mid-session.
Step 5: Run your first Explore query
For a first session on a codebase WalnutAI hasn't touched yet, stay in Plan mode. This is the “Explore” step: WalnutAI reads through your project structure and existing code without changing anything, so you can see what it understands before you let it act.
Type a broad, low-stakes question into the chat input to start something like “what does this repo do, and where's the authentication logic?” Use @ to mention specific files or folders directly, and / for quick commands like commit or review. WalnutAI's response will walk through what it found in your codebase, giving you a first read on how well it's mapped the project before you ask it to change anything.
This exploration step matters more than it looks like it should. It's the fastest way to catch a wrong assumption a misidentified framework, a missed config file before it shapes a plan you're about to approve.
Step 6: Run your first Plan session
Once the exploration looks right, switch to a real task. Describe what you want — a bug fix, a small feature, a refactor — and, still in Plan mode, WalnutAI will lay out its intended approach as a set of steps before touching a file. Review the plan the way you'd review a PR description: does the scope match what you asked for, and does anything look like it's touching more than it should?
Switch to Ask mode to execute it step by step with a prompt before each change, or Auto mode to let WalnutAI carry out the plan and only stop for anything it doesn't consider safe. Every change is git-snapshotted, so approving a step you want to undo later is a normal git revert, not a support ticket.
Step 7: Running more than one agent at once
Once a single session feels routine, WalnutAI supports running multiple agents in parallel useful when you've got independent work to hand off at the same time, like a bug fix in one module and a test-generation pass in another. Each agent keeps its own session history and its own permission mode, so a Plan-mode exploration in one panel doesn't block an Auto-mode task running in another.
This is also where WalnutAI's QA Mode agents come in if you're working test-first: Test Planner explores your app and builds a test plan, Test Generator turns that plan into Playwright scripts, and Test Healer diagnoses and fixes tests that start failing or flaking. They're built to run alongside your Development Mode session rather than instead of it.
What model is actually answering you
WalnutAI isn't tied to a single model. It supports Anthropic Claude (including Opus and Sonnet-class models), OpenAI's GPT line, Azure OpenAI, AWS Bedrock, and Google Gemini, plus any OpenAI-compatible custom endpoint. Use the model selector in the sidebar to pick one directly, or leave it on Auto and let WalnutAI route the request useful when you want a faster, cheaper model for a small exploration and a stronger one for a task that needs deeper reasoning.
Configuration worth knowing about
A few settings live under VS Code's normal settings (Ctrl+, / Cmd+,), searchable by their walnut. prefix:
walnut.server.url — the WalnutAI server endpoint, defaults to app.walnutai.ai.
walnut.playwright.enabled — turns on Playwright MCP for browser automation, relevant if you're using the QA agents.
walnut.playwright.browser — which browser engine Playwright automation uses (Chromium, Firefox, or WebKit).
On security: API keys are stored through VS Code's SecretStorage rather than in plain settings files, file changes need explicit approval unless you're in Auto mode, and WalnutAI doesn't train on your code without consent.
