From c42f4ec2b9a6920b07308afd09038ca7be2bcf02 Mon Sep 17 00:00:00 2001 From: Ammar Date: Tue, 28 Oct 2025 15:32:25 +0000 Subject: [PATCH 1/9] build: add mdbook tools to nix devShell Add mdbook, mdbook-mermaid, and mdbook-linkcheck to the nix development shell for building documentation locally. These tools are required by the docs build scripts (scripts/docs.sh and scripts/docs_build.sh). --- flake.nix | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/flake.nix b/flake.nix index 52784c734..c8e22a2f2 100644 --- a/flake.nix +++ b/flake.nix @@ -130,6 +130,11 @@ bash nixfmt-rfc-style + # Documentation + mdbook + mdbook-mermaid + mdbook-linkcheck + # Terminal bench uv asciinema From d6f1631f37c8f38f67daf739460b775f668b45f4 Mon Sep 17 00:00:00 2001 From: Ammar Date: Tue, 28 Oct 2025 15:34:03 +0000 Subject: [PATCH 2/9] docs: bind mdbook server to all hosts by default Change `mdbook serve` to bind to 0.0.0.0 instead of localhost, allowing remote access to the docs server. This is useful for development environments like remote servers or containers. --- scripts/docs.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/docs.sh b/scripts/docs.sh index ac859d93b..8ee42a522 100755 --- a/scripts/docs.sh +++ b/scripts/docs.sh @@ -8,5 +8,5 @@ if [ ! -f "docs/mermaid-init.js" ] || [ ! -f "docs/mermaid.min.js" ]; then cd .. fi -# Serve the docs -cd docs && mdbook serve --open +# Serve the docs (bind to all hosts for remote access) +cd docs && mdbook serve --hostname 0.0.0.0 --open From 0a3208dfe4760de06429bd9cb4eaeda3d8d8ed25 Mon Sep 17 00:00:00 2001 From: Ammar Date: Tue, 28 Oct 2025 15:36:47 +0000 Subject: [PATCH 3/9] docs: enhance blockquote styling with alert support Improve blockquote design: - Increase padding and add border-radius for better visual appeal - Add subtle box-shadow for depth - Support GitHub-style alerts (Note, Tip, Important, Warning, Caution) - Color-coded left borders for each alert type: - Note: blue - Tip: green - Important: purple - Warning: orange - Caution: red - Better paragraph spacing within blockquotes Usage: > **Note**: This is a note > **Warning**: This is a warning > **Tip**: This is a tip --- docs/theme/custom.css | 83 ++++++++++++++++++++++++++++++++++++++----- 1 file changed, 75 insertions(+), 8 deletions(-) diff --git a/docs/theme/custom.css b/docs/theme/custom.css index e6c9af359..7a7b06eb2 100644 --- a/docs/theme/custom.css +++ b/docs/theme/custom.css @@ -291,17 +291,84 @@ table code { font-size: 0.9em; } -/* Blockquotes (callout style) */ +/* Blockquotes with GitHub-style alerts support */ blockquote { - border: 1px solid var(--color-border) !important; - border-left: 4px solid var(--color-plan-mode) !important; - background: color-mix(in srgb, var(--color-background-secondary), white 1.5%) !important; - padding: 0.5rem 0.6rem; - margin: 1.2rem 0; - color: color-mix(in srgb, var(--color-text), white 6%) !important; + border: 1px solid var(--color-border); + border-left: 4px solid var(--color-plan-mode); + background: color-mix(in srgb, var(--color-background-secondary), white 2%); + padding: 1rem 1.2rem; + margin: 1.5rem 0; + border-radius: var(--radius-md); + color: var(--color-text); + box-shadow: var(--shadow-1); +} + +blockquote p { + margin: 0.5rem 0; +} + +blockquote p:first-child { + margin-top: 0; +} + +blockquote p:last-child { + margin-bottom: 0; +} + +/* GitHub-style alert callouts */ +/* NOTE: blue */ +blockquote:has(p:first-child > strong:first-child:is([class*="Note"], [class*="note"])), +blockquote > p:first-child:has(strong:first-child:is([class*="Note"], [class*="note"])) { + border-left-color: hsl(210 70% 50%); +} +blockquote:has(p:first-child > strong:first-child:is([class*="Note"], [class*="note"])) p:first-child strong:first-child, +blockquote > p:first-child strong:first-child:is([class*="Note"], [class*="note"]) { + color: hsl(210 70% 60%) !important; } + +/* TIP: green */ +blockquote:has(p:first-child > strong:first-child:is([class*="Tip"], [class*="TIP"])), +blockquote > p:first-child:has(strong:first-child:is([class*="Tip"], [class*="TIP"])) { + border-left-color: hsl(120 50% 45%); +} +blockquote:has(p:first-child > strong:first-child:is([class*="Tip"], [class*="TIP"])) p:first-child strong:first-child, +blockquote > p:first-child strong:first-child:is([class*="Tip"], [class*="TIP"]) { + color: hsl(120 50% 55%) !important; +} + +/* IMPORTANT: purple */ +blockquote:has(p:first-child > strong:first-child:is([class*="Important"], [class*="IMPORTANT"])), +blockquote > p:first-child:has(strong:first-child:is([class*="Important"], [class*="IMPORTANT"])) { + border-left-color: hsl(268 94% 60%); +} +blockquote:has(p:first-child > strong:first-child:is([class*="Important"], [class*="IMPORTANT"])) p:first-child strong:first-child, +blockquote > p:first-child strong:first-child:is([class*="Important"], [class*="IMPORTANT"]) { + color: hsl(268 94% 65%) !important; +} + +/* WARNING: orange/yellow */ +blockquote:has(p:first-child > strong:first-child:is([class*="Warning"], [class*="WARNING"])), +blockquote > p:first-child:has(strong:first-child:is([class*="Warning"], [class*="WARNING"])) { + border-left-color: hsl(38 92% 50%); +} +blockquote:has(p:first-child > strong:first-child:is([class*="Warning"], [class*="WARNING"])) p:first-child strong:first-child, +blockquote > p:first-child strong:first-child:is([class*="Warning"], [class*="WARNING"]) { + color: hsl(38 92% 60%) !important; +} + +/* CAUTION: red */ +blockquote:has(p:first-child > strong:first-child:is([class*="Caution"], [class*="CAUTION"])), +blockquote > p:first-child:has(strong:first-child:is([class*="Caution"], [class*="CAUTION"])) { + border-left-color: hsl(0 70% 55%); +} +blockquote:has(p:first-child > strong:first-child:is([class*="Caution"], [class*="CAUTION"])) p:first-child strong:first-child, +blockquote > p:first-child strong:first-child:is([class*="Caution"], [class*="CAUTION"]) { + color: hsl(0 70% 60%) !important; +} + +/* Default strong styling in blockquotes */ blockquote strong { - color: var(--color-plan-mode) !important; + color: var(--color-plan-mode); } /* kbd (for keybinds page) */ From a981dd6a1eba2b13ad315869e831c33046a2ad59 Mon Sep 17 00:00:00 2001 From: Ammar Date: Tue, 28 Oct 2025 15:37:18 +0000 Subject: [PATCH 4/9] docs: remove border-radius throughout theme Set all border-radius values to 0 for a sharper, more consistent visual style across all elements (blockquotes, code blocks, tables, details, images, inputs, etc.). --- docs/theme/custom.css | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/theme/custom.css b/docs/theme/custom.css index 7a7b06eb2..e90d85c23 100644 --- a/docs/theme/custom.css +++ b/docs/theme/custom.css @@ -27,10 +27,10 @@ --link-color: rgb(62, 140, 218); --link-hover: var(--color-plan-mode-hover); --content-max-width: 78ch; - --radius-lg: 10px; - --radius-md: 8px; - --radius-sm: 6px; - --radius-xs: 4px; + --radius-lg: 0; + --radius-md: 0; + --radius-sm: 0; + --radius-xs: 0; --shadow-1: 0 1px 1px hsl(0 0% 0% / 0.25); --shadow-2: 0 2px 10px hsl(0 0% 0% / 0.35); From 6c84e568f3781c578577b5cf281cae4cf8a2fb8f Mon Sep 17 00:00:00 2001 From: Ammar Date: Tue, 28 Oct 2025 15:38:44 +0000 Subject: [PATCH 5/9] docs: simplify blockquote design for sharp corners Remove full border and box-shadow from blockquotes, keeping only the left border accent. This eliminates the diagonal corner artifacts that occurred when mixing thin borders with thick left borders at 0 radius. Changes: - Remove 1px full border (only keep 3px left border) - Remove box-shadow - Increase background opacity slightly for better contrast - Cleaner look that works well with sharp corners --- docs/theme/custom.css | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/theme/custom.css b/docs/theme/custom.css index e90d85c23..dbb674514 100644 --- a/docs/theme/custom.css +++ b/docs/theme/custom.css @@ -293,14 +293,11 @@ table code { /* Blockquotes with GitHub-style alerts support */ blockquote { - border: 1px solid var(--color-border); - border-left: 4px solid var(--color-plan-mode); - background: color-mix(in srgb, var(--color-background-secondary), white 2%); + border-left: 3px solid var(--color-plan-mode); + background: color-mix(in srgb, var(--color-background-secondary), white 3%); padding: 1rem 1.2rem; margin: 1.5rem 0; - border-radius: var(--radius-md); color: var(--color-text); - box-shadow: var(--shadow-1); } blockquote p { From 431b7c0e9af89176118e3952a98509fc82286405 Mon Sep 17 00:00:00 2001 From: Ammar Date: Tue, 28 Oct 2025 15:43:06 +0000 Subject: [PATCH 6/9] docs: restore border-radius with consistent application Bring back border-radius to fix diagonal border artifacts while maintaining a cohesive look throughout the UI. Changes: - Set consistent border-radius values (lg: 8px, md: 6px, sm: 4px, xs: 3px) - Apply to blockquotes (fixes diagonal corner issue) - Apply to inline code (xs: 3px) - Apply to code blocks (md: 6px) - Already applied to: tables, details, mermaid, images, kbd, search All UI elements now have matching rounded corners for a polished, consistent appearance. --- docs/theme/custom.css | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/theme/custom.css b/docs/theme/custom.css index dbb674514..889838e07 100644 --- a/docs/theme/custom.css +++ b/docs/theme/custom.css @@ -27,10 +27,10 @@ --link-color: rgb(62, 140, 218); --link-hover: var(--color-plan-mode-hover); --content-max-width: 78ch; - --radius-lg: 0; - --radius-md: 0; - --radius-sm: 0; - --radius-xs: 0; + --radius-lg: 8px; + --radius-md: 6px; + --radius-sm: 4px; + --radius-xs: 3px; --shadow-1: 0 1px 1px hsl(0 0% 0% / 0.25); --shadow-2: 0 2px 10px hsl(0 0% 0% / 0.35); @@ -233,12 +233,14 @@ p:has(+ ol) { padding: 2px 6px; font-family: var(--font-monospace); font-size: 0.92em; + border-radius: var(--radius-xs); } /* Code blocks */ pre { background: var(--color-background-secondary) !important; border: 1px solid var(--color-border) !important; + border-radius: var(--radius-md); box-shadow: var(--shadow-1); overflow: auto; margin: 1rem 0; @@ -297,6 +299,7 @@ blockquote { background: color-mix(in srgb, var(--color-background-secondary), white 3%); padding: 1rem 1.2rem; margin: 1.5rem 0; + border-radius: var(--radius-md); color: var(--color-text); } From 8de4246830448a0fb2cbc8e2c6834ccdf81a93d3 Mon Sep 17 00:00:00 2001 From: Ammar Date: Tue, 28 Oct 2025 15:47:26 +0000 Subject: [PATCH 7/9] docs: fix table border-radius rendering Tables weren't showing rounded corners because `border-collapse: collapse` prevents border-radius from working. Changes: - Use `border-collapse: separate` with `border-spacing: 0` - Add outer border to table element - Remove duplicate borders between cells (only right/bottom on cells) - Explicitly set border-radius on corner cells (first/last th/td) - Add `overflow: hidden` to enforce rounded corners Tables now have properly rounded corners matching other UI elements. --- docs/theme/custom.css | 35 ++++++++++++++++++++++++++++++++--- 1 file changed, 32 insertions(+), 3 deletions(-) diff --git a/docs/theme/custom.css b/docs/theme/custom.css index 889838e07..68c8149fa 100644 --- a/docs/theme/custom.css +++ b/docs/theme/custom.css @@ -261,23 +261,52 @@ pre > code { /* Tables */ table { - border-collapse: collapse; + border-collapse: separate; + border-spacing: 0; width: 100%; margin: 1.1em 0; background: var(--color-background-secondary) !important; + border: 1px solid var(--color-border); border-radius: var(--radius-md); + overflow: hidden; } table thead { background: color-mix(in srgb, var(--color-background-secondary), white 8%); - border-bottom: 2px solid var(--color-border) !important; +} +table thead tr:first-child th:first-child { + border-top-left-radius: var(--radius-md); +} +table thead tr:first-child th:last-child { + border-top-right-radius: var(--radius-md); +} +table tbody tr:last-child td:first-child { + border-bottom-left-radius: var(--radius-md); +} +table tbody tr:last-child td:last-child { + border-bottom-right-radius: var(--radius-md); } table th, table td { padding: 0.75em 1em; - border: 1px solid var(--color-border) !important; + border-right: 1px solid var(--color-border); + border-bottom: 1px solid var(--color-border); text-align: left !important; color: var(--color-text) !important; } +table th:first-child, +table td:first-child { + border-left: none; +} +table th:last-child, +table td:last-child { + border-right: none; +} +table thead th { + border-bottom: 2px solid var(--color-border) !important; +} +table tbody tr:last-child td { + border-bottom: none; +} table th { font-weight: 700; font-size: 1.05em; From 9789ec66edb5ac8d825380225cf283038a2cea9c Mon Sep 17 00:00:00 2001 From: Ammar Date: Tue, 28 Oct 2025 15:52:43 +0000 Subject: [PATCH 8/9] docs: reorganize workspace documentation structure Move local workspace details from workspaces.md into new local.md page, making it subordinate to Workspaces (matching SSH structure). Changes: - Create docs/local.md with local workspace details (worktrees, reviewing, filesystem layout) - Simplify docs/workspaces.md to high-level overview with links to specific workspace types - Update SUMMARY.md to include Local as sub-page under Workspaces Structure now: - Workspaces (overview) - Local (git worktree details) - SSH (remote workspace details) - Forking - Init Hooks This provides better organization and makes it easier to find workspace-type-specific information. --- docs/SUMMARY.md | 1 + docs/local.md | 43 ++++++++++++++++++++++++++++++++ docs/workspaces.md | 62 +++++++++++----------------------------------- 3 files changed, 59 insertions(+), 47 deletions(-) create mode 100644 docs/local.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 6934609c1..3a6e273b6 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -9,6 +9,7 @@ # Features - [Workspaces](./workspaces.md) + - [Local](./local.md) - [SSH](./ssh.md) - [Forking](./fork.md) - [Init Hooks](./init-hooks.md) diff --git a/docs/local.md b/docs/local.md new file mode 100644 index 000000000..f47102bb4 --- /dev/null +++ b/docs/local.md @@ -0,0 +1,43 @@ +# Local Workspaces + +Local workspaces use [git worktrees](https://git-scm.com/docs/git-worktree) on your local machine. Worktrees share the `.git` directory with your main repository while maintaining independent working changes and checkout state. + +## How Worktrees Work + +A worktree is a separate directory on the same filesystem as the main repository that shares a `.git` but has independent working changes and checkout state. **All committed changes from any worktree are visible to all other worktrees including the main repository.** + +It's important to note that a **worktree is not locked to a branch**. The agent can switch to new branches, enter a detached HEAD state, etc. When you create a workspace, the agent will begin at the selected branch but may switch freely in the course of the session. **We empower users to define their agent's branching strategy in AGENTS.md** + +## Filesystem Layout + +Local workspaces are stored in `~/.cmux/src//`. + +Example layout: + +``` +~/.cmux/src/ + cmux-main/ + improved-auth-ux/ + fix-ci-flakes/ +``` + +## Reviewing Code + +Here are a few practical approaches to reviewing changes from workspaces, depending on how much you want your agent to interact with `git`: + +- **Agent codes, commits, and pushes**: Ask agent to submit a PR and review changes in your git Web UI (GitHub, GitLab, etc.) + - Also see: [Agentic Git Identity](./agentic-git-identity.md) + - This is the preferred approach for `cmux` development but requires additional care with repository security. +- **Agent codes and commits**: Review changes from the main repository via `git diff `, push changes when deemed acceptable. +- **Agent codes**: enter worktree (click Terminal icon in workspace top bar), run `git add -p` and progressively accept changes into a commit. + +## Reviewing Functionality + +Some changes (especially UI ones) require the Human to determine acceptability. An effective approach for this is: + +1. Ask agent to commit WIP when it's ready for Human review +2. Human, in main repository, checks out the workspace branch in a detached HEAD state: `git checkout --detach ` + +**Note**: This workflow uses the detached HEAD state because the branch is already checked out in the workspace and you cannot check out the same branch multiple times across worktrees. + +If you want faster iteration in between commits, you can hop into the worktree directory and run a dev server (e.g. `bun dev`) there directly and observe the agent's work in real-time. diff --git a/docs/workspaces.md b/docs/workspaces.md index 31f5028ad..8d08d6dda 100644 --- a/docs/workspaces.md +++ b/docs/workspaces.md @@ -1,59 +1,27 @@ # Workspaces -cmux supports multiple workspace backends for different use cases: +Workspaces in cmux provide isolated development environments for parallel agent work. Each workspace maintains its own Git state, allowing you to explore different approaches, run multiple tasks simultaneously, or test changes without affecting your main repository. -- **Local workspaces**: [git worktrees](https://git-scm.com/docs/git-worktree) on your local machine -- **SSH workspaces**: Regular git clones on a remote server accessed via SSH +## Workspace Types -The backend is selected based on your runtime configuration. Local workspaces use git worktrees which share the `.git` directory with your main repository, while SSH workspaces are independent git clones on the remote machine. +cmux supports two workspace backends: -## Basics of worktrees +- **[Local Workspaces](./local.md)**: Use [git worktrees](https://git-scm.com/docs/git-worktree) on your local machine. Worktrees share the `.git` directory with your main repository while maintaining independent working changes. -A worktree is a seperate directory on the same filesystem as the main repository that shares a `.git` -but has independent working changes and checkout state. **All committed changes from any worktree are -visible to all other worktrees including the main repository.** +- **[SSH Workspaces](./ssh.md)**: Regular git clones on a remote server accessed via SSH. These are completely independent repositories stored on the remote machine. -It's important to note that a **worktree is not locked to a branch**. The agent can switch to new -branches, enter a detached HEAD state, etc. When you create a workspace, the agent will -begin at the selected branch but may switch freely in the course of the session. **We empower users to define their agent's branching strategy in AGENTS.md** +## Choosing a Backend -## Reviewing code +The workspace backend is selected when you create a workspace: -Here are a few practical approaches to reviewing changes from workspaces, -depending on how much you want your agent to interact with `git`: +- **Local**: Best for fast iteration, local testing, and when you want to leverage your local machine's resources +- **SSH**: Ideal for heavy workloads, long-running tasks, or when you need access to remote infrastructure -- **Agent codes, commits, and pushes**: Ask agent to submit a PR and review changes in your git Web UI (GitHub, GitLab, etc.) - - Also see: [Agentic Git Identity](./agentic-git-identity.md) - - This is the preferred approach for `cmux` development but requires additional care with repository security. -- **Agent codes and commits**: Review changes from the main repository via `git diff `, push changes when deemed acceptable. -- **Agent codes**: enter worktree (click Terminal icon in workspace top bar), run `git add -p` and progressively accept changes into a commit. +## Key Concepts -## Reviewing functionality +- **Isolation**: Each workspace has independent working changes and Git state +- **Branch flexibility**: Workspaces can switch branches, enter detached HEAD state, or create new branches as needed +- **Parallel execution**: Run multiple workspaces simultaneously on different tasks +- **Shared commits**: Local workspaces (using worktrees) share commits with the main repository immediately -Some changes (esp. UI ones) require the Human to determine acceptability. An effective approach -for this is: - -1. Ask agent to commit WIP when its ready for Human review -1. Human, in main repository, checks out the workspace branch in a detached HEAD state: `git checkout --detach ` - -Note: this workflow uses the detached HEAD state because the branch is already -checked out in the workspace and you cannot check out the same branch multiple times -across worktrees. - -If you want faster iteration in between commits, you can hop into the worktree directory and run a -dev server (e.g. `bun dev`) there directly and observe the agent's work in real-time. - -## Filesystem Layout - -Local workspaces are stored in `~/.cmux/src//`. - -SSH workspaces are stored on the remote machine at `~/workspace//` (or your configured remote path). - -Example layout: - -``` -~/.cmux/src/ - cmux-main/ - improved-auth-ux/ - fix-ci-flakes/ -``` +See the specific workspace type pages for detailed setup and usage instructions. From c814d3dd7e73bbc76eb352e2f9d5a18f3ecd46e4 Mon Sep 17 00:00:00 2001 From: Ammar Date: Tue, 28 Oct 2025 15:54:58 +0000 Subject: [PATCH 9/9] docs: move reviewing sections to main Workspaces page Move 'Reviewing Code' and 'Reviewing Functionality' sections from local.md to workspaces.md since they apply to both local and SSH workspaces. Changes: - Add reviewing sections to workspaces.md after 'Key Concepts' - Remove reviewing sections from local.md (now focuses on worktree mechanics and filesystem layout) - Add note in 'Reviewing Functionality' about detached HEAD being specific to local workspaces This reduces duplication and puts shared concepts in the parent page where they're easier to find. --- docs/local.md | 21 --------------------- docs/workspaces.md | 23 +++++++++++++++++++++++ 2 files changed, 23 insertions(+), 21 deletions(-) diff --git a/docs/local.md b/docs/local.md index f47102bb4..cff83015c 100644 --- a/docs/local.md +++ b/docs/local.md @@ -20,24 +20,3 @@ Example layout: improved-auth-ux/ fix-ci-flakes/ ``` - -## Reviewing Code - -Here are a few practical approaches to reviewing changes from workspaces, depending on how much you want your agent to interact with `git`: - -- **Agent codes, commits, and pushes**: Ask agent to submit a PR and review changes in your git Web UI (GitHub, GitLab, etc.) - - Also see: [Agentic Git Identity](./agentic-git-identity.md) - - This is the preferred approach for `cmux` development but requires additional care with repository security. -- **Agent codes and commits**: Review changes from the main repository via `git diff `, push changes when deemed acceptable. -- **Agent codes**: enter worktree (click Terminal icon in workspace top bar), run `git add -p` and progressively accept changes into a commit. - -## Reviewing Functionality - -Some changes (especially UI ones) require the Human to determine acceptability. An effective approach for this is: - -1. Ask agent to commit WIP when it's ready for Human review -2. Human, in main repository, checks out the workspace branch in a detached HEAD state: `git checkout --detach ` - -**Note**: This workflow uses the detached HEAD state because the branch is already checked out in the workspace and you cannot check out the same branch multiple times across worktrees. - -If you want faster iteration in between commits, you can hop into the worktree directory and run a dev server (e.g. `bun dev`) there directly and observe the agent's work in real-time. diff --git a/docs/workspaces.md b/docs/workspaces.md index 8d08d6dda..107f26890 100644 --- a/docs/workspaces.md +++ b/docs/workspaces.md @@ -24,4 +24,27 @@ The workspace backend is selected when you create a workspace: - **Parallel execution**: Run multiple workspaces simultaneously on different tasks - **Shared commits**: Local workspaces (using worktrees) share commits with the main repository immediately +## Reviewing Code + +Here are a few practical approaches to reviewing changes from workspaces, depending on how much you want your agent to interact with `git`: + +- **Agent codes, commits, and pushes**: Ask agent to submit a PR and review changes in your git Web UI (GitHub, GitLab, etc.) + - Also see: [Agentic Git Identity](./agentic-git-identity.md) + - This is the preferred approach for `cmux` development but requires additional care with repository security. +- **Agent codes and commits**: Review changes from the main repository via `git diff `, push changes when deemed acceptable. +- **Agent codes**: Enter worktree (click Terminal icon in workspace top bar), run `git add -p` and progressively accept changes into a commit. + +## Reviewing Functionality + +Some changes (especially UI ones) require the Human to determine acceptability. An effective approach for this is: + +1. Ask agent to commit WIP when it's ready for Human review +2. Human, in main repository, checks out the workspace branch in a detached HEAD state: `git checkout --detach ` (for local workspaces) + +**Note**: For local workspaces, this workflow uses the detached HEAD state because the branch is already checked out in the workspace and you cannot check out the same branch multiple times across worktrees. + +If you want faster iteration in between commits, you can hop into the workspace directory and run a dev server (e.g. `bun dev`) there directly and observe the agent's work in real-time. + +--- + See the specific workspace type pages for detailed setup and usage instructions.