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

# Sessions and project context

> Add files, guide a running task, find earlier work, and understand context usage in the desktop app.

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>;

A desktop Code session keeps the conversation, tool results, and selected workspace together. Use it to investigate a problem, guide an active task, and return to the work later. Start with the [quickstart](/docs/mka1-code/first-task) if you have not run a session yet.

## Start and organize a session

Open **Code → New session**, choose a folder, and check the branch, model, and permission mode before sending the first message. The first message attaches the workspace to the session. To work in a different execution environment, start another session and choose its destination first.

Give each session a specific purpose, such as investigating a failing checkout test or reviewing an API change. Use the session's sidebar menu to rename it, pin work you return to frequently, or archive completed work. Archived sessions remain available in **Archived**. Deleting a local session removes its saved history from this computer; read the confirmation before continuing.

A new conversation does not create a new copy of the repository. If two tasks need to edit the same project independently, use [separate worktrees](/docs/mka1-code/workspaces).

## Add project context

Mention relevant file paths with `@`, or attach the failing test output so the agent has the error to investigate. The composer accepts file selection, drag-and-drop, and pasted attachments, including specifications and screenshots. Image input requires a model that supports it.

### Give the agent a checkable request

Include the observed behavior, expected behavior, and a way to verify the result. File names and error output help the agent begin with the relevant code instead of guessing where to look:

> The checkout returns 12 for three items priced at 12 each. Read @checkout.js and @checkout.test.js. Add a failing test for a total of 36, fix the calculation, and run npm test. Keep the public function signature unchanged.

Select the intended item from the `@` suggestions before sending. Attach a design or screenshot when the task depends on appearance; explain which part matters. Some document formats require a matching skill, and the app warns you when that skill is inactive.

For a screenshot, open **Mark up the image** on its thumbnail to point out the relevant control or region. Review the edited image, then choose **Apply**. The marked image replaces the attachment for that message.

## Follow a running task

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.

Sending a message during a run follows **Settings → Composer → A message typed during a run**. **Queue** holds the message until the run finishes. **Interrupt** delivers it at the next model turn, so it can change the agent's next step. To stop the active turn, choose **Cancel run**.

### Queue, redirect, or stop

Use **Queue** for a follow-up that depends on the current result, such as asking for a summary after the tests finish. Use **Interrupt** when the next action should change, such as correcting a file name or narrowing the scope. An interrupt is delivered at the next model turn; inspect the timeline to see what has already run.

Canceling a run stops the active turn. Check **Session changes** afterward to see which edits remain, then decide whether to continue from those files or revise them. Canceling is not a Git rollback.

## Return to earlier work

To return to earlier work, use **Search sessions** to find a session by name or transcript text. Select it to reopen the conversation and continue with its saved workspace. Use **Search this session** to find a result within a long transcript.

### Revisit a decision

Pin a useful message and open **Pinned** to find it later. Where **Branch from here** is available, use it to explore another approach in a separate conversation. This branches the discussion; use a Git branch or worktree separately if the files also need to be isolated.

**Restart from this message** and **Edit and restart from here** replace the later conversation. The confirmation may also offer to restore files changed since that point. Review the listed files and choose deliberately: keeping a transcript, replacing later messages, and restoring repository files are different operations.

<Frame caption="Search finds previous sessions so you can return to their conversation and results.">
  <ScreenshotCrop src="/images/mka1-code/guides/sessions.jpg" alt="Session search results for the checkout example" width={2720} height={1660} x={875} y={616} cropWidth={970} cropHeight={395} maxWidth="100%" />
</Frame>

## Understand context usage

The context indicator measures how much of the model's context window is in use. When **Compact session** is available, it summarizes earlier history to free space for further work; the earlier transcript remains in the session. Open the indicator to inspect its details. Gateway request and token totals are reported separately in [Usage](/docs/mka1-code/troubleshooting).

## Use chat alongside coding

Switch to **Chat** for conversations with a selected model, such as discussing an approach or asking for an explanation. Use **Code** when you want the agent to work in a selected project with file and command tools. In Chat, responses stream into the conversation and history is stored locally. You can rename conversations, stop a response, or regenerate the latest reply.

Both Chat and Code support dictation. Record your request with the microphone beside the composer, then review the transcribed text before sending it.

Continue with [Planning and permissions](/docs/mka1-code/permissions).