Your first task
Add a project, start a task, choose where it runs, and follow the agent while it works.
Add a project
A project in Machine Code is a folder on your computer, usually a git repository.
- In the sidebar, click Add project (or press Ctrl+O, ⌘O on Mac).
- 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 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.
Pick a model
The model button lists every model you can use. See Models and engines.
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:
| 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. |
| An SSH host | Runs on a remote computer 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.
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.
- 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.
When the agent wants to do something that needs your OK, a card appears in the chat. Approve or decline it there.
To decide ahead of time what agents
may do on their own, see 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.
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.
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.