What is the Codus Brain, and what can it do?

The Codus Brain is a general AI assistant built into codus that works across all your projects at once, not just the one you are looking at. It lives in a drawer along the right edge of the window and opens on its own every time codus starts; you open and close it with the brain icon in the title bar. Inside the drawer is a Claude Code terminal you type into (you answer with the arrow keys and Enter, not clicks), and it can see every project, plan, note, task and git history you keep in codus. So you can ask it to find a project, check what an agent is doing, draft a plan, read a project's git status, or hand a job to the agent working in any single project.

What the Brain is

The Brain is a drawer that opens along the right edge of the codus window. Inside it is a Claude Code terminal, the same kind of AI terminal that works inside your individual projects. The difference is reach: a project's own agent sees only that one project, while the Brain can see all of them at once, along with their plans, notes, tasks and git history.

Everything the Brain does runs on the copy of Claude Code installed on your own Mac. There is no separate cloud or hosted version. If Claude Code is not installed, the drawer cannot start a Brain (see Before you start below).

The drawer can hold more than one Brain at a time, shown as tabs along the top. Each tab is its own separate session. Adding, renaming and closing those tabs has its own page (manage the brain drawer).

Because it is a terminal, you talk to it by typing, and you answer its questions with the arrow keys and Enter. Clicking a choice inside the terminal text does nothing, which catches out almost everyone the first time. For the full typing-and-answering mechanics, see talk to the brain. (codus runs on macOS only today.)

How the Brain is different from a project agent

Every project in codus (codus calls each one a quadrant, and labels them Q1, Q2, and so on) has its own agent that works only inside that project. The Brain sits above all of them. It is a general assistant for your whole codus setup, not tied to any single project. Ask a project's agent to fix a bug in that project; ask the Brain to find which project had the bug, compare two projects, or pass a job from one to another.

The Brain does not change when you move between the different codus views such as SEO, Video or Support. It is one continuous session and stays the same whichever view is on screen.

Before you start

The Brain runs on Claude Code installed on your Mac. If you do not have it, the drawer shows a short message and a Get Claude Code button instead of a terminal. The message reads "Claude Code isn't installed on this machine" and "codus Brain runs on your local Claude Code. Install it, then reopen this drawer." Install Claude Code first, then reopen the drawer. The full install steps are on their own page (claude code required).

How to open and close the Brain

1. The Brain opens on its own every time codus starts, so you will usually find it already open on the right.
2. To close it, click the small × at the top of the drawer, or click the brain icon in the title bar (the strip across the very top of the window). That icon has the accessible name "Codus Brain", and its tooltip reads "Codus Brain — ask anything".
3. To open it again, click the same brain icon. It stays highlighted while the drawer is open.

Closing the drawer does not stop the Brain. The session keeps running out of sight, and when you reopen the drawer you see everything it did while it was hidden.

There is no keyboard shortcut for the Brain. Use the brain icon.

How do I know it worked? When the Brain is open you see the drawer down the right side with a terminal in it, and the brain icon in the title bar is highlighted. Once Claude Code has started, you can type into the terminal.

Note: because the Brain always opens at launch, it will reappear every time you start codus, even if you closed it last time. That is expected. codus does not remember it as closed.

The number badge on the brain icon

The agents inside your projects can send the Brain messages. When they do, a small number appears on the brain icon in the title bar showing how many are waiting. If there are more than nine, it shows "9+". The count updates on its own and clears as the Brain reads the messages. The delegate to quadrant agents page explains this back-and-forth.

What the Brain can do

For a built-in tour, click the info button (a small ⓘ) at the top of the drawer. Its tooltip reads "What can Brain do?", and it opens a panel headed "What can Brain do?". The panel opens with this line:

Brain can act as a general assistant to all your projects and workflows in Codus. It spans every quadrant, plan, note, task, and git history. Some things to try:

Below it are seven groups of example requests:

• Discover projects: find a project anywhere in your setup. Examples: "List my projects" and "Find the project I was working on yesterday".
• Inspect quadrants: see what each project is doing right now. Examples: "List my codus quadrants", "What's running in Q3?", and "Show me Q1's last action".
• Plans: list, open, or draft a plan. Examples: "List the plans for Q2's project", "Open plan {plan_id}" (you swap {plan_id} for a real plan's id), and "Help me draft a plan for Q4's current branch". When you ask for a new plan, the Brain hands the drafting to that project's own agent, so the plan is anchored to the right project folder.
• Git: check a project's version history without opening it. Examples: "What's the git status of Q1?", "Show me the last 10 commits on Q3's branch", and "Diff the staged changes in Q2".
• Browser: look at a project's live preview. Examples: "Take a screenshot of Q3's preview", "Read Q1's preview console", and "What URL is loaded in Q2?". The Brain can also open or close a project's preview partway through a conversation.
• Multi-quadrant orchestration: the most advanced group, for setting up and wiring together the pieces several projects need at once. Examples: "Set up a new worktree for a feature branch", "Clone the DB for Q5's worktree", and "Reserve a port for Q3 and valet-link it".
• Talk to a quadrant agent: hand a job to the agent inside one project. Examples: "Tell Q4 to rebuild the dashboard" and "Ask Q1's agent to run the test suite and log_action the result".

The rule the panel ends on: the Brain does the cross-project work itself (finding projects, reading files, checking git), and passes anything that depends on a single project's own setup (its build command, its environment variables, its framework quirks) to that project's agent.

These examples are there to read, not to click. They are plain text, not buttons, so clicking one does nothing. Read the one you want, close the panel, then type your own version into the Brain terminal.

Close the panel with its × (tooltip "Close (Esc)"), the Esc key, or by clicking the dark area behind it.

One thing you will notice: while the help panel is open, the drawer's Live View browser disappears. That is expected, and it comes back on its own when you close the panel. The Live View has its own page (live view browser).

Common problems

"I clicked an example in the help panel and nothing happened." The examples are there to read and type yourself. They are not buttons. Close the panel and type your own version into the terminal.

"The drawer opens every time I start codus, even though I closed it." That is by design. The Brain always opens at launch. Close it whenever you like with the × or the brain icon; it will not be remembered as closed.

"The Brain is only showing a button that says Get Claude Code." The Brain needs Claude Code installed on your Mac. The message reads "Claude Code isn't installed on this machine" and "codus Brain runs on your local Claude Code. Install it, then reopen this drawer." Install it, then reopen the drawer (claude code required).

"Is there a shortcut key to open the Brain?" No. Use the brain icon in the title bar.

"Does the Brain change when I switch to the SEO, Video or Support view?" No. It is one session and does not change with the view on screen.

"The Live View went blank when I opened the help panel." That is expected. It reappears when you close the panel.