Claude Code project layout on macOS: a folder structure that survives 10 parallel sessions

If you've tried to run three Claude Code sessions in parallel on a single Mac, you've hit the wall: not the model, not the rate limits — your own file system. The agent generates artifacts, you stash them somewhere, and within an hour you can't find the screenshot from session two or remember which prompts/ directory has the right system prompt for a code review pass.

This is the layout we use behind mq-dir to keep ten sessions traceable. It works whether you have one Claude window open or five.

The shape of a session

A "session" is a single AI run, scoped to a goal: "refactor the auth module", "draft a launch blog post", "port the iOS pane code to AppKit". Sessions can last 30 minutes or three days. They share three properties:

1. They produce source changes (commits, diffs).
2. They produce artifacts (screenshots, transcripts, exported plans).
3. They consume inputs (reference docs, prompt templates, design files).

If you treat all three as the same kind of file, you blow up your IDE's search and your version control — both lose signal under the volume. Splitting them is the single highest-leverage move.

Top-level directory layout

Here's the layout we land on after a year of iteration:

~/dev/
├── _shared/                    ← global, version-controlled
│   ├── prompts/                ← reusable system prompts
│   ├── references/             ← internal docs you re-reference often
│   └── snippets/               ← code patterns you paste
├── sessions/                   ← ephemeral working sessions
│   ├── 2026-04-22-auth-rewrite/
│   │   ├── CLAUDE.md           ← session goal + scope + rules
│   │   ├── artifacts/          ← screenshots, transcripts
│   │   ├── notes.md            ← running log of what you tried
│   │   └── repo/               ← worktree of the actual codebase
│   └── 2026-04-22-launch-post/
│       └── …
└── repos/                      ← long-lived working copies
    ├── mq-dir/
    └── another-project/

Three shapes worth noting:

• _shared/ is version-controlled in its own repo. You'll want this when you reformat your laptop in 2027.
• sessions/<date>-<topic>/ is ephemeral. You should be able to rm -rf it after the session lands without losing anything important. The session's commits go into repos/<project>/, not into the session folder.
• sessions/*/repo/ is a git worktree, not a clone. Saves disk and keeps refs unified.

The session's CLAUDE.md

Every session directory has a CLAUDE.md at its root. It's two paragraphs:

# Session: auth module rewrite — 2026-04-22

## Goal
Replace the legacy ASP.NET cookie auth with the new JWT path documented
in repos/main-app/docs/auth.md. Ship behind a feature flag.

## Out of scope
Don't touch the user-management UI. Don't migrate test fixtures —
follow-up session will handle them.

## Constraints
- All new files: TypeScript strict
- Run `npm test -- --bail` after every commit
- Don't push to main; PR to feat/auth-jwt

You will save more time than you spent writing it. When you context-switch back to this session three days later, you read the file, you're caught up. When the agent goes off-track, you point at the file and it self-corrects.

The four-pane workflow

This is where the file manager matters. With one pane, you're alt-tabbing through Finder windows, and your three Claude windows are your only context. With four panes, you can hold a session entirely on one screen:

The point isn't the specific pinning — it's that each pane has one job, and you stop hunting. mq-dir's quad-pane layout was designed against this exact use case: open four panes, route ⌘1–4 to focus each, never drag a Finder window again.

Naming convention for sessions

YYYY-MM-DD-<verb>-<noun>. Examples:

• 2026-04-22-rewrite-auth
• 2026-04-22-draft-launch-post
• 2026-04-23-debug-pane-flicker

The date prefix sorts naturally. The verb-noun is dense enough to scan from a list of 30 sessions ("which one was the auth thing?"). Avoid putting the project name in the session name — it's already in the repo path.

Where prompts go

The single biggest unlock for repeatable AI work is a flat prompt library. We keep ours under _shared/prompts/, one file per prompt, named by intent:

_shared/prompts/
├── code-review-strict.md
├── code-review-style.md
├── pr-description-writer.md
├── ios-to-appkit-port.md
├── markdown-to-html-with-toc.md
└── …

Two rules:

1. Never inline. If you find yourself pasting "review this code carefully and check…" into a session, stop and write the prompt as a file. Future-you will thank you.
2. Test in production. Use the real prompts the real agent uses. Don't have a "draft" library and a "live" library — that's how prompts decay.

In mq-dir, ⌘-clicking a .md in the prompt-library pane opens it in the Markdown preview, so you can re-read before pasting. Small thing; matters daily.

Artifacts: keep them sparse, keep them dated

Artifacts are the leak point. Every session creates dozens, you stop noticing, and a quarter later your laptop is 80% screenshots. Two practices:

1. Subfolder per type: artifacts/screenshots/, artifacts/transcripts/, artifacts/exports/. Nine times out of ten you only want one type — shallow folders save hunting.
2. Quarterly cleanup: When you start a session in a new quarter, rm -rf sessions/2025-Q4-* if those sessions have shipped. Brutal but necessary.

The pane-with-preview workflow makes this less painful: you can flip through 30 screenshots in a pane in under a minute and decide what to keep.

What this gives you

After a few weeks of using this layout, three things happen:

1. Sessions become composable. You can pause one mid-flight, work on another, and come back without re-orienting.
2. Prompts compound. Your prompt library gets smarter every week, and you spend less time re-typing the same instructions.
3. The agent stays on-rails. A session's CLAUDE.md is a contract — you give it to the agent at the start, point at it when it drifts, and tear it up when the session ends.

That's it. Not a framework, not a tool — a layout. The directory structure does the work. mq-dir is what we built to make navigating that structure not painful, but the structure itself is portable: drop it on Linux, drop it on a fresh Mac, drop it on a colleague's laptop.

If you try it for a week and your session count grows from two to five without your file system melting, the layout is doing its job.