How to Manage Multiple Projects (When Each One Has an AI Agent)

Managing multiple projects stopped being a time problem and became an attention problem. When each project has an agent like Claude Code or Codex working inside it, the work happens whether you’re looking or not. What you’re managing is no longer your hours across four repos, it’s four streams of decisions arriving at once.

Most advice about juggling projects assumes the projects sit still while you’re away. These don’t.

what actually changed

Old constraint: you can only be in one codebase at a time, so you context-switch, and switching costs you twenty minutes of ramp-up each way.

New constraint: all four codebases are moving simultaneously, and each one periodically stops dead waiting for a yes from you. Ramp-up cost didn’t go away. It got joined by two worse costs:

Stall time. An agent blocked on an approval you didn’t notice does nothing for forty minutes. That’s not slow, that’s stopped, and it’s invisible.
Review debt. Four agents producing work you haven’t read is four diffs of unverified change sitting in four repos. This is the one that quietly ruins weeks.

Everything below is aimed at those two.

rule 1: every project carries its own context

The agent should not need you to explain the project. Each repo gets a file at its root that says what this thing is, how to run it, what not to touch, and what the conventions are. Claude Code reads CLAUDE.md, and AGENTS.md is the emerging cross-agent equivalent that several tools read.

Keep it short and factual. Build and test commands, the deploy path, the one directory nobody should touch, the naming convention you actually use. A 40-line file that’s true beats a 400-line file that’s aspirational.

Do the same for tooling. Config an agent needs to work in a project belongs in the project, checked in where possible, so that opening the repo is the whole setup. MCP servers are the common case here, and per-project rather than global is almost always right: see per-project MCP configs. Our Claude Code configuration guide covers the whole file set.

The test: if you can drop an agent into a repo cold and it does the right thing without you narrating, that project is managed. If you have to explain the project every time, you’re the config file.

rule 2: the plan lives in the repo, not your head

With one project you can hold the plan in your head. With four you cannot, and you’ll discover that on Tuesday when you can’t remember whether the migration was done or just discussed.

Keep a plain markdown task list in each repo. Checkboxes, grouped by area, with enough of a sentence per task that it means something in three weeks. It’s for you first and the agent second, but the agent second is the point: an agent that can read the list can pick up the next thing without a briefing, and can tick off what it finished.

This is also how you park a project properly. Before you walk away, write down where it actually stands. Coming back to a repo with a current task list is a two-minute restart. Coming back to a repo with nothing written down is a half-hour archaeology session, and you’ll do it four times.

rule 3: contain the blast radius per project

Different projects deserve different amounts of trust, and treating them the same is how a client repo gets a force-push.

Three dials worth setting per project:

Approval strictness. Your scratch project can let the agent run freely. The production repo should ask before anything that writes or pushes. If your setup only has one global setting for this, that’s a problem you’ll pay for eventually.

Credentials. Separate API keys per client or per context, so a session in the wrong directory can’t spend or touch the wrong account.

Working copies. If two agents work in one repo, they need separate checkouts. Git worktrees are built in and take one command:

git worktree add ../myapp-auth -b feature/auth
git worktree add ../myapp-billing -b feature/billing

Each agent gets its own directory and branch, and you merge when the work is good. Skipping this is the most common way parallel agent work goes wrong: see two agents on the same repo for what actually breaks, and the git worktree guide for the mechanic.

rule 4: batch review, don’t interleave it

The instinct with four projects running is to read each diff as it lands. That’s the worst version. You end up half-reading everything with your attention split across contexts, which is how bad code gets approved by someone who was technically looking at it.

Better: let work accumulate, then review one project at a time with the whole project in your head. Read the diff properly, run the tests, then move to the next. Reviewing three changes in one repo back to back is far cheaper than three switches.

The exception is the blocking approval. Those you handle immediately, because the agent is stopped until you answer, and a two-second yes is not a context switch. What you’re batching is judgment, not permissions. Reviewing agent work goes deeper on doing the reading well.

rule 5: your attention is the real project limit

The workable number of concurrent projects is lower than the number of agents you can start. Starting agents is free. Reading what they produced is not.

For most people it’s three or four projects genuinely in flight, with others parked. Parked is a legitimate state, and parking well (rule 2) is what makes rotation cheap. Trying to keep eight live means eight shallow reviews, which is the same as none. How many agents can you actually run works through where the ceiling sits and why it isn’t your hardware.

rule 6: what needs you has to find you

The rules above are habits, and habits handle most of it. What they can’t fix is the discovery problem.

A terminal treats every session as the same undifferentiated stream of characters. It has no idea that one tab is blocked on an approval and another finished nine minutes ago, because it doesn’t know what those states are. So the job of noticing falls to you, and you do it by clicking through tabs, which is exactly the thing that doesn’t scale past a couple of projects.

Everything you can do about it in a plain terminal is a workaround. Name your tabs after the repo. Wire agent-side hooks to fire a desktop notification when a session goes idle or asks for input. Both help. Neither gives you a single view of what’s happening across four projects at once.

what crystl does about it

crystl is a Mac terminal built for this specific shape: several projects, each with agents in it, and one person keeping track.

Projects are first-class objects called gems. A gem holds its own sessions, its own MCP servers, its own API key selection, and its own approval mode, so rule 1 and rule 3 stop being discipline and become configuration. They all sit on one rail, a click apart.

The noticing is handled for you. Approval requests and agent questions surface as floating panels color-coded by project, so you know which repo is asking before you read a word, and they push to your phone. The agent activity panel shows every agent’s live state across every gem in one view. Sessions keep structured conversation history that survives closing a window, which is rule 2 with less typing. Isolated shards create the worktrees from rule 3 for you.

Any CLI agent counts here. Claude Code in one project, Codex in another, side by side in one queue, which is a view no single agent vendor is going to build for you.

the short version

Every project carries its own context, checked in.
The plan lives in the repo, not your head.
Contain the blast radius per project: approvals, keys, working copies.
Batch review by project. Answer blocking approvals immediately.
Three or four live projects. Park the rest properly.
Make what needs you come to you, instead of going looking for it.

The first five are habits you can start this afternoon. The sixth is where the tooling has to do the work, and it’s the one that decides whether four projects feels like four times the output or four times the noise.

crystl is free. Sign up at crystl.dev/login.