What's the difference between /cd and --add-dir? Why can't --add-dir replace /cd?
These two commands address different kinds of needs. --add-dir (and its counterpart /add-dir) adds a new directory alongside your existing working directory, letting Claude access files in that directory too — your session's primary working directory doesn't change, it just gains a wider reach. /cd, on the other hand, moves the session's entire primary working directory somewhere else; the original directory stops being the primary one.
This difference also shows up in how settings get applied: a directory added on the side mostly isn't treated as a full configuration source — only a few specific types of configuration (like enabledPlugins or certain CLAUDE.md cases) apply as exceptions. The new directory /cd moves you to, by contrast, fully applies its own project settings, hooks, MCP servers, skills, and agents, as though you'd started a brand-new session directly in that directory. If what you need is "swap the entire primary working scope," --add-dir can't achieve the same effect as /cd.
Why did the gap between "changing directories" and "new settings taking effect" — the wait for resume — exist in the first place, and what caused it?
This reflects that session-internal state (the working directory itself) and the persistent configuration-loading process (reading project settings, starting hooks, connecting to MCP servers) originally ran along different trigger paths. Moving the working directory is essentially changing a path variable the session currently remembers — that change itself can happen instantly, without much complexity. But project settings, hooks, and MCP servers were originally designed as a one-time loading process that happens "at session startup," not something that could be re-triggered at any point during a running session.
The behavior before 2.1.246 reflected, to some extent, that moving the working directory took a lighter path, while the full configuration-loading logic still only hung off the session-startup moment. So when you changed directories, only the directory path itself updated instantly; the configuration reload still had to wait for the next genuine "startup" — that is, a resume — to trigger. This fix essentially wires the configuration-loading process, which used to only fire at session startup, into the /cd moment as well, so the two no longer need a restart to stay in sync.
What does the trust prompt actually show now when you change directories, and how is that different from before?
Previously, if you moved to a directory that hadn't been trusted yet, the system would show a trust prompt, but that prompt couldn't tell you what the directory's settings would actually activate once you accepted — because under the old design, settings were only meant to take effect after a resume anyway, so the prompt itself simply didn't have complete information to list out yet.
After 2.1.246, the trust prompt now directly lists the allow rules, additional directories, hooks, and helper commands that this directory's settings would activate, letting you see the full list before you actually accept. If, after reviewing the list, you decide not to accept, the session stays in its original directory rather than being forced to move — meaning the trust decision is now made with full visibility into what would actually happen, rather than accepting first, moving over, and gradually discovering what was in that directory's settings through later operations.
If I regularly use /cd to switch between several different projects within the same session, how does this fix actually affect my workflow?
The most direct impact is that you no longer need to deliberately end and resume a session just to get the new directory's settings to apply — if you'd built a habit of "resume once after changing directories to make sure settings apply," that habit can now be skipped entirely, since settings already take effect the moment you move.
The more practically relevant difference to watch for is that project-scope and local-scope MCP servers under the old directory now disconnect the instant you change directories. If your workflow used to rely on keeping certain background connections alive across a switch — say, monitoring something continuously through the old directory's MCP Server — that kind of connection now disconnects the moment you move, rather than accidentally lingering as it might have before, back when settings simply weren't applied in real time. If your workflow depends on keeping certain connections active across multiple directories simultaneously, you may need to redesign it around adding directories with --add-dir instead of switching entirely with /cd.
Claude Code's /cd command (available since version 2.1.169) lets you move a session's working directory somewhere else while keeping the conversation. Version 2.1.246 fixed a gap that had existed since the command launched: previously, after changing directories, the new directory's project settings, hooks, MCP servers, and skills only actually took effect once you later resumed the session. As of 2.1.246, these now apply the moment you move.
/cd <path> addresses the scenario where you want to move an entire session's primary working directory somewhere else — not adding an extra directory alongside the current one the way --add-dir does, but genuinely relocating the whole session. Claude Code keeps the conversation, loads the new directory's CLAUDE.md, and prompts you to trust the workspace if this is your first time working there. Afterward, if you resume this session with --resume from the new directory, the system can find it.
Before this fix, /cd would move the working directory, but the new directory's project settings (including its permission rules), hooks, servers configured in .mcp.json, and skills didn't actually apply to the current session right away — you had to end it and restart with --resume before those settings genuinely took effect. That meant there was an easy-to-miss window between moving directories and that directory's settings actually kicking in. If you started operating right after the move, what actually applied could still be the old directory's configuration mix, not the new settings you assumed you'd already switched to.
Post-fix, the instant you change directories, the new directory's project settings (including permission rules), hooks, servers from .mcp.json (still subject to the usual approval process), skills, and agents all take effect immediately, with no need to end and resume the session. If the new directory hasn't been trusted yet, the trust prompt now lists exactly which allow rules, additional directories, hooks, and helper commands that directory's settings would activate, letting you review before deciding whether to accept. If you decline, the session stays in its original directory rather than being forced to move.
Beyond the core fix of settings applying immediately, there are a few pre-existing behaviors around /cd worth knowing together with this. Additional directories switch to whatever list is defined in the new directory's settings, but any directories you manually added with --add-dir or /add-dir are preserved and won't disappear just because you changed directories. Project-scope and local-scope MCP servers under the old directory get disconnected, as do servers provided by plugins no longer enabled in the new directory. And hooks triggered by the move still receive a ${CLAUDE_PROJECT_DIR} environment variable pointing to the project root where the session originally started — that value doesn't change just because you moved directories.
If you need to restrict the scope of where /cd can go, you can configure this through Cd-category permission rules. A bare Cd deny rule disables the entire /cd feature outright; a deny rule paired with a path blocks matching target directories. The moment you add even one Cd allow rule, /cd switches to allowlist mode, and from then on only target directories matching an allow rule can be moved to. With no Cd rules configured at all, /cd keeps its default behavior, still prompting for trust when it encounters an unfamiliar directory.