Documentation

How to use wcagent

Install the VS Code extension, connect your wcagent account and model provider, then describe a coding outcome. wcagent gathers relevant repository context, runs approved tools locally, and gives you a diff and validation evidence to review.

The short version

Install wcagent from the Visual Studio Marketplace and open a repository in desktop VS Code.
Open wcagent and sign in.
Pair the bundled browser connector if your model uses a browser account.
Choose a model, reasoning effort, and access mode.
Describe the result you want, send the task, then review and apply the changes.

Before you start

Desktop VS Code 1.109 or newer. Browser-only vscode.dev and virtual workspaces are not supported.
A wcagent account. You need an active trial or paid plan and an internet connection.
Access to a supported model provider. Model access is separate from wcagent and remains subject to the provider’s limits and terms.
A Chromium browser for browser models. Use Chrome, Brave, or Edge with the provider account signed in.

You can inspect an untrusted workspace, but edits and commands require you to trust the workspace or choose an access mode that permits them.

1. Install the extension

Open wcagent on the Visual Studio Marketplace and select Install. Allow your browser to open VS Code when prompted.
Alternatively, open Extensions in VS Code, search for wcagent, confirm the publisher is wcagent, and select Install.
Open a local Git repository, then select the wcagent icon in the Activity Bar. You can also open the Command Palette and run wcagent: Open wcagent.

You can also install the Marketplace extension from a terminal:

code --install-extension wcagent.wcagent-agent

Select Sign in in the wcagent view, or run wcagent: Connect Account.
Your browser opens app.wcagent.ai. Sign in with email and password or Google, then approve the device connection.
Return to VS Code. Your account and available models appear in the composer.

The extension stores its device tokens in VS Code Secret Storage, which uses your operating system’s secure credential store.

3. Connect a browser model

Skip this section for a server-backed model. Browser-backed models use a connector that is already bundled with the wcagent extension. There is no separate connector download.

In VS Code, run wcagent: Open Browser Connector Folder. Leave this managed folder where wcagent created it; do not copy, move, or rename it.
In the browser profile where you are signed in to the model provider, open chrome://extensions, brave://extensions, or edge://extensions.
Turn on Developer mode, choose Load unpacked, and select the exact folder opened by wcagent. Keep Developer mode enabled.
Run wcagent: Pair Browser Model Connector. wcagent copies a one-time pairing value.
Open the connector from the browser toolbar, paste the pairing value, and finish pairing. The model selector in VS Code will show the connection when it is ready.

One connector per provider

Pair each browser provider you want to use. The connector works inside the provider’s signed-in browser profile and has no access to your repository. Provider cookies, passwords, and authentication headers stay in that browser profile.

When wcagent updates, it replaces the managed connector files. A loaded connector normally detects the update and reloads within about a minute. If it does not, select Reload for the connector on the browser extensions page.

4. Run your first task

Open the repository you want wcagent to work on.
In the composer, select the model, reasoning effort, and access mode you want.
Describe the outcome, important constraints, and how the result should be validated.
Add any specific files, folders, editor selection, or images with the + menu, then send the task.

A useful request is specific about the finished behavior without prescribing every implementation step:

Make the checkout handler idempotent.
Keep the existing public API unchanged, add regression tests,
and run the smallest relevant validation suite.

For a focused operation, use the Command Palette actions such as wcagent: Explain Selection or File, wcagent: Review File, or wcagent: Generate Tests.

Understand the composer

Model: Choose an available server-backed or paired browser model. If a browser model is offline, check its connector before sending.
Reasoning effort: Choose how much reasoning the selected model should use. Higher effort can help with difficult repository work but may take longer and use more of the provider’s allowance.
Access: Controls when wcagent must ask before it edits files, runs commands, or crosses another guarded boundary.
IDE context: A removable context tag adds bounded information from the active file, selection, open files, diagnostics, repository instructions, and ranked workspace metadata. Remove it when you want an explicit-files-only request.
Attachments: Use + to add a file, folder, current selection, or image. Large pasted text is sent as an attachment automatically.

Enable Review context before sending in settings if you want to inspect the context bundle for every task.

Choose access and isolation

Access mode	What happens	Use it when
Ask for approval	Edits, commands, internet access, and other guarded actions wait for your approval.	You want to review each local boundary.
Approve for me	Ordinary workspace edits and recognized validation commands proceed automatically; unsafe or unusual boundaries can still prompt.	You trust the task but want safety checks retained.
Full access	After confirmation, wcagent can use the filesystem, terminal, internet, and local browser for the current task and workspace root. OS controls and core safety checks still apply.	You understand the request and want minimal interruption.

Worktree isolation

The default isolation mode is Worktree. wcagent performs the task in a separate Git worktree, so your open repository is unchanged until you review the result and select Apply changes.

For a non-Git folder, or if you deliberately select Direct isolation, edits affect the open workspace as the task runs. wcagent warns you before starting in direct mode.

Workspace trust still applies

In an untrusted VS Code workspace, wcagent remains read-only unless you trust the workspace or explicitly confirm Full access for the task. Trust or elevate a workspace only when you know and accept the code it contains.

While wcagent works

The conversation shows progress updates and collapsible activity for reads, edits, commands, browser checks, approvals, and delegated work. An elapsed-time indicator continues while the task is active.

Approve or reject a requested action from its approval card.
Send a follow-up to queue another instruction, or steer the active task when the new direction should affect the current work.
Stop the task when you do not want it to continue. Completed local actions are not silently reversed.
Close or reload VS Code if necessary. wcagent restores the active task from its retained event history when you return.

Review and apply the result

Read the final summary and the validation results. A failed or skipped check should be treated as unresolved until you inspect it.
Open the edited-files card to see additions and deletions, then preview each changed file. You can also run wcagent: Review wcagent Changes.
In Worktree mode, select Apply changes only after you accept the diff. wcagent stops if the same lines changed in your open repository and cannot be applied safely.
If needed, use Undo applied changes. Undo also checks for later overlapping changes instead of overwriting them.

In Direct mode, the files are already changed in your open workspace; use your normal Git workflow to review, keep, or revert them.

Manage conversations

Open the wcagent home view to return to an existing conversation with its context, or choose New Chat for a clean thread. Starting a new chat does not cancel a task that is already running.

You can delete completed, failed, or cancelled conversations. Deleting a conversation removes its retained history; it does not delete workspace files, undo applied changes, or remove generated images. Images created by a task are saved under wcagent-generated-images/<turn-id>/.

Use wcagent in VS Code Chat

In the native VS Code Chat view, mention @wcagent and use /fix, /explain, /review, or /tests.

Command Palette reference

Open the Command Palette with Ctrl + Shift + P on Windows/Linux or ⇧⌘P on macOS, then search for wcagent.

Command	Purpose
wcagent: Open wcagent	Open the main wcagent view.
wcagent: New wcagent Chat	Start a new conversation.
wcagent: Add Selection to wcagent Chat	Add the active editor selection to the composer.
wcagent: Add File to wcagent Chat	Add the active file to the composer.
wcagent: Ask wcagent	Open wcagent with the current editor context.
wcagent: Explain Selection or File	Ask for an explanation of the current selection or file.
wcagent: Review File	Request a focused code review.
wcagent: Generate Tests	Request tests for the current code.
wcagent: Review wcagent Changes	Open the current task diff.
wcagent: Connect Account	Start the wcagent device sign-in flow.
wcagent: Open Browser Connector Folder	Reveal the managed connector folder to load in Chromium.
wcagent: Pair Browser Model Connector	Create and copy a one-time browser pairing value.
wcagent: Unpair Browser Model Connector	Disconnect a paired browser connector.
wcagent: Manage Plugins	Install, update, enable, disable, or remove wcagent plugins.
wcagent: Install Plugin from Git Repository	Install a plugin from a GitHub or GitLab repository.
wcagent: Browse Signed Plugin Registries	Browse plugins from configured verified catalogs.
wcagent: Manage MCP Servers	Open the MCP server settings.
wcagent: Sign Out	Remove this device’s wcagent session.

Settings

Open the wcagent account menu and choose wcagent settings. The settings view contains General, Configuration, Personalization, Usage & billing, Browser connectors, Privacy, and Account sections.

VS Code setting	What it controls
`webcodestudio.tasks.isolation`	Uses a separate Git worktree by default, or direct edits when configured.
`webcodestudio.context.maxFiles`	Maximum number of ranked files considered for automatic context. Default: 80.
`webcodestudio.context.confirmBeforeSend`	Shows the context review step before each task. Default: off.
`webcodestudio.browser.executablePath`	Overrides the Chromium executable used for local browser validation. Default: automatic detection.

Troubleshooting

The Send button is unavailable

Confirm that you are signed in, your trial or plan is active, a model is selected, and its connector shows as connected when using a browser model.

The browser model is offline

Open wcagent settings → Browser connectors. Confirm the provider is signed in within the same browser profile, Developer mode is still enabled, and the connector is enabled. After an update, wait about a minute or reload the connector from the browser extensions page. Only use repair or re-pair when wcagent asks for it or the connection remains unavailable.

Edits or commands are blocked

Check VS Code Workspace Trust and the task’s access mode. In an untrusted workspace, mutations and commands require workspace trust or an explicitly confirmed Full access grant.

Browser validation cannot start

Install Chrome, Brave, or Edge, or set webcodestudio.browser.executablePath to a compatible executable.

The extension looks out of date after installing

Open Extensions, select wcagent, and check for an update. Then run Developer: Reload Window. If the problem remains, uninstall and reinstall wcagent from the Marketplace.

You need diagnostic details

Open View → Output and select wcagent. Review the logs before sharing them, especially if your task handled private repository data.

Privacy and provider limits

wcagent sends the service and your selected model only the context needed for the task, such as ranked path metadata, selected editor text, requested file contents, diagnostics, diffs, command output, approvals, and completion evidence. Absolute workspace paths are excluded.

For browser models, the connector returns model text and bounded runtime metadata. It does not send provider cookies, passwords, or authentication headers to wcagent. Conversations may remain in the selected provider’s history.

wcagent does not increase or bypass provider usage limits, authentication, CAPTCHAs, safety systems, or geographic restrictions. Use only connection methods permitted for your account. Read the complete Privacy Policy, Terms of Use, and security overview.