TOOLS & SKILLS
Run Claude Agents Side By Side 🛠️
Claude Code can run sessions next to each other now. This is the actual setup. The real shortcuts, how many agents to run before it stops helping, why they.
You could always run more than one agent. The problem was you could not see any of them.
Here is what it used to look like. You start one agent in a window. You open a second window and start another. Then a third. Then you spend the next twenty minutes clicking between windows trying to remember which one you asked to fix the login bug and which one was writing tests. Half the time one of them finished ten minutes ago and has been sitting there waiting on you, and you had no idea.
The Claude Code desktop app fixed the seeing part. Your sessions now live in a sidebar on the left. You can pull two of them into the main window at once and watch both of them work. You can tell at a glance which ones are running and which ones are done and waiting on you.
This guide is the setup, not the announcement. The exact keys, the number I actually run, the reason they cannot break each other, and the specific task pairs that are worth doing at the same time. Nothing in here needs you to be a developer.
How To Actually Set It Up
This takes about two minutes. Do it once and it sticks.
Press Cmd+N on a Mac or Ctrl+N on Windows. You can also click New session at the top of the sidebar. Every session you start shows up in that sidebar on the left. Each one is its own conversation with its own memory. They do not share anything, which is the point.
This is the one people miss. Hold Cmd on a Mac, or Ctrl on Windows, and click a session in the sidebar. It opens in a second pane right next to the one you already had open. A normal click swaps sessions. The held key is what splits the screen.
One thing to know so it does not surprise you: once the split is open, clicking a different session in the sidebar replaces whichever pane you were last clicked into. It does not add a third. So click into the pane you want to swap before you pick the new session.
Drag a pane by its header to move it. You can sit them side by side or stack one on top of the other. Drag the edge between two panes to make one bigger.
What I do: side by side when I am actually reading both. Stacked when one of them is a long job I only want to glance at, because a short stacked pane still shows me the last few lines and whether it is done.
Press Cmd+\ on a Mac or Ctrl+\ on Windows. That closes whichever pane you are focused on and drops you back to one session filling the window. Learn this key. You will use it more than the split key, because the fastest way to think clearly is to close things.
Ctrl+Tab moves forward through your sessions in the sidebar and Ctrl+Shift+Tab moves back. Same on both Mac and Windows. This is how you do a quick lap to check on everything without hunting in the sidebar.
This is the step that makes the whole thing readable, and almost nobody does it. At the top of the sidebar there are controls to filter by status, project, and environment, and to group by project. Turn grouping on. Now your sessions sit under headings, and you can see at a glance that three of them are on your website and one is on something else.
Then rename them. Click the session title in the toolbar at the top of the open session and type what it is doing. Not "session 2". Write "checkout bug" or "rewrite the welcome email". Six weeks in, this is the difference between a sidebar you can read and a list of identical rows.
The shortcuts, in one place:
| What you want | Mac | Windows |
|---|---|---|
| New session | Cmd+N | Ctrl+N |
| Open a session in a second pane | Hold Cmd, click it in the sidebar | Hold Ctrl, click it in the sidebar |
| Close the pane you are in | Cmd+\ | Ctrl+\ |
| Flip through your sessions | Ctrl+Tab and Ctrl+Shift+Tab | Ctrl+Tab and Ctrl+Shift+Tab |
| Ask a side question without adding it to the chat | Cmd+; | Ctrl+; |
| Open a terminal inside the session | Ctrl+` | Ctrl+` |
How Many Should You Run
This is the honest part, and it is the part the screenshots lie about.
The internet loves posting ten agents running at once. It looks incredible. It is not a way to work. Nobody is reading ten sets of output. They took the screenshot and then they closed eight of them.
My ceiling is four. Past four I stop being the person running the work and start being the person trying to remember what the work was. I open a pane and have to read back through it to figure out what I asked for. That is the moment I have gone too far, and it happens for me at five.
Here is why it breaks down so fast. Every agent you add is not just another agent. It is another set of changes you have to read, another thing you have to check, another decision waiting on you. The agents got faster this year. You did not.
How to find your own number: run two for a week. Just two. Then try three. Watch for the moment you have to re-read a pane to remember what you asked. That number is your limit. Work one below it. For most people starting out that is two, and two is genuinely great.
And keep the point in front of you. The win is not launching the most agents. It is finishing three real tasks in the time one used to take. Two agents that both finish something beat six that all need you to come untangle them.
Why They Do Not Collide
This is the part that makes running several agents safe instead of scary, so it is worth understanding even if you never touch the settings.
Normally your project is one folder of files. If two agents both work in that one folder at the same time, they write over each other. One saves a file, the other saves the same file two seconds later, and the first one's work is gone. You do not get a warning. You find out later when something you know you fixed is broken again.
The desktop app gives every session its own copy of your project. You do not make the copy. It happens by itself the moment you start the session. Session one gets its own copy. Session two gets its own copy. They are editing different files sitting in different places on your computer, so they simply cannot touch each other's work. Nothing comes back together until you decide to bring it back together.
The name for this is a git worktree. You do not need to know how it works under the hood. You need to know what it means: each session has its own files and its own branch, and no agent can undo another agent's work.
The four practical things to know about those copies:
- They live inside your project, in a folder called .claude/worktrees/. You can move them somewhere else in Settings, under Claude Code, in the "Worktree location" setting. There is also a setting for a branch prefix, which is handy if you want every Claude branch labeled so it is easy to spot.
- Add that folder to your .gitignore. Put .claude/worktrees/ in there. Otherwise those copies show up as a pile of new untracked files in your main project and it gets confusing fast.
- A fresh copy does not include your hidden setup files. Things like your .env file are skipped, which means the project may not run inside a new session. The fix is a file called .worktreeinclude in your project folder. List the files you want carried in, one per line, and every new session gets them automatically.
- Clean up when you are done. Hover the session in the sidebar and click the archive icon to remove its copy. There is also a setting called "Auto-archive after PR merge or close" that does it for you once the work has been merged.
If you work in the terminal instead of the desktop app, you get the same isolation with a flag. Run claude --worktree and a name, for example claude --worktree feature-auth. That makes a copy at .claude/worktrees/feature-auth on a branch called worktree-feature-auth. Open another terminal, run it again with a different name, and you have a second isolated session. Leave the name off and Claude picks one for you.
What To Actually Run In Parallel
Running two agents only saves you time if the two jobs do not need each other. If agent B has to wait and see what agent A came up with, you did not save anything. You just moved the waiting somewhere you cannot see it.
These are the five pairings I come back to. They work because the two halves never need to talk to each other.
The trick is that you give both of them the same short description of what the thing should do, and the test agent writes its tests from that description, not from the code. It never sees the other agent's work.
This is better than doing it in one session, not just faster. When one agent writes both, the tests get written to agree with the code it just wrote, so they pass even when the code is wrong. A test agent that only saw the description checks what you actually asked for.
Different files, different kind of work, and you can check each one on its own in a minute. The bug fix either works or it does not. The doc either reads right or it does not. This is the easiest first parallel run there is, and it is a good one to test the whole setup on.
This one is for people who are not writing code at all. Send one session off to read: competitor pages, reviews, the last six months of your own posts. Meanwhile the other one drafts from the outline you already have in your head.
The research does not have to arrive before the draft starts. Bad first drafts are what second passes are for. When the research lands, you hand it to the drafting session and it gets sharper.
My favorite one. Put your real task in one session. Put the small annoying jobs in the other: rename things, update dependencies, clean up warnings, write the readme that has been missing for a year.
Chores are close to perfect for parallel work. They are contained, they never depend on your main task, and you can tell in ten seconds whether the result is right.
Your website in one pane, client work in the other. Zero overlap, because they are not even the same files. This is the safest parallel run there is and the one people forget, because they think about parallel as splitting one job instead of running two lives.
This is also exactly what grouping the sidebar by project is for. Two headings, two sets of sessions, no confusion about which agent is on which thing.
And three things not to run in parallel:
- Two agents on the same file. The copies keep them from breaking each other, which is good. But now you have two different versions of the same file and you get to merge them by hand. You added work.
- A big rewrite next to anything else. A rewrite touches half your project, so every other branch fights with it when you go to merge. Do the rewrite alone. It is the one job that deserves your whole screen.
- Anything you cannot check quickly. If you cannot tell in about two minutes whether the answer is right, do not run it beside three other things. You will be tired, you will approve it without reading it, and that is how bad work gets in.
The Part Nobody Mentions
More agents means more reviewing. That is the whole cost, and it never shows up in the screenshots.
Four agents finishing at once is four sets of changes to read, four things to approve, four chances to miss something because you were skimming. Your attention is the real limit here. Not the app, not your computer, not your plan. You.
Two things that help, both small:
- Stagger your starts. Give the first session the longest job, then start the next one a few minutes later. If you launch four in the same minute, all four come back in the same minute, and now you have a line of things waiting on you.
- Keep one pane on the job that actually matters. The other sessions are running in the background whether you watch them or not, and the app will tell you when they finish. Your eyes belong on the one you would be upset to get wrong.
The real unlock of AI agents is not full autonomy, but human-in-the-loop systems design. Structure your agent inputs with explicit constraints, negative prompts, and automated test checkpoints. When building tools, keep token consumption lean by caching system prompts and isolating tasks into specialized sub-agents.