Allow user-defined named projects that map to multiple directories

Resolved 💬 2 comments Opened Feb 11, 2026 by wolf Closed Mar 12, 2026

Problem

Claude Code derives project identity from the working directory path, creating a 1:1 mapping between directories and projects. This doesn't match how developers actually think about projects:

  • Git worktrees of the same repo get separate project identities (see #24382)
  • Subdirectories that are conceptually distinct projects (e.g., ~/.claude/ within a dotfiles repo) can't have their own identity
  • Directory reorganization orphans project config (see #24789)
  • Related directories that are part of the same logical project (monorepo modules, paired repos) can't share memory

The common root cause is that project identity is implicit and path-derived, when it should be explicit and user-defined.

Proposed solution

Allow users to define named projects and map directories to them. For example, a configuration like:

{
  "projects": {
    "siloc": ["~/develop/dmp/siloc", "~/develop/dmp/siloc-*"],
    "dotfiles": ["~/dotfiles"],
    "claude": ["~/.claude"]
  }
}

This would mean:

  • Launching from ~/develop/dmp/siloc/ or any worktree matching siloc-* shares one memory directory
  • ~/.claude/ gets its own project identity even if it lives inside a dotfiles repo
  • Memory, session history, and project-level config are tied to the project name, not the directory path

Benefits

  • Solves the worktree problem (#24382) as a special case
  • Solves the directory reorganization problem (#24789) — just update the mapping
  • Gives users a mental model that matches how they actually work
  • Named projects could also enable features like per-project settings overrides

Environment

  • Claude Code CLI, macOS

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗