# Your first task

Add a project, start a task, choose where it runs, and follow the agent while it works.

Canonical page: https://themachine.myapps.ai/docs/code/first-task

## Add a project

A project in Machine Code is a folder on your computer, usually a git
repository.

1. In the sidebar, click **Add project** (or press **Ctrl+O**, **⌘O** on Mac).
2. Pick how to add it:
   - **Search for directory**: type part of the folder's name and pick it.
   - **Browse**: choose the folder in your computer's file browser.
   - **Clone from GitHub**: pick a repository from your GitHub account, or
     paste its address, and choose where to put it.
   - **New directory**: create an empty folder.

![The Add project menu with Search for directory, Clone from GitHub, and New directory](/images/docs/code/add-project.webp)

The project appears in the sidebar. Add as many as you like.

## Start a task

Click **New task** in the sidebar (or press **Ctrl+N**, **⌘N** on Mac).

### Describe the change

Write what you want, the way you'd brief a teammate. Name files, commands,
and what "done" looks like.

> The signup form accepts emails without a dot after the @. Add proper
> validation, show the error under the field, and add a test for it.

![The message box with a request typed in, the model button, and the agent mode](/images/docs/code/composer.webp)
### Pick a model

The model button lists every model you can use. See [Models and
engines](/docs/code/models).
### Choose where it runs

Open **Run on**, the button next to the project name above the message box.
It shows where the task will run, **Local** at first. Pick one:

![The Run on menu with Local, Worktree, and Machine Cloud](/images/docs/code/run-on.webp)

| Option | What it means |
|---|---|
| **Local** | *This checkout.* The agent works directly in the folder you added. |
| **Worktree** | *A new git worktree.* The agent gets its own copy of the repository on a new branch, so your checkout stays untouched and several agents can work at once. |
| **Machine Cloud** | *New cloud session in your Machine project.* The task runs in a Machine Cloud sandbox and opens there. See [Machine Cloud](/docs/code/machine-cloud). |
| *An SSH host* | Runs on [a remote computer](/docs/code/remote-computers) you added, in this project's checkout there. |

Machine Code remembers your choice for each project. **Worktree** only shows
when the folder is a git repository; **Machine Cloud** only shows when your
project can use it.
### Send

Press **Enter**. The agent starts, and the task appears in the sidebar under
its project.

> **Use a worktree for anything bigger than a quick fix**
> A worktree keeps the agent's changes on their own branch until you decide
> what to do with them. It's the easiest way to run two or three tasks at once.

## Follow along

While the agent works, the chat shows its replies, the commands it runs, and
the files it changes. If it made a plan, a **Plan** card shows how many steps
are done.

![An agent partway through a task: a preview of the page it edited, the files it changed, and its plan at 4 of 5 steps](/images/docs/code/agent-working.webp)

Next to the chat:

- **Changes** (**Ctrl+Shift+G**) shows the diff of everything the agent
  changed.
- **Files** (**Ctrl+Shift+E**) shows the project's files. Click one to open
  it in the [code editor](/docs/code/code-editor).
- **Chat details** (**Ctrl+Alt+B**) shows the environment, how much of the
  model's context is used, connectors, files changed, and background tasks.

To stop the agent, press **Escape**. To add more instructions, type in the
message box. You can send while it's working.

## Agent modes

Click the mode button in the message box, or press **Shift+Tab** there to
cycle through the agent's modes. Which modes there are depends on the engine
running the agent, for example **Always ask**, **Accept file edits**, **Plan
mode**, and **Full access**.

![The agent mode menu: Always ask, Accept file edits, Plan mode, and Full access](/images/docs/code/agent-modes.webp)

When the agent wants to do something that needs your OK, a card appears in
the chat. Approve or decline it there.

![A Needs your approval card asking to run npm run deploy, with Allow once, Always allow, and Deny](/images/docs/code/approval-card.webp)
 To decide ahead of time what agents
may do on their own, see [Approval rules](/docs/code/approval-rules).

## Tabs, terminals, and more

A task's window has tabs. Press **Ctrl+T** for a new tab, **Ctrl+Shift+A**
for another agent, **Ctrl+Shift+T** for a terminal, or **Ctrl+Shift+B** for
the [built-in browser](/docs/code/browser).

When an agent starts a dev server or a watcher, it runs it in a Machine Code
terminal you can see, so it keeps running after the agent's turn ends.

## When it's done

Read the changes, then commit and open a pull request. See [Review and
ship](/docs/code/review-and-ship).

To tidy up, archive the task from the sidebar (**Ctrl+Shift+Backspace**
archives the current one). Closing a chat's tab doesn't archive it: it stays
in the sidebar, and clicking it brings the tab back.