Beads Management

Beads Management coordinates agent work by mission: one goal across the repositories it needs. Each mission has a Main (a Beads Manager), Workers in the relevant repositories, a Reviewer for larger changes, and an optional Orchestrator that governs the process at the autonomy level you choose. The dashboard provides Missions, an Inbox for decisions and alerts, Projects, Settings, and Tools & skills. Requires Paseo 0.9.0 or later on macOS or Linux.

Open Missions and choose New mission to name the goal, short code and repositories. Its Main works in a Mission-List project, with one workspace per mission, and assigns work to Workers in the selected repositories. Existing repository Managers are associated with one-repository missions during migration. Mission records, journals, shared project memory, traces and settings are stored on the daemon host. The plugin creates and labels its agent roles and mission workspaces.

Each mission gets its own branch and worktree for each repository when its first Worker starts there. Independent requests can use additional lanes, up to seven live lanes per mission and repository. When a lane finishes, the plugin fast-forwards the mission branch to it locally; if that branch moved, it first attempts a conflict-free merge into the lane and retries. Conflicts or overlapping uncommitted files leave the merge pending and notify the Main. A clean, completed lane can be reset to the mission branch for new work. These lane operations do not push to the forge. The repository’s own worktree setup takes precedence. Otherwise, when lockfiles match, the plugin attempts a copy-on-write clone of existing node_modules and .nx/cache; unsupported filesystems leave that preparation unfinished rather than copying or downloading dependencies. Closing a mission retires its worktrees and offers an archive card; archiving remains your action in Paseo.

For missions already using a shared checkout, a checkpoint card lets you save its current commits, uncommitted changes and untracked files on a separate local branch; ignored files stay out. This runs only when you choose the checkpoint option and leaves your working files, HEAD and normal Git index in place. Pushing and merging the checkpoint remain your responsibility. Review calls also write local Git tree objects from a temporary index to identify the reviewed state.

The mission page offers a standing integration permission for each mission and repository. Granting it allows Workers to push that mission branch to origin and open or update its merge request into the chosen integration branch. You can revoke it on the mission page; merging remains on the forge. These workflow rules do not sandbox agents.

Workers run without permission prompts by default (bypass mode on Claude, full access on Codex). Mains also select an available mode without permission prompts. Review changes before committing. Hold risky actions is off by default and can be enabled per project; the plugin’s policy checks are workflow guardrails, not an OS sandbox. Its local tool server uses role/agent bindings to coordinate agents. Allow agent tools is a separate, confirmed, machine-wide Paseo setting that applies to every agent.

The plugin reads project and agent metadata, timelines, repository state and its own workflow records. Mission Mains receive context across their selected repositories, and linked Workers exchange requests and replies through the plugin. This context reaches the selected agents’ model providers. The optional Orchestrator starts only when you start it, reads plugin project context with secrets masked, spends provider tokens, and coordinates process decisions. The governor also tracks mission thresholds and can send a nudge to its Main.

Dependent requests can wait in a stored queue until their prerequisite requests finish; the mission page shows lanes, overlaps and held work, with cancellation. Idle Mains with outdated role instructions are handed over to a successor automatically after an update, preserving their old conversations. A mission’s current Main can resolve delegated Worker or Reviewer provider failures using the configured recovery choices; owner-only decisions and effectful permissions retain their existing authority.

Memory and briefs distinguish mission context from lasting project rules, use bounded summaries, and leave retired facts out of current briefs. Main context compaction has a separate token threshold, defaulting to 150,000 tokens, as well as the configured window share.

Request-size thresholds can ask a Worker to finish and report remaining work, then create a continuation Worker with the prior report, open questions and links. Structural waits hold routine nudges until their dependency resolves. Review budgets use an owner decision when their cap is reached. Settings control these automation limits.

Setup on Tools & skills shows each operation and asks for confirmation before installing:

• Beads tools br and bv: Homebrew packages from dicklesworthstone/tap, or GitHub-hosted install scripts for Dicklesworthstone/beads_rust and Dicklesworthstone/beads_viewer when Homebrew is unavailable.
• Workflow skills: the third-party skills CLI fetched from npm downloads skills from github.com/cuongntr/agent-skills into Claude and Codex skills folders. That CLI has its own data-collection behavior.

The update screen checks npm for the latest package version and runs the Paseo plugin update command only after confirmation. Cleanup can remove the plugin’s role configuration and, when selected, its own saved data; it is separate from uninstalling the plugin.