ws-git-protect

bworkspace

Claude Code multi-project workspace launcher with custom prompts and isolated worktrees.

git clone https://github.com/btimothy-har/bworkspace.git
cd bworkspace && uv run install.py
ws setup
ws start workspace

Why bworkspace?

When working with Claude Code across multiple projects, you face friction:

• Scattered context — Each project needs different prompts, working styles, and domain knowledge
• Branch conflicts — Parallel conversations on the same repo compete for the working directory
• Repetitive setup — Re-configuring directories and prompts for each session

bworkspace solves this with a single command that:

1. Replaces Claude's default system prompt — Full control over behavior, consistency across sessions, tailored to your workflow (Claude Code still appends its tool definitions)
2. Configures project context — Loads project-specific prompts and working styles automatically
3. Supports isolated worktrees — Use -l <label> to work in a labeled worktree for parallel conversations
4. Manages multi-repo projects — Groups related repositories under one project definition

Features

Multi-Project Management

Define projects in ~/.bworkspace/projects.json with their directories, descriptions, and working styles. Launch any project with ws start <project>.

{
  "my-project": {
    "dirs": ["GitHub/my-project", "GitHub/my-project-docs"],
    "description": "My awesome project",
    "working_style": "engineering"
  }
}

Custom Prompts

Layer prompts for different contexts:

Layer	Purpose
Environment	CLI context, Python/uv usage, workspace paths
Core	Working principles, task management, tool usage
Working Style	Role definition, communication style, code quality practices
Project Context	Domain knowledge, project-specific patterns

Git Worktree Isolation

Use -l <label> to work in an isolated worktree:

ws start myproject -l auth      # Create or re-enter "auth" worktree
ws start myproject -l bugfix    # Create or re-enter "bugfix" worktree

Worktrees live in ~/.worktrees/<repo>/<label>/ with branches named wt/<label>.

Installation

Requires uv and Claude Code.

git clone https://github.com/btimothy-har/bworkspace.git
cd bworkspace
uv run install.py           # interactive (prompts for editable mode)
uv run install.py -e        # editable (recommended for development)
uv run install.py --no-editable

This installs two tools (ws and observer) and saves the workspace directory to ~/.bworkspace/config.json.

Then initialize the environment:

ws setup                     # check prerequisites, scaffold dirs, create default config

If ws or observer aren't in your PATH:

export PATH="$HOME/.local/bin:$PATH"

Upgrading

uv tool upgrade ws-core && uv tool upgrade observer

Uninstalling

uv tool uninstall ws-core && uv tool uninstall observer

Usage

Launching Projects

ws start <project>                # Start in project directory
ws start <project> --resume       # Resume previous conversation (-r)
ws start <project> -l <label>     # Work in labeled worktree (creates if new)

Opening in VS Code

ws open <project>                  # Open bworkspace + project directories
ws open <project> -n               # Open in new window
ws open <project> -l <label>       # Open in existing worktree

Managing Worktrees

ws worktree list <project>         # List worktrees for project
ws worktree list --all             # List all worktrees (-a)
ws worktree clean <project>        # Interactive cleanup
ws worktree clean <project> <name> # Remove specific worktree
ws worktree clean <project> --all  # Remove all worktrees
ws worktree clean <project> -f     # Force removal (--force)

Listing Projects

ws projects                        # Show available projects

Configuration

Projects are defined in ~/.bworkspace/projects.json:

{
  "web-app": {
    "dirs": ["GitHub/web-app"],
    "description": "Main web application",
    "working_style": "engineering"
  },
  "data-pipeline": {
    "dirs": ["GitHub/pipeline", "GitHub/pipeline-config"],
    "description": "ETL pipeline and configuration",
    "working_style": "engineering",
    "context": "pipeline"
  }
}

Field	Required	Description
dirs	Yes	Paths relative to $HOME. First is primary (cwd), rest are --add-dir
description	No	Shown in ws projects list
working_style	No	Loads ~/.bworkspace/prompts/working_styles/{name}.md (user override) or package default
context	No	Loads ~/.bworkspace/prompts/context/{name}.md for project context

Prompt System