Projects
Add projects, switch between them in one window, and give each its own sandbox, approvals and model.
A project is a folder KodaCode works in. One window holds all your projects. Switching doesn't pause anything, so a session or goal in one project keeps working while you're in another.
Add a project
Open the project switcher (⇧⌘O) and choose Add project:
| Field | What it does |
|---|---|
| Folder | Choose the folder KodaCode works in. |
| Name | The name in the project menu. |
| Initialize a git repository | Runs git init in this folder when you save. |
| Where memory is kept | A file in the project, committed with the repository (.koda/memory.json), or Kept in .koda/memory, ignored by git. |
| Where this project runs | On this computer, Docker or Podman. |
| Base image for this project's container | The image a container starts from. |
You can also open a saved project from the same screen. The switcher lists your projects. It has Search projects, Rename project and Project settings. Badges show Sessions waiting for you and Sessions working. Recent projects keeps the last five.
Per-project settings: the Runs on chip
The chip beside the prompt box sets Where this project runs, "Where this project's commands run, and whether its edits wait for you":
| Setting | Options |
|---|---|
| Sandbox | Host, Docker or Podman, and its Base image |
| Changes in project | Default, Ask before each, Apply directly |
| Outside the project | Default, Ask first, Allow, Deny |
| Review every turn | Run a full review after each turn that changes files |
| Parallel autonomous tasks | How many autonomous tasks in this project run at the same time. More wait for a free slot. Your own sessions don't count. |
A project's own choice wins over the defaults in Preferences → Permissions & sandbox. A folder that isn't a saved project uses the defaults. To change them, add the folder from the project menu.
Per-project model
Each project remembers the model you last chose for it, so different projects can run different providers and models at the same time. The model picker in the top bar shows whether the choice is the project's own.
Project instructions
KodaCode reads AGENTS.override.md at the project root. If that file doesn't exist, it reads AGENTS.md. The agent gets that file together with your own ~/.config/kc/AGENTS.md. KodaCode strips HTML comments and caps each file at 32 KiB.