Workspace Manager

An opinionated system for organizing workspaces and projects across machines.

Quick Start

# Clone this repo
git clone https://github.com/benlinton/workspace-manager.git
cd workspace-manager

# Set up config (choose one)
./bin/workspace config init                          # copy from example template
./bin/workspace config download <url>                # download a config file from a URL
./bin/workspace config clone git@github.com:you/workspace-config.git  # clone a private config repo

# Edit config with your repos and machine name
./bin/workspace config edit

# Preview what init would do without making changes
./bin/workspace init --dry-run

# Create directories and clone repos
./bin/workspace init

Example Layout

~/Workspace/
├── code/                    # All software projects, grouped by org
│   ├── personal/            #   Personal projects
│   ├── org-1/               #   Work projects for org-1
│   ├── org-2/               #   Work projects for org-2
│   ├── third-party/         #   Third-party repos for reference or contribution
│   └── experiments/         #   Prototypes, experiments, and labs
│
├── knowledge/               # PKM, reference material, and filed documents
│   ├── second-brain/        #   Primary personal knowledge management
│   ├── document-vault/      #   Document retreival system
│   ├── bytebytego/          #   Example system design reference (read-only)
│   └── ...                  #   Documents, guides, runbooks, courses, help, etc.
│
├── research/                # Single-use research, analysis, and intelligence gathering
│   ├── market-research/     #   Market research and analysis
│   └── ...                  #   Health analysis, business strategy, deep-dives, etc.
│
├── studio/                  # Creative production
│   ├── productions/         #   Video projects
│   ├── music/               #   Music library
│   ├── sound-effects/       #   Sound effect libraries
│   ├── design/              #   Standalone design work (logos, branding, UI mockups)
│   ├── video-editor/        #   Video editor media cache and proxies
│   └── ...                  #   Video plugins, LUTs, templates, stock footage, etc.
│
├── toolkits/                # AI tools, harnesses, plugins, and shared resources
│   ├── my-mcp-server/       #   Example: an MCP server you built
│   ├── shared-context/      #   Example: reusable context files
│   ├── constitution/        #   Example: a set of rules all AI agents must follow
│   ├── useful-tool/         #   Example: a third-party tool cloned from someone else
│   └── ...                  #   Whatever tools you need — no fixed set
│
└── dotfiles -> <symlinked dotfiles path> 

Commands

Command	Description
Config
workspace config init	Create config from example template
workspace config clone <url>	Clone a private config repo into config/
workspace config download <url>	Download a config.json from a URL
workspace config show	Print config.json to stdout (default)
workspace config edit	Open config.json in $EDITOR
workspace config path	Print config directory path
Workspace
workspace init	Create directory tree and clone repos (requires config)
workspace init --dry-run	Preview what init would do
workspace status	Show what exists and what's missing
workspace pull	Pull latest changes for all repos (excludes studio)
workspace pull <section>	Pull only repos in a specific section (code, research, knowledge, toolkits)
workspace validate	Validate config and check directory tree is in sync

Existing directories are skipped. Existing repos are not re-cloned. Studio projects are excluded from init and pull — they typically use Git LFS or cloud storage.

Configuration

Config lives in config/config.json (gitignored). See templates/config.example.json for the full schema.

[Expand Key Fields] 👈

Field	Description
machine	Name of this machine (used to look up per-machine settings); overridden by WORKSPACE_MACHINE env
workspace_root	Path to workspace root (default: ~/Workspace)
dotfiles	Path to your dotfiles directory (default: ~/.local/share/chezmoi)
bin_link	Optional path to symlink the workspace command (e.g., ~/.local/bin/workspace)
code.orgs	List of org directories to create under code/
code.repos / research.repos / knowledge.repos / toolkits.repos	Repos to clone, each with url and path
studio.categories	Subdirectories to create under studio/
machines.<name>.skip	Top-level directories to skip on this machine
machines.<name>.code_orgs	Limit which code orgs are set up on this machine

Multi-Machine Setup

This tool is very flexible when supporting multiple machine types.

[Expand Details] 👈

A single config.json holds settings for all your machines. The WORKSPACE_MACHINE variable tells the tool which machine it's running on, so it can apply the specific per-machine overrides.

Set the machine name by creating a .env file in the project root:

echo "WORKSPACE_MACHINE=macbook-personal" > .env

The tool checks .env first, then the WORKSPACE_MACHINE env var, then the machine field in config.json.

Managing your config — choose one:

1. Check in config.json — simplest option. Remove config/ from .gitignore and commit it. In this case, you'll likely want to make this forked repo private.

2. Clone a separate config repo — keeps your config private while this repo stays public.

   ./bin/workspace config clone git@github.com:you/workspace-config.git
   

   Simply add a single config.json to the separate repo.

3. Many config files — for advanced use cases.

   If you desire multiple configs (e.g. CONFIG_REPO/available/macbook-personal.json, CONFIG_REPO/available/macbook-work.json), follow Step 2 and then symlink the config you want (using relavite paths):

   ln -s available/macbook-personal.json config/config.json
   

Principles

Why the layout is structured this way — depth limits, portability, and grouping logic.

[Expand Details] 👈

Two levels to any project, three where it earns its keep

The target depth is Workspace/<grouping>/<project>/. The only exception is code/, which uses Workspace/code/<org>/<project>/ — the org layer drives context-switching efficiency and scopes tab-completion.

Path pattern	Depth	Why
code/<org>/<project>	3	Org grouping maps to how you switch between clients/employers
research/<project>	2	Flat — no sub-grouping needed
studio/<category> or studio/<category>/<project>	2–3	Categories organize by medium; some (productions/) have sub-projects
knowledge/<item>	2	Flat — PKM, reference material, and documents side by side
toolkits/<tool>	2	Flat — each entry is its own repo

Groupings are portable

Every top-level directory is activity-based and universal:

• code/ — present on every dev machine
• research/ — present wherever you do research and analysis
• studio/ — present on creative workstations
• toolkits/ — present wherever you use AI tools
• knowledge/ — present wherever you manage personal knowledge, reference material, or documents
• dotfiles — present wherever you manage system config

Only the contents inside code/ vary by machine (your work laptop might only have org-1/, your personal machine has personal/ + org-2/). The top-level structure is identical everywhere.

Groupings are by nature of work, not who it's for

The "who" (org) is a property of code projects and lives one level down inside code/. Everything else is grouped by what kind of work it is.

Conventions

Per-directory rules for what goes where and how each section is used.

[Expand Details] 👈

code/

• Organized by org/context. New repos go under the appropriate org directory.
• third-party/ repos sit flat — no sub-grouping by contribution vs reference.
• experiments/ is for prototypes and experiments. When one graduates, move it to the appropriate org. When one dies, delete it.
• AI tool source code is developed here like any other project. When ready for consumption, tools are published as standalone repos and cloned into toolkits/.

research/

• Each subdirectory is a focused research or analysis project.
• These are non-code projects: tax analysis, health research, business strategy, data synthesis, multi-step investigations.
• The work involves gathering data, scraping, synthesizing, finding insights, and making sense of documents.
• Many of these are Claude Code working directories — the project structure is whatever the work requires.

studio/

• Organized by medium/category at the first level.
• productions/ contains named video projects (e.g., my-film-2026/).
• design/ is for standalone design work not tied to a specific production.
• Production-related design assets stay with their production, not in design/.
• video-editor/ holds video editor media cache and proxies.
• Studio projects are not auto-cloned by the workspace script — they typically use Git LFS, cloud storage, or manual backup due to large binary assets.

knowledge/

• Everything you know, have learned, or have on file — flat, with names that do the work.
• Entries can be git repos, document stores, synced folders, or any other format.
• PKM vaults, reference material, context libraries, filed documents — all live here as peers.
• The distinction between types is obvious from the item name — no subdirectory wrappers needed.
• Not for active development — if you start contributing significantly to a reference repo, move it to code/third-party/.

toolkits/

• A growing library of AI tools, harnesses, plugins, and shared resources consumed by projects across the workspace.
• Each entry is its own git repo — a mix of your own published tools and third-party tools cloned from others.
• Your own tools are developed in code/, published as standalone repos, then cloned here. Third-party tools are cloned directly.
• Projects reference tools by path (e.g., @path imports, .mcp.json entries, hook paths in settings).
• This directory grows as your AI tooling needs evolve — there's no fixed set of categories.

dotfiles

• Symlink to your dotfiles directory, configured via dotfiles in config.json.
• Defaults to ~/.local/share/chezmoi if not set.
• Works with any dotfiles manager (chezmoi, yadm, bare git repo, etc.).

Additional Docs

• workspace-design — Design principles and rationale
• ai-tooling — AI tool integration and toolkits
• sync-workflow — Multi-machine sync strategy

License

MIT