RFC: explicit channel-scoped cwd for buzz-acp on local and remote runtimes
- Dominant language
- Rust
- Stars
- 32.7k
- Forks
- 4.3k
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 253
Description
**Motivation**
Managed agents currently have one process-wide working directory, normally the Buzz nest or an optional static workspace associated with the agent.
This does not work well when the same agent identity participates in channels for different repositories. Repository-specific instructions, skills, tools, and memory routing depend on the actual working directory being selected before the ACP adapter and session start.
The problem is not limited to agents managed by Buzz Desktop. A `buzz-acp` runtime may run on a laptop, a remote host, a container, or under another supervisor. Regardless of where the agent is created, the runtime needs a supported way to provide an explicit working directory instead of inheriting or assuming the Buzz nest.
A concrete use case is keeping a small set of stable managed identities, such as Claude, Codex, and OpenCode, and reusing them across many project channels. Creating one managed-agent identity per repository causes identity and configuration sprawl.
**Proposed solution**
Make `cwd` a first-class input to `buzz-acp`, usable by both Desktop-managed and independently supervised local or remote runtimes, and allow a channel or future project entity to bind to a logical repository or workspace identity.
The runtime executing `buzz-acp` should resolve that logical identity to an absolute path available in its own environment before creating or resuming the ACP session for that channel. For example, the same repository could resolve to `/Users/alice/src/project` on a laptop and `/srv/agents/repos/project` on a remote worker.
Expected properties:
- `buzz-acp` can always be started or instructed with an explicit workspace cwd, without depending on Buzz Desktop internals.
- One managed-agent identity can participate in channels backed by different workspaces.
- Each runtime resolves the portable workspace identity to its own local absolute path.
- The selected workspace becomes the real cwd before adapter and session initialization.
- Each `session/new` receives the resolved cwd rather than a process default or prompt-only hint.
- Implementations may use workspace-scoped workers keyed by `(agent, workspace)` when adapters require process-level cwd or initialization.
- Absolute filesystem paths remain local to the runtime and are never stored on the relay.
- The relay may store a portable repository identity, such as a normalized Git remote.
- Rebinding a channel invalidates its previous session.
- Missing, ambiguous, or deleted workspace mappings fail clearly instead of silently falling back to the Buzz nest.
- Existing Activity and agent identity remain consistent across workspace-scoped workers.
- Buzz does not automatically create, delete, or manage Git worktrees.
- Worker and session lifecycle remains bounded, considering the resource-growth problem described in #2961.
This could initially use a runtime-local channel-to-workspace mapping without requiring a full Project entity. A later Project model could provide the portable repository identity while each local or remote edge continues resolving its own path.
The exact transport for the cwd could be a CLI option, runtime config, or a session-routing API. The important behavior is that it is explicit, available outside Desktop, and applied before the adapter/session starts.
**Alternatives considered**
A static per-agent working directory, as proposed in #3364, is useful but requires duplicating every agent identity for every repository.
Prompt-only run options, as proposed in PR #3269, do not change the process or session cwd and therefore do not load repository-scoped configuration reliably.
The configurable `repos_dir` from PR #1194 exposes existing checkouts but does not select the correct checkout for a channel.
Maintaining a private Buzz fork is possible, but this functionality affects core desktop and ACP lifecycle behavior and would be better maintained upstream.
**Additional context**
No exact duplicate was found.
- #3364 explicitly defers automatic project/channel repository switching.
- PR #382 previously proposed the useful "Relay = WHAT, Edge = WHERE" model and local repository-path resolution, but was closed without merge.
- PR #3269 adds prompt-level repository targeting without changing cwd.
- PR #1194 adds the global repository collection directory.
- #2961 documents why workspace-scoped workers also need bounded lifecycle behavior.
The intent of this RFC is to get maintainer direction before any implementation or fork is started.
Contributor guide
Research direction
Read the existing buzz-acp runtime and ACP adapter/session initialization, then trace session/new and the relay/runtime boundary; the RFC names no source files or tests. Done means maintainers choose an explicit cwd transport and workspace-resolution design covering rebinding, clear mapping failures, local-path isolation, and bounded worker or session lifecycle.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- backend, distributed-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100