Quickstart

The desktop app runs on macOS, Windows, and Linux. Code opens a session tied to a project folder and execution environment, with file and command tools available to the agent. Chat opens a conversation with a model. Each Code session keeps its own conversation history, so you can return to the investigation and tool results later.

Before you start

Install the desktop app and connect your account. Choose a project whose dependencies and test tools are already installed. Start with a local project for this walkthrough.

This walkthrough begins with a read-only question, then follows a quantity bug through a regression test, a fix, and Git review. Use the runnable sample below or adapt the files and test command to your repository. The agent’s wording and sequence of tool calls may differ; verify its actual results.

Prepare a small example

Use your own repository, or create an empty checkout-example folder and save these three files in it. The sample uses Node.js’s built-in test runner and needs no third-party packages. Its calculation deliberately ignores quantity so you can follow a real failure through to a fix.

Example project files

{
  "name": "checkout-example",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node --test"
  }
}

export function calculateTotal(items) {
  return items.reduce((total, item) => total + item.price, 0);
}

import test from 'node:test';
import assert from 'node:assert/strict';
import { calculateTotal } from './checkout.js';

test('one unit costs 12', () => {
  assert.equal(calculateTotal([{ price: 12, quantity: 1 }]), 12);
});

In a terminal opened in that folder, run:

Bash

npm test

The initial test should pass because it only covers one unit. Create a README.md containing “This example calculates checkout totals. Run npm test to run its tests.” The first request below uses that README. For the Git review step, initialize the folder as a repository and commit the starting files, or use an existing repository where you can inspect the diff. This minimal sample has no web page. Browser verification later in the guides applies to your own running web project.

Choose a project and model

A Code session needs a project folder, model, and permission mode. The folder determines which project the agent works on, the gateway supplies the available models, and the permission mode determines how tool approval requests are handled.

Open a new Code session and choose your project folder. For a Git repository, select the branch or create a separate worktree for the task.
Choose a model from the picker. The available models come from your configured gateway.
Choose a permission mode. Use Always ask for a first task if you want to review requests to change files or run commands.
Describe the task and send the message. Include the expected result and how to verify it.

The folder, branch, and worktree controls are beside the composer. Choose the workspace before the first message; an existing session retains its execution destination.

Choose the project folder and execution environment before starting a session.

Ask about the project

Start with a question whose answer you can check against the project:

Read @README.md and identify how to run this project and its tests. Do not change files.

Select README.md from the @ suggestions so the file is included in the request. Expand the file-read card in the response and compare the answer with the README. In the sample above, the answer should identify npm test and describe the checkout calculation. It should not claim to have run tests unless the timeline contains that command result.

Reproduce and fix a bug

Next, give the agent a reproducible problem and an expected result:

Checkout totals ignore item quantities. Add a regression test in checkout.test.js for three units at $12 each: the expected total is $36. Run npm test to reproduce the failure, fix checkout.js, and run the tests again.

The first test run should show the incorrect total of 12; after the fix, the same assertion should pass with 36. Review the actual test output before accepting the agent’s summary.

Check the result

The timeline records the agent’s responses and tool activity as the task runs. Each tool card shows the action and its result: a file read, a command, or a response from a connected service. For the checkout example, inspect the failing test output first, then compare it with the result after the calculation changes. Click a tool card to expand the command and its output. When the app requests approval, inspect the proposed action before approving or denying it. Answer the agent’s questions in the session, and send further instructions if the task needs to change direction.

The example session reports the reproduced failure, the quantity fix, and two passing tests.

Review before committing

Open Session changes and check both checkout.js and checkout.test.js. Confirm that the calculation multiplies price by quantity and that the regression test covers three units. Expand the test result to verify that both tests passed, then review and commit the changes. For a web project, you can also check the running page in the browser.

Get started

Features

Tools and customization

Other interfaces

Support

Before you start

Prepare a small example

Choose a project and model

Ask about the project

Reproduce and fix a bug

Check the result

Review before committing

​Before you start

​Prepare a small example

​Choose a project and model

​Ask about the project

​Reproduce and fix a bug

​Check the result

​Review before committing

Before you start

Prepare a small example

Choose a project and model

Ask about the project

Reproduce and fix a bug

Check the result

Review before committing