Work views

Isolated, cd-able project views under ~/Code/.work for risky or review-before-apply work, shared by humans and agents.

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

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.

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.

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

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

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

Create or reuse a work view with bowline workon ~/Code/acme/web auth-fix.
Change into it with cd ~/Code/.work/acme/web/auth-fix and work normally: run pnpm dev, edit files, run tests.
Inspect the result with bowline diff auth-fix, and confirm readiness with bowline review auth-fix.
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.
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.

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.

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:

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

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