How do I start working on a project?

Two steps. Assign a project folder to one of the panes, then boot it. The Assign a project guide in every empty pane walks you through both. Choose your project folder, then pick boot project. The agent reads your project, starts anything it needs to run, and waits for you to tell it what to do.

Before you start

Your selected supported coding provider must be installed and configured, otherwise the agent cannot start. See What do I need before I can use codus?.

Step 1: Choose your project folder

1. In an empty pane's Assign a project guide, click Choose a project folder.
2. Pick the folder your project lives in. Any folder works. It does not have to be set up in any particular way.
3. The folder's name now appears in that pane's header, and more controls appear beside it.

Two things worth knowing:

• codus adds managed instructions for both providers, using CLAUDE.md for Claude Code and AGENTS.md for Codex. If you track your project's changes, you may see those files edited. That is expected.
• A folder can only be pinned to one pane at a time. Trying to pin the same folder twice is refused, with a message telling you which pane already has it.

Step 2: Start the agent

1. Click start in that pane's header.
2. Select the installed provider you intend to use. Available providers and their model controls are described in provider selection.
3. Under your choice, pick boot project, which is marked as recommended.

boot project tells the agent to look over your project and bring up anything that needs to be running, such as your development server, before it waits for you. The alternative, start unbooted, just opens the agent and waits.

You will see an unusual-looking line appear in the text panel as it starts. That is codus giving the agent its opening instruction. It is not an error.

The permission screens on the first boot

Both providers can show several one-time trust screens before the normal agent prompt appears. Codus normally confirms its own managed setup automatically. If a screen remains, check that the folder name is the project you pinned before accepting it.

For Claude Code:

1. Choose Yes, I trust this folder.
2. Keep every Codus MCP server checked and confirm the list.
3. On the Bypass Permissions warning, choose Yes, I accept.

For OpenAI Codex:

1. Choose Yes, continue for the pinned project folder.
2. On the project hooks screen, choose Trust all and continue for the Codus-managed hooks.

Seeing more than one screen is normal on the first start. Never accept a folder you do not recognise.

Step 3: Tell it what you want

The large text panel filling the pane is where you and the agent talk. Type what you want in plain English at the bottom and press return.

You do not need to phrase it in any special way, and you do not need to know what any of your files are called. Asking it to explain your project back to you is a reasonable first thing to try.

When the agent asks you a question back, you answer with the arrow keys and return, not the mouse. See How do I answer the agent when it asks me something?, which is the one thing that catches everyone out at the start.

How do I know it worked?

The pane's text panel fills with the agent's replies, and the folder name sits in the header. When the agent finishes something, a line appears in the done panel describing what it did.

The coloured dot on the tab tells you what is happening without you having to watch: amber while it is working, green when it has finished, and a pulsing red when it has stopped and needs an answer from you.

Doing this four times

Repeat in the other panes with other folders. Each pane is independent: its own project, its own agent, its own conversation. That is the point of codus, and it is why four agents can be working while you are only looking at one.

For more agents in the same project, use Terminals → + to add a Builder or Reviewer alongside the Lead Agent; see extra project agents. Pinning the same folder to another quadrant is a different operation and is refused. A separate Git worktree is an option when you want an isolated copy of the project.