v1.0.0

Builder 1.0.0

Builder 1.0 is focused on making long-running agent work safer to resume, easier to inspect, and easier to split across sessions and worktrees.

Highlights

Sessions are project-aware

Builder now keeps structured metadata for projects, workspaces, sessions, worktrees, and runtime leases in a local database. This gives sessions an explicit execution target instead of treating the current directory as implicit state.

When Builder starts in an unknown workspace, it can bind that workspace to a project. Existing sessions can also be retargeted if their workspace moved:

builder project
builder attach <path>
builder attach --project <project-id> <path>
builder rebind <session-id> <new-path>

This is most visible when resuming sessions, attaching to a local daemon, or running headless agents from a workspace that Builder has not seen before.

Git worktree management

Builder can create, switch, and delete git worktrees from the TUI with /wt or directly from slash commands:

/wt
/wt create
/wt switch <target>
/wt delete [<target>]

Switching worktrees moves the session execution target, runtime cwd, tool cwd, and transcript context together, so the agent sees the correct checkout. Deletes are guarded: Builder blocks deletion of the main worktree, worktrees used by other sessions, and worktrees with running background processes. Dirty worktrees show a preview before confirmation.

Managed worktrees can be configured with:

[worktrees]
base_dir = "~/.builder/worktrees"
setup_script = "scripts/setup-worktree.sh"

Headless subagent roles

builder run now supports named headless roles:

builder run --agent fast "summarize the unstaged changes"
builder run --fast "find the flaky tests in this repo"
builder run --continue <session-id> "follow up"

Roles are configured under [subagents.<role>] and inherit normal Builder config. This makes background subagent workflows more predictable: interactive Builder can launch separate headless Builder instances, and humans can use the same mechanism directly in scripts or shells.

Custom system prompts

Builder supports SYSTEM.md files for replacing the built-in main system prompt:

~/.builder/SYSTEM.md
<workspace>/.builder/SYSTEM.md

The workspace file takes priority. Builder snapshots the rendered system prompt on the session's first model request, then reuses that snapshot when the session is resumed or moved. Editing SYSTEM.md affects new sessions, not already-locked sessions.

Supported placeholders include:

{{.DefaultSystemPrompt}}
{{.BuilderRunCommand}}
{{.EstimatedToolCallsForContext}}

Compact detail mode

Detail mode is now a compact transcript inspector instead of a long raw dump. Messages and tool calls are collapsed by default, can be expanded with Enter, and can be navigated with keyboard or mouse wheel in the detail alt screen.

The ongoing transcript remains optimized for native terminal scrollback, selection, and copy-paste. Detail mode is for inspecting the session structure, expanding specific tool calls, and understanding hidden or diagnostic context without flooding the main work surface.

Command execution and output shaping

The agent-facing shell tool is now the exec_command / write_stdin pair. Command output can be post-processed before it reaches the model, with built-in processing and an optional user hook:

[shell]
postprocessing_mode = "builtin" # none | builtin | user | all
postprocess_hook = "~/.builder/shell_postprocess_hook"

The tool can still request raw output when needed. Builder also seeds a managed ripgrep config at ~/.builder/rg.conf and exports it through RIPGREP_CONFIG_PATH when the user has not set one.

Shell subprocesses receive agent-friendly environment defaults such as AGENT=builder and non-interactive/progress-suppression variables for common tools including Docker, Compose, npm, and Yarn.

Patch tool improvements

The patch tool now uses a freeform patch format and reports structured failures with target paths preserved. Patch calls are easier to read in detail mode, including failures, move-only updates, and EOF-only hunks.

Authentication and startup polish

The startup and slash-command flows are more state-aware:

• /login is shown when Builder is unauthenticated or using API-key auth.
• /logout is shown when Builder is using saved OAuth auth.
• /resume is hidden when there are no other sessions to resume.
• first-run setup can import skills and slash-command directories from existing agent setups.

Model defaults

The default model is now gpt-5.5. Builder also tracks the configured context window and estimates the number of tool calls that fit in the available context budget for prompt rendering and compaction decisions.

Reliability

1.0 includes a large persistence and runtime cutover. The practical result is better continuity when sessions are resumed, moved, compacted, switched between worktrees, or attached through the local server.

Important reliability work in this release:

• session metadata moved to a structured local database while large transcript artifacts remain file-backed
• runtime activation uses explicit leases, improving recovery after stale controllers or interrupted runs
• local-first RPC transport avoids repeated setup costs for local daemon usage
• transcript replay, compaction, rollback, and detail hydration share stricter ordering rules
• native ongoing scrollback remains append-only while detail mode can hydrate compact inspection pages
• explicit TCP server targets are honored over same-machine socket optimization

Compatibility Notes

• Sessions are now bound to projects/workspaces. If a session cannot find its workspace, use builder rebind <session-id> <new-path>.
• Headless runs require the selected workspace to be attached to a Builder project. Use builder attach or builder attach --project <project-id> when running from a new checkout.
• Prompts or docs that mention the old model-facing shell tool should refer to exec_command and write_stdin for new sessions. The user-facing $ <command> shortcut remains the normal way to run shell commands interactively.
• Removed shell timeout config/CLI behavior is replaced by Builder's background process model. Commands can run indefinitely; yield_time_ms controls when Builder backgrounds the process and returns control.

Full changelog

New Features

• phase4a - add database
• complete phase 4b storage cutover
• complete phase 4c runtime cutover
• finish phase 5 and plan phase 4d
• complete phase 4d daemon cutover
• add unknown-workspace project binding flow
• add explicit workspace rebind
• continue phase 2 divergence fixes
• add remote auth bootstrap and workspace-aware attach
• expand sandbox dev toolchain
• add local-first persistent rpc transport
• add gws transport spike benchmarks
• switch websocket transport to gws
• feat!: retarget sessions with builder rebind
• feat!: confirm and retarget moved session workspaces
• seed managed ripgrep config
• feat!: replace shell tool with exec_command
• add exec_command post-processing
• add headless subagent roles
• add worktree management closes #68
• add git worktree management closes #68
• add gpt-5.5 model contract
• default to gpt-5.5
• estimate tool calls from context budget
• add freeform patch custom tool
• support SYSTEM.md prompt snapshots
• compact detail transcript inspector

Bug Fixes

• lock and test session launch visibility
• address phase 4 review findings
• address follow-up review findings
• harden metadata registration and migration
• tighten registration race recovery
• harden metadata and migration boundaries
• narrow workspace binding conflict recovery
• harden runtime activation lifecycle
• allow large migration manifests
• retry fileless metadata persistence
• lock staging before migration cutover
• close late phase 4 review gaps
• remove dead transcript reducer assignment
• address direct attach review regressions
• address remaining app-server review issues
• isolate process access by project
• skip daemon launch for unregistered workspaces
• enforce project attach invariants
• preserve optional lifecycle session ids
• preserve committed tool pairs before transient tails
• harden transcript replay semantics
• resolve nested workspace paths to attached roots
• align project binding prompt input UI
• require exact workspace path matches
• stabilize transcript hydrate diagnostics
• avoid replaying slid ongoing tail
• stabilize transcript event ranges
• harden transcript committed tail tracking
• harden project attach and runtime cleanup
• preserve continuity recovery cause across deferred sync
• harden transcript recovery and queued steering visibility
• harden project binding error handling
• harden rollback targeting and transcript authority
• enforce reviewer and compaction transcript ordering
• harden persisted local-entry ordering
• correct rollback transcript index mapping
• signal hosted tool transcript commits
• stream rollback transcript index resolution
• hydrate deferred committed user flushes
• close remaining transcript review regressions
• harden request replay and workspace rebind
• correct workspace rebinding and sandbox bootstrap readiness
• stabilize compaction transcript events
• materialize compacted detail transcript pages
• expose unknown developer messages in detail mode
• persist hidden noop reviewer turns
• keep skill warnings out of model context
• scope manual compaction carryover to latest segment
• drop pre-compaction developer context
• rebuild canonical compaction context order
• track headless state across compaction
• align native compaction prefix ordering
• unify compaction carryover projection
• align ongoing and local compaction transcript state
• update sandbox container workspace paths
• preserve transcript continuity across compaction
• drop reviewer rollback and recover scrollback after gaps
• clarify server project picker notice
• remove cache hit from status line
• restore typed remote and metadata errors
• harden runtime release and auth gating
• harden status refresh, remote attach, and lease checks
• bound binding command rpc calls
• address remaining medium review findings
• restore sandbox serve script mode
• restore request idempotency and runtime takeover
• harden request id memo retries
• keep bootstrap completion idempotent
• align rollback transcript index visibility
• restore process kill idempotency
• dedupe prompt answers by request id
• keep runtime release retries idempotent
• preserve native web search stream items
• serialize session runtime takeover activation
• dedupe runtime submit user message retries
• replay memoized writes before lease recheck
• recover from stale controller lease retries
• restore headless prompt retry safety
• harden queued runtime command retries
• restore compaction notice and gate remote auth reuse
• share pre-auth policy and cap request memo
• reuse workspace discovery for launched run prompt daemons
• cache session launch clients by workspace scope
• dedupe queued runtime user messages
• avoid memoizing primary run contention
• cache run prompt clients by workspace scope
• harden request replay idempotency
• rerun waiting retries after transient memo failures
• gate remote reuse on project attach
• align run prompt reuse tests with capabilities
• replay runtime control mutations by request id
• harden path search and transport tests
• isolate path search from git hook env
• isolate path search test from git hook env
• address transport review findings
• align run prompt tests after rebase
• finalize failed runtime takeovers
• support secure websocket endpoint dialing
• replay input draft mutations by request id
• isolate interrupt-sensitive runtime control calls
• converge concurrent workspace registration
• honor explicit tcp targets over local socket
• use shell-specific transcript highlighting (closes #140)
• show patch failures in detail transcript (closes #139)
• hide /resume when no other sessions exist closes #136
• add onboarding imports for agents dirs (closes #132)
• omit empty background shell log file notice (closes #131)
• suppress NO_OP completion notifications closes #113
• preserve live assistant state across detail hydrates
• stabilize tui spinner states
• recover expired controller leases safely
• keep spilled streaming append-only across detail mode
• surface disconnect failures in ongoing scrollback
• restore PR #145 CI stability
• address PR #145 review regressions
• harden PR #145 flaky cli app tests
• stabilize PR #145 detail roundtrip test
• avoid flaky detail render assertion in PR #145 test
• remove flaky PR #145 output assertion
• allow /resume when session availability is unknown
• allow unscoped session retargets
• preserve patch target paths in failures
• remove startup header inset from project binding flow
• remove glamour header margin in startup pickers
• append native compaction notices after hidden rewrites
• respect explicit local daemon targets
• harden native spill finalization checks
• align environment cwd with shell workdir
• simplify shell exit output notices
• drop local-only worktree prompt embeds
• address in-scope PR findings
• address follow-up PR review
• suppress duplicate interrupt cancellation errors
• sanitize reviewer suggestions
• keep default cache warnings out of ongoing mode
• honor cli tool overrides during launch
• defer failed override continuation updates
• isolate git worktree commands from inherited git env
• persist role-only continuation overrides
• make hook warning test deterministic
• preserve go test json output
• tighten worktree target resolution
• preserve session worktree metadata
• sync repaired worktree targets
• keep worktree target updates after overlay close
• address remaining PR 148 review findings
• normalize config model assertions
• clarify worktree transition prompts
• finish PR 148 review cleanup
• clean worktree transition context
• use live context for worktree rollback
• authorize worktree list reconciliation
• address latest PR 148 review findings
• resolve worktree create targets asynchronously
• harden worktree sync reconciliation
• stabilize worktree mutation locking
• keep worktree overlay open during switch
• persist runtime reminders after rebind
• clear stale reminders on workspace rebind
• update default model references
• keep commentary stream in assistant group
• show server subscription status
• silence noop turn bell
• align poll summary color
• resolve config per session workspace
• clarify worktree delete confirmation
• ignore dormant sessions for worktree delete blockers
• use runtime registry for worktree delete blockers
• render patch paths from active workdir
• force confirmed dirty worktree deletes
• probe dirty worktrees only for delete previews
• remove worktree delete transcript notes
• recover unavailable runtime controls
• harden lease recovery warning
• make lease warning visibility explicit
• render structured patch transcript calls
• address pr review regressions
• preserve eof-only patch hunks
• allow move-only patch updates
• address follow-up pr review findings
• address latest pr review findings
• gate custom patch tool on active provider
• preserve final answer before supervisor events
• address system prompt review findings
• preserve empty system prompt snapshots
• harden empty system prompt persistence tests
• add agent shell environment overrides closes #114
• show auth slash command by state closes #107
• cache auth slash command per slash session
• route detail expansion key
• keep compact detail expansion reachable
• limit compact detail dividers
• right-align detail expand markers
• keep compact detail markers width safe
• address compact detail review feedback
• preserve selection in detail alt screen
• focus visible detail item after scroll
• refine compact detail transcript rendering
• tune compact detail navigation
• polish compact detail spacing
• brighten developer context symbol
• polish status line
• center detail selection while scrolling
• cover center detail page scrolling
• clarify expandable detail items
• refine detail labels
• align detail labels and tests
• keep edge detail rows selectable
• move detail edge selection on wheel
• preserve live transcript compact metadata
• smooth detail reverse wheel selection
• avoid hiding top detail rows with spacer
• recenter detail edge selection before scrolling
• keep unknown developer entries detail-only
• preserve detail rows around edge spacer
• recenter detail edge reversal
• walk detail edge selection by line
• hold camera for off-center detail selection
• address stale detail review threads
• address rebase review comments
• use injected status collector on startup
• stabilize 1.0 session flows
• fold compaction notice into summary
• consolidate compaction transcript notice

Other

• update docs for phase 4
• cover registration fallback boundaries
• add transcript decision diagnostics
• cover sliding ongoing tail recovery
• avoid copying embedded test server locks
• share tool ids and patch transcript formatting
• enforce package architecture boundaries
• update docs
• cover startup binding failure states
• make project availability checks deterministic
• remove persisted request dedup storage
• consolidate sandbox and shared test utilities
• slim sandbox runtime image
• cover narrow server project notice layout
• format native scrollback integration test
• ignore legacy reviewer rollback in session view
• align serve startup copy assertion
• format runtime control replay fix
• Merge pull request #141 from respawn-app/network-stack-local-first
• Merge pull request #137 from respawn-app/phase-2-divergence-fixes
• Merge pull request #133 from respawn-app/phase-67
• Merge pull request #128 from respawn-app/phase-6-transcript-reliability
• Merge pull request #117 from respawn-app/phase-5-app-server
• Merge pull request #115 from respawn-app/phase-4-app-server
• update dependencies
• Merge pull request #142 from respawn-app/network-stack-local-first
• Merge pull request #125 from respawn-app/dependabot/github_actions/actions/github-script-9
• Merge pull request #124 from respawn-app/dependabot/github_actions/softprops/action-gh-release-3.0.0
• Merge pull request #123 from respawn-app/dependabot/github_actions/github-actions-non-major-77d500c670
• cover session retarget fallback and service
• reduce background and retry timing in runtime coverage
• gofmt runtime adapter test
• harden review regression coverage
• harden remote lagging subscriber assertions
• expect flush-left startup picker headings
• cover shared startup markdown margin
• Merge pull request #145 from respawn-app/pr-142-explicit-tcp-tail
• add worktree-mgmt prefabs
• remove multi_tool_use_parallel wrapper
• format go files
• update docs
• Merge pull request #147 from respawn-app/tokenoptimization-mvp
• Merge branch 'main' into wt-management
• Update .builder/skills/docs-writing/SKILL.md
• Update docs/src/content/docs/command-postprocessing.md
• Merge branch '1.0-fixes' into wt-management
• Merge pull request #148 from respawn-app/wt-management
• update tool defs
• cover worktree patch path rebinds
• Merge pull request #150 from respawn-app/1.0-fixes-2
• remove stale docs
• update system prompt for more frequent questions
• Merge pull request #151 from respawn-app/system-md-fixes
• Merge pull request #153 from respawn-app/agent-vars
• Merge pull request #154 from respawn-app/login-logout-107
• cover compact detail divider boundaries
• document right aligned detail markers
• Revert "test: document right aligned detail markers"
• Revert "fix: right-align detail expand markers"
• Revert "test: cover compact detail divider boundaries"
• Revert "fix: limit compact detail dividers"
• cover detail scroll focus through app
• remove flaky websocket unix timing test
• cover wheel detail edge selection
• cover wheel top-edge detail spacer
• pin bottom scrollback detail reversal
• Merge pull request #152 from respawn-app/detail-mode-v2
• clean up test suite
• update compaction notice replay expectations
• Merge pull request #155 from respawn-app/1.0

Docs

• refine prompt and repo guidance wording
• fix handoff prompt grammar
• lock direct-attach phase 4d topology
• lock nested workspace binding semantics
• archive phase 7 completion
• narrow phase 2 migration scope
• update migration and blocker plans
• reconcile migration plans and sandbox docs
• record reviewer family-fix workflow
• add events jsonl schema v2 proposal
• improve cli help and serve startup
• tighten public docs guidance
• update system prompt guidance
• clarify agent prompt guidance
• record compaction summary notice contract