How do I start working on a project?
Two steps. Pin a folder to one of the panes, then start an agent on it. Click 📁 pin a worktree in an empty pane, choose your project folder, then use the start button and 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
Claude Code must be installed and signed in, otherwise the agent cannot start. See What do I need before I can use codus?.
Step 1: Pin your project folder
- In an empty pane, click 📁 pin a worktree. Despite the name, this is just "choose a folder".
- Pick the folder your project lives in. Any folder works. It does not have to be set up in any particular way.
- The folder's name now appears in that pane's header, and more controls appear beside it.
Two things worth knowing:
- codus adds a short section to a file called CLAUDE.md in that folder, so the agent knows how to work with codus. If you track your project's changes, you will see that file has been 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
- Click start in that pane's header.
- The menu offers two groups, Claude and OpenAI Codex, depending on which you use.
- 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.
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.
If you want two agents on the same project, that is refused, because one folder can only be pinned once. Ask your agent about setting up a git worktree, which gives you a second folder for the same project.