# Work views (/docs/concepts/work-views)



A work view is an opt-in, isolated view of a project that lives under
`~/Code/.work`. You use one when you want to try something risky, run an
experiment, or hold changes for review before they touch the main project, all
without a Git worktree, branch, commit, or pull request. The same work view
folders serve humans and coding agents, so the path is the product and the Git
ceremony stays optional.

## What a work view is [#what-a-work-view-is]

A work view is a real, cd-able directory with a fresh base, isolated writes,
inherited project env, and lazy hydration. You create one, work in it with your
normal shell and editor, and then accept it into the main project or discard it.
Nothing in a work view reaches the main project until you accept it.

Two paths matter, and both are stable across every authorized machine:

| Path                             | What it is                                                |
| -------------------------------- | --------------------------------------------------------- |
| `~/Code/acme/web`                | The main view: the normal project path.                   |
| `~/Code/.work/acme/web/auth-fix` | A work view: an isolated, named view of the same project. |

`~/Code/.work` is a Bowline namespace, not source inside a repository. It never
shows up as untracked content and never makes `git status` noisy in the main
view. Creating a work view is metadata-first: Bowline records a small work view
ref that points at the project, a base Workspace Snapshot, an empty overlay, and
the project env profile. It does not copy or upload the project tree, and other
devices learn the work view exists without downloading anything until they touch
it.

<Callout type="info">
  Work views inherit project env by default. Your `.env`, `.env.local`, and
  `.env.*` values rematerialize in the work view, so `cd ~/Code/.work/acme/web/auth-fix && pnpm dev`
  works without copying secrets between machines.
</Callout>

## Automatic head advance versus review-before-apply [#automatic-head-advance-versus-review-before-apply]

The contrast with ordinary work is the reason work views exist. When you edit a
project at its main path, those edits form a Machine Overlay on the current
Workspace Snapshot. A non-conflicting Machine Overlay becomes a new Workspace
Snapshot and advances the Workspace Head automatically. There's no accept step
and no Git publish required. Diverging edits become a Sync Conflict instead.

A work view holds its changes in an isolated overlay that never advances the
main project's Workspace Head on its own. The overlay stays separate until you
run `bowline accept`, at which point Bowline performs a three-way snapshot merge
against the current main view. This is what makes a work view the place for
review-before-apply work: the main project keeps moving while the work view
waits for your decision.

## Lifecycle [#lifecycle]

A work view moves through a fixed set of lifecycle states. The default view of
`~/Code/.work` stays small. It shows active work you started or follow, plus
review-ready work, while accepted, discarded, expired, and archived work stays
out of the way but remains discoverable.

| State          | Meaning                                                       |
| -------------- | ------------------------------------------------------------- |
| `active`       | Writable or currently in progress.                            |
| `review-ready` | Complete enough for you to review.                            |
| `accepted`     | Merged into the main view.                                    |
| `discarded`    | Intentionally thrown away.                                    |
| `expired`      | Inactive beyond retention policy.                             |
| `archived`     | Hidden from the default view but restorable during retention. |

You drive the lifecycle with a small set of commands. Mutating commands accept
`--dry-run` to preview the effect and `--idempotency-key <key>` to make retries
safe, and most accept `--json`.

| Command                           | What it does                                            |
| --------------------------------- | ------------------------------------------------------- |
| `bowline workon [project] <name>` | Create or reuse a named work view under `~/Code/.work`. |
| `bowline work [--include-hidden]` | List work views and their state.                        |
| `bowline diff <target>`           | Show what the work view changed.                        |
| `bowline review [target]`         | Preview whether the work view is ready to apply.        |
| `bowline accept <target>`         | Apply a review-ready work view into the main view.      |
| `bowline discard <target>`        | Drop a work view without touching the main view.        |
| `bowline restore <target>`        | Bring a hidden or discarded work view back into view.   |
| `bowline cleanup [--apply]`       | Reclaim local backing store for hidden work views.      |

## Using a work view [#using-a-work-view]

The daily loop stays boring on purpose. Create a work view, work in it with
ordinary tools, then decide what happens to it.

1. Create or reuse a work view with `bowline workon ~/Code/acme/web auth-fix`.
2. Change into it with `cd ~/Code/.work/acme/web/auth-fix` and work normally:
   run `pnpm dev`, edit files, run tests.
3. Inspect the result with `bowline diff auth-fix`, and confirm readiness with
   `bowline review auth-fix`.
4. Apply it with `bowline accept auth-fix`. The main view advances to a new
   Workspace Snapshot, and `cd ~/Code/acme/web && git diff` shows the change for
   your own Git workflow.
5. Or drop it with `bowline discard auth-fix`. Discard hides the visible path and
   leaves the main view untouched; overlay state remains recoverable with
   `bowline restore auth-fix` until retention expires.

<Callout type="warn" title="Important">
  Accepting a work view never commits, pushes, opens a pull request, or mutates
  any source-control ref. It merges files into the main view only. Publishing
  stays your Git workflow, and changes that touch policy, secrets, or conflicting
  spans require an explicit review path before they apply.
</Callout>

## Work views and agent leases [#work-views-and-agent-leases]

Work views are useful without agents, and that's the pressure test that keeps
them clean. Agent leases then consume the same primitive. A trusted agent writes
to the real project directory by default, but passing `--work-view` to
`bowline agent start` binds the lease to an isolated work view instead:

```bash
bowline agent start ~/Code/acme/web \
  --task "fix auth callback race" \
  --work-view
```

The agent writes only inside that work view and returns review-ready work. You
inspect its output with normal tools (`cd ~/Code/.work/acme/web/<name>`,
`bowline diff <name>`, `pnpm test`) and then `bowline accept <name>` or
`bowline discard <name>`. This keeps the agent machinery below the product fold:
you see folders and status, not a workflow console.

## Next steps [#next-steps]

* [Agent leases](/docs/concepts/agent-leases): how a lease scopes an agent's
  authority, budget, and writes.
* [Work with coding agents](/docs/guides/working-with-agents): a task guide for
  handing work to local and remote agents.
* [Sync and continuity](/docs/concepts/sync-and-continuity): how non-conflicting
  overlays advance the Workspace Head automatically.
* [Conflicts](/docs/concepts/conflicts): what happens when an accept can't merge
  cleanly.
* [CLI commands](/docs/cli/commands): the full reference for `bowline workon`,
  `accept`, `discard`, and `cleanup`.