vCode User Guide

vCode is the Artificial Labs AI coding agent for your local machine. It's a single binary that runs in your terminal: you describe what you want, and the same cloud agent that powers the Code panel plans and executes the work — reading, editing, and running code on your computer, under a permission system you control.

Your sessions live in the cloud, so history, token usage, and cost are always visible in the panel, and a dropped connection never loses work. This guide covers vCode Desktop v1.5.0+.

1. Installation

Windows

One-line install (PowerShell):

iwr https://<your-panel-host>:8080/install.ps1 -UseBasicParsing | iex

Or download vcode.exe from the panel's vCode page and put it somewhere on your PATH.

Linux

Download vcode-linux-amd64 from the panel's vCode page, then:

chmod +x vcode-linux-amd64
sudo mv vcode-linux-amd64 /usr/local/bin/vcode

Anywhere

If you already have the binary, vcode install copies itself onto your PATH.

vCode checks for updates at startup and tells you when a newer version is available. vcode completion bash|zsh|fish|powershell generates shell completions.

2. Signing in

vcode login

This opens your browser for SSO. Once approved, the token is stored locally and reused.

• vcode whoami — show who you're logged in as
• vcode logout — clear the saved token

3. Basic usage

From your project directory:

vcode

This starts an interactive session. Type what you want done:

> add input validation to the signup form and write a test for it

The agent streams its thinking, proposes actions, asks your permission where required, executes, and iterates until done.

Useful startup flags

• vcode -c / vcode --continue — resume your most recent session
• vcode --permission-mode acceptEdits — start in a specific permission mode
• vcode --yes — bypass all permission prompts (trusted projects only)

Sessions

Every conversation is a named session stored in the cloud.

• vcode sessions — list your sessions (--verbose adds full token usage)
• vcode switch [session] — switch the active session
• vcode delete <name-or-id> — delete a session and its messages
• vcode -c — continue the most recent one

Steering and stopping

• Type while the agent is working to queue steering guidance, or from another terminal: vcode steer "use pnpm, not npm"
• /stop in the session (or vcode stop from another terminal) halts the run.

4. Talking to the agent

@-mention files and images

Reference project files directly in your message:

> refactor @src/auth/login.js to use async/await

The file's contents are attached automatically (up to 400 lines inline). Mentioning an image (@mockup.png, up to 10MB) uploads it so vision-capable models can see it — great for screenshots of bugs or design mockups.

Slash commands

• /help — list all commands
• /status — session, model, mode, connection info
• /cost — token usage and estimated cost for this session
• /clear — start a fresh conversation
• /compact — summarize the conversation to free up context
• /stop — stop the current iteration
• /init — analyze the project and generate a VCODE.md memory file
• /memory — open your memory files in $EDITOR
• /model — list available models and switch the session's model
• /plan — toggle plan mode (agent proposes, doesn't touch)
• /rewind — restore files from a checkpoint
• /mcp — list connected MCP servers and their tools
• /terminals — show the agent's background terminal sessions
• /doctor — diagnose connectivity, auth, and version

Custom slash commands

Drop a markdown file in .vcode/commands/ (project) or ~/.vcode/commands/ (personal) and it becomes a slash command. The file's content is sent as the prompt; $ARGUMENTS is replaced with whatever you type after the command.

5. Permissions

Every action the agent takes is classified (read / edit / execute / network / other) and checked against your permission settings before it runs.

Modes

• default — reads are free; edits and commands ask for approval the first time
• acceptEdits — file edits auto-approved; commands still ask
• plan — read-only: the agent can look but not touch
• bypass — everything auto-approved (--yes); for trusted projects only

Approval prompt

When approval is needed you'll see the exact action (with diff or command) and choose: allow once, allow always (writes a rule), or deny. Denials are explained to the agent so it can take a different approach.

Rules

Persistent rules live in settings files and take the form action_type(glob):

{
  "permissions": {
    "allow": ["run_command(npm test*)", "update_file(src/**)"],
    "deny":  ["run_command(rm -rf*)", "read_file(.env*)"]
  }
}

Precedence: deny > read-only > mode > allow > prompt.

Settings files

• ~/.vcode/settings.json — personal, all projects
• <project>/.vcode/settings.json — shared with your team (commit it)
• <project>/.vcode/settings.local.json — personal, this project (gitignore it)

6. Memory

vCode loads memory files into every session, so the agent starts already knowing your conventions:

• ~/.vcode/VCODE.md — personal notes that apply everywhere
• <project>/VCODE.md — project conventions
• <project>/VCODE.local.md — personal, project-specific notes

A line containing @path/to/file.md inside a memory file imports that file (one hop). Start a message with # to quick-add a note. /init generates a starter VCODE.md by analyzing the project, and /memory opens the files in your $EDITOR.

7. Checkpoints

Before the agent modifies a file, vCode snapshots it. If a change goes wrong:

/rewind

Pick a checkpoint, and your files are restored to that moment. Checkpoints are local and per-session — an automatic safety net under the agent.

8. Hooks

Automate policy and glue with shell hooks in .vcode/settings.json:

{
  "hooks": {
    "PreToolUse":  [{ "matcher": "run_command",             "command": "./scripts/audit.sh" }],
    "PostToolUse": [{ "matcher": "update_file|create_file", "command": "npx prettier --write ." }],
    "Stop":        [{ "matcher": "*",                       "command": "notify-send 'vCode done'" }]
  }
}

• PreToolUse runs before an action; a non-zero exit blocks the action.
• PostToolUse runs after an action completes.
• Stop runs when the agent finishes a task.
• Matchers are |-separated globs on the action type. Hooks receive a JSON payload on stdin and have 30 seconds to finish.

9. MCP

vCode speaks the Model Context Protocol. Any stdio MCP server's tools become available to the agent:

vcode mcp add github npx -- -y @modelcontextprotocol/server-github
vcode mcp add mydb ./db-server --env DB_URL=postgres://localhost/dev
vcode mcp list
vcode mcp remove mydb

Configuration lives in ~/.vcode/mcp.json (personal) and <project>/.vcode/mcp.json (shared). Tools appear as mcp__server__tool, are listed by /mcp, and go through the same permission prompts and hooks as every other action.

10. Configuration reference

• vcode config show — current configuration
• vcode config set <key> <value> — set a value (e.g. server URL, default model)

File map

• ~/.vcode/ — auth token, config, history, personal settings/memory/commands/mcp.json
• <project>/.vcode/ — settings.json, settings.local.json, commands/, mcp.json
• <project>/VCODE.md, VCODE.local.md — project memory

Line editing: history persists across sessions (~/.vcode/history), and Tab completes slash commands and @ file paths.

11. Troubleshooting

• First stop: /doctor — checks auth, server connectivity, and whether your binary is up to date.
• "Permission denied" loops — the agent was denied and told not to retry; approve the action, add an allow rule, or tell it a different approach.
• Update available banner — download the new binary from the panel's vCode page and replace the old one (or re-run the install one-liner).
• Session feels confused — /compact to summarize, or /clear for a clean slate; memory files survive clears.
• Windows SmartScreen warning — expected for an unsigned binary; choose "More info → Run anyway".
• Agent can't see a file — @-mention it, or check deny rules aren't blocking reads.
• Something broke my working tree — /rewind to a checkpoint.