Working Directory

Every session has a working directory — the folder tools like Bash, Read, Write, Grep, and Glob use to resolve relative paths. A relative path you type like ./src/foo.ts is resolved against the session's working directory at the moment a tool runs.

You'll rarely need to think about this — the default works well — but when you want to scope a session to a specific folder, or run agent sub-tasks in git worktree isolation, this is the mental model.

Default

A new session inherits its working directory from, in order:

1. The workspace's defaults.workingDirectory (if set in {workspace}/config.json).
2. The workspace root path.

For a workspace you created as "Open a folder on disk" (say ~/code/my-app), the default working directory is ~/code/my-app. For a purely "container" workspace under ~/.fabric-agent/workspaces/{id}/, it's that directory.

The two cwds

There are actually two working-directory fields on a session:

Practically: the first time you send a message, sdkCwd locks in. After that, changing workingDirectory still changes where Bash runs commands — but the SDK's transcript-on-disk stays in the original location. If you want a truly fresh directory scope, create a new session.

Changing working directory

The chat input shows a working-directory badge — click it to pick a different folder. A short history of recently-used directories lives behind a dropdown so you can switch back quickly.

Changing doesn't reset the conversation. Context history, tool results, permissions, and the locked LLM connection all carry over. Only path resolution changes.

Relative paths

Tools resolve relative paths at invocation time, against whatever the session's working directory is right now. If you change the working directory mid-session, the next tool call uses the new cwd; earlier tool results stay unchanged.

Absolute paths ignore the working directory entirely — they're used as-is.

Isolation worktrees

When an agent spawns sub-agents to work in parallel, you can opt them into git worktree isolation. Turn on "Isolate child agents" when creating a session, and any child session gets its own worktree:

~/.fabric-agent/worktrees/{workspace-id}/{child-session-id}

on a throwaway branch named:

fabric-agent/subagent/{parent-session-id}/{child-session-id}

The child session runs in this isolated worktree. It can edit files, run builds, and commit without touching the parent's working tree — perfect for "try three approaches to this bug in parallel" workflows. When the child exits, the worktree persists until you clean it up manually (git worktree remove).

Isolation is fixed at session creation — you can't toggle it on an existing session, because the worktree has to be provisioned up-front.

Tools affected

The following tools all operate relative to the session's working directory:

• Bash — shell commands run with cwd set.
• Read / Write / Edit — file operations.
• Grep / Glob — search within the directory subtree.

MCP tools and API source tools are unaffected — they have their own endpoints or parameters and don't participate in cwd resolution.

UI surfaces

• Chat input — the working-directory badge shows the current folder and lets you change it.
• Session list — not shown directly; the workspace context is the quick indicator.
• Inside a tool result — tool outputs show paths relative to cwd where useful; hover for the absolute path.

Related

• Conversations — per-session settings and the session-locked LLM connection.
• Workspaces — workspaces are the outer scope; working directory is the inner scope inside a session.
• Permissions — how Explore / Ask / Execute modes limit what tools can do inside the working directory.