Skip to content

Thirty terminals, twenty apps: structuring a multi-repo Claude Code workflow

5 min readcitizencapet

You do not have one project open. You have twenty. You do not run one Claude session. You run thirty. Here is the shape of the workflow that does not collapse under that load.

The tutorials show one repo, one terminal, one Claude Code session. That is not the real shape of the work. The real shape is twenty repos open in the background, three to four live sessions doing things you care about right now, a dozen more in pause while you wait for a build or a review, and a scratchpad tab where you triage.

If you are running that load and not losing things, you are already doing most of what is in this post. If you are losing things, here is the discipline that stops the bleeding.

One cwd per tab, always

The single highest-leverage rule. Every terminal tab starts with cd into exactly one repo. Never run a Claude session from a cwd that is a parent of multiple repos, and never split a single Claude session across two repos using cd.

Why: Claude Code derives the project identity from the initial cwd, and writes the session JSONL under ~/.claude/projects/<encoded-cwd>/. If you start in ~/code and cd api mid-session, the JSONL still lives under the parent folder and the session will forever be misfiled. Recall's project listing becomes noisy the moment this rule breaks.

# good
cd ~/code/billing && claude

# bad
cd ~/code && claude
# then "cd billing" inside the session

Alias every session day-of

A raw UUID is not a name. Forty sessions in, you cannot find anything by UUID alone. Alias them as you close them:

recall alias 0f3c9a11 "billing: webhook retry backoff"

Aliases are the handle you will use a week later when you half-remember what you were doing. Do this at the end of the session while the context is still in your head, not a month later when you are trying to find it.

Tag by feature, not by project

Tags are flat and they auto-filter in the web UI. They are also global, which means a tag cuts across projects. This makes them the right place for cross-repo concepts (#auth, #migration-order, #perf-regression) and the wrong place for project names. The project-name dimension is already handled by cwd.

recall tag add 0f3c9a11 auth
recall tag add 0f3c9a11 rate-limit

Keep the tag namespace small. Fifty tags is reasonable. Five hundred is a second problem you now need to manage.

Triage with -p <substring>

recall list -p billing --since 7d

The -p flag takes a substring against the project path, so you do not have to remember the full cwd. Combined with --since it becomes a daily triage tool. Every morning: list the last 24 hours across the two or three projects you are actively on, alias and tag anything important, close what is noise.

Pin the canonical-decision session

Some sessions matter disproportionately. The one where you settled on the schema. The one where you picked the retry strategy. The one where you untangled the auth flow. These are load-bearing decisions and you will want them two years from now.

Pin them:

recall pin 0f3c9a11

Pinned sessions rise to the top of the project view and live in a dedicated list. They are the thing you hand to a new teammate, or to a fresh Claude session when you need to rebuild the mental model.

Write the note on close

Aliases are titles. Notes are executive summaries. Every pinned session should have a one-paragraph note that says what was decided, why, and what it obsoletes. Future-you will not re-read a 400-turn session to reconstruct the call. Future-you will read the note.

recall note add 0f3c9a11 "Chose exponential backoff with jitter, max 6 retries. \
Rejected fixed interval because of thundering herd risk on the webhook endpoint."

The note and the transcript sit side by side in the UI. The note is the index card.

The scratchpad tab

One non-obvious piece: keep a dedicated scratchpad tab that is not a Claude session. It is a plain shell in ~ with your triage commands in history. This is where you run:

recall list --since 24h
recall search "the thing I half remember"
recall tag list
recall pin list

The scratchpad is the outside-the-agents view. When the other twenty-nine tabs are alive and busy, the scratchpad is where you decide what to pay attention to. Without it, triage starts competing with actual work for the same shell, and one of them loses.

Pause and resume without losing thread

You will be pulled off a session. A meeting, a production issue, a lunch. Three hours later you come back. The tab is still there, the scrollback is mostly intact, but the mental model is gone.

The move: before stepping away, spend thirty seconds writing a note on the current session with the single sentence "where I was about to go next". On return, open the UI, read the note, and you are oriented again in seconds. The note does not have to be good. It has to exist.

recall note add <current-session-id> "Next: wire the retry handler into the webhook worker and add the jitter constant to config."

This is the cheapest habit on this list and the one that most directly pays back under interrupt-driven work. The twenty-app workflow is an interrupt-driven workflow by definition.

The workflow, compressed

  1. One cwd per tab, entered before claude starts.
  2. Alias every session before you close the tab.
  3. Tag with 3 to 5 flat, cross-repo concepts.
  4. Use recall list -p <substring> --since 24h every morning for triage.
  5. Pin the decision sessions. Write a note on each one.
  6. For a truly important effort, create a collection and add the relevant sessions. Collections are hand-picked and hierarchical; tags are flat and auto-filtered. They solve different problems.

Thirty terminals stops being a house of cards the moment you treat the session history as a queryable database rather than a scrollback buffer. That is the whole mental shift. Start with the CLI reference or the shortcuts page for the keybindings that make the UI side of this fast.