> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mka1.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Read a project, reproduce a checkout bug, verify the fix, and prepare to review the changed files.

export const ScreenshotCrop = ({src, alt, width, height, x = 0, y = 0, cropWidth = width, cropHeight = height, maxWidth = "100%"}) => <div className="not-prose" style={{
  position: "relative",
  overflow: "hidden",
  width: "100%",
  maxWidth,
  margin: "0 auto",
  aspectRatio: `${cropWidth} / ${cropHeight}`
}}>
    <img src={src} alt={alt} width={width} height={height} style={{
  position: "absolute",
  display: "block",
  margin: 0,
  maxWidth: "none",
  width: `${width / cropWidth * 100}%`,
  height: "auto",
  left: `${-x / cropWidth * 100}%`,
  top: `${-y / cropHeight * 100}%`
}} />
  </div>;

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](/docs/mka1-code/install). Choose a project whose dependencies and test tools are already installed. Start with a local project for this walkthrough.

<Note>
  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.
</Note>

## 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.

<Accordion title="Example project files">
  <CodeGroup>
    ```json package.json theme={null}
    {
      "name": "checkout-example",
      "private": true,
      "type": "module",
      "scripts": {
        "test": "node --test"
      }
    }
    ```

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

    ```js checkout.test.js theme={null}
    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);
    });
    ```
  </CodeGroup>
</Accordion>

In a terminal opened in that folder, run:

```bash Bash theme={null}
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.

1. Open a new **Code** session and choose your project folder. For a Git repository, select the branch or [create a separate worktree](/docs/mka1-code/workspaces) for the task.
2. Choose a model from the picker. The available models come from your configured gateway.
3. Choose a permission mode. Use **Always ask** for a first task if you want to review requests to change files or run commands.
4. 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.

<Frame caption="Choose the project folder and execution environment before starting a session.">
  <ScreenshotCrop src="/images/mka1-code/desktop-project.jpg" alt="Project selector showing the checkout demo folder and local or remote execution choices" width={2720} height={1660} x={975} y={500} cropWidth={685} cropHeight={415} maxWidth={520} />
</Frame>

## 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.

<Frame caption="The example session reports the reproduced failure, the quantity fix, and two passing tests.">
  <ScreenshotCrop src="/images/mka1-code/guides/quickstart.jpg" alt="Checkout quantity prompt and completed regression-test summary" width={2720} height={1660} x={1000} y={120} cropWidth={1160} cropHeight={550} maxWidth="100%" />
</Frame>

## 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](/docs/mka1-code/review-changes). For a web project, you can also [check the running page in the browser](/docs/mka1-code/previews).