Blackdot: A Development Framework Built for Claude Code and Modern Development

Start on Mac, continue on Linux, same Claude conversation.

That’s how this started.

I solved it with a simple /workspace → ~/workspace symlink so Claude sees the same absolute path everywhere.

But the real outcome wasn’t just portability. It was a new way to treat configuration as a framework–Blackdot: a feature registry, multi-vault secrets, layered configuration, and an extensible hook system–all fully opt-in, with no need to fork the core.

This works great on a single Linux machine too. The framework’s modularity, vault system, hooks, and dev tool integrations stand on their own.

The Problem That Started It

I use Claude Code across three machines: Mac laptop, Lima VM, and WSL2. Claude stores sessions by working directory path. /Users/me/api on Mac and /home/me/api on Linux are different sessions–different paths mean lost conversation history.

I found this article about migrating Claude sessions and started writing path rewriting scripts. After a few hours, I realized there was a simpler way.

The Solution: Root-Level Symlink

1

/workspace -> ~/workspace

Now /workspace/api resolves correctly on every machine, but Claude sees the same absolute path. Same path = same session folder = conversation continues.

1
2
3
4
5
6
7

# Mac
cd /workspace/api && claude
# ... work for an hour, Claude learns your codebase ...

# Later, Linux VM - SAME conversation
cd /workspace/api && claude
# Full history intact. No sync. No export.

From a Portability Hack to a Framework

The /workspace trick solved a real problem. The bigger discovery was that configuration can be a control plane: features, hooks, layered config, and vault-backed state–without forks.

That solved Claude portability. But while building this, I needed:

• Secrets synced without storing in git (SSH keys, AWS credentials)
• Shell config that didn’t break when switching contexts
• Developer tools (AWS, Rust, Go, Python) with consistent aliases
• Health checks to catch broken configs
• Extensibility without editing core code

That became a framework.

The Control Plane: Features + Hooks + Layers

Everything optional is a feature. Enable what you need, skip what you don’t.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# See what's available
blackdot features

# Enable specific features
blackdot features enable vault --persist
blackdot features enable aws_helpers

# Apply presets for common setups
blackdot features preset claude      # Claude-optimized
blackdot features preset developer   # Full dev stack
blackdot features preset minimal     # Shell only

Feature Categories

Core (always enabled):

• Shell configuration (ZSH, prompt, core aliases)

Optional (framework capabilities):

• workspace_symlink - /workspace for portable Claude sessions
• claude_integration - Claude Code hooks and settings
• vault - Multi-vault secrets (Bitwarden/1Password/pass)
• templates - Machine-specific configs with filters
• hooks - Lifecycle event system (multiple trigger points)
• config_layers - Hierarchical config (env > project > machine > user)
• drift_check - Detect unsync’d changes before overwriting
• backup_auto - Automatic backups before destructive ops

Integrations (developer tools):

• aws_helpers - AWS SSO profiles, helpers, tab completion
• cdk_tools - AWS CDK aliases and environment management
• rust_tools - Cargo aliases, clippy, watch, coverage
• go_tools - Go build/test/lint helpers
• python_tools - uv integration, pytest aliases, auto-venv
• nvm_integration - Lazy-loaded Node.js version management
• sdkman_integration - Java/Gradle/Kotlin version management
• modern_cli - eza, bat, ripgrep, fzf, zoxide

Dependencies auto-resolve. Enable claude_integration and it enables workspace_symlink automatically.

Hook System: Opt-In Automation

Hooks are opt-in automation, not hidden magic. You can list, validate, and run each hook manually.

The hook system triggers custom scripts at multiple lifecycle points:

1
2
3
4
5
6
7
8
9

# Available hooks
shell_init             # Shell starts
directory_change       # cd into directory
pre_vault_pull         # Before pulling secrets
post_vault_pull        # After pulling secrets
pre_vault_push         # Before pushing secrets
post_vault_push        # After pushing secrets
doctor_check           # Health validation runs
pre_uninstall          # Before uninstalling

Example: Auto-activate Python venv on cd

1
2
3
4

# hooks/10-python-venv.sh
if [[ -f .venv/bin/activate ]]; then
    source .venv/bin/activate
fi

Hooks auto-discover from ~/hooks/ and .blackdot-hooks/ in project directories. Priority-based execution (00-99, lower runs first).

1
2
3

blackdot hook list                    # Show all hooks
blackdot hook run directory_change    # Test hook manually
blackdot hook validate                # Validate all hook scripts

No core file edits needed. Drop scripts in hooks/, they run automatically.

Configuration Layers

Hierarchical config resolution with 5 layers:

1
2
3
4
5
6
7
8
9

# Precedence: env > project > machine > user > defaults
export BLACKDOT_VAULT_BACKEND=bitwarden   # env layer
echo '{"vault":{"backend":"pass"}}' > .blackdot.json  # project layer

blackdot config get vault.backend
# → bitwarden (env wins)

blackdot config show vault.backend
# Shows all layers and which one is active

Project configs (.blackdot.json) travel with repos. Machine configs (~/.config/blackdot/machine.json) stay local.

Optional Integrations: AWS/Rust/Go/Python

The framework includes dozens of curated aliases and helpers for common development workflows. All tools are optional integrations–enable only what you use.

AWS & CDK

1
2
3
4
5
6
7
8
9

# AWS SSO with tab completion
awslogin <TAB>         # Shows available profiles
awsset production

# CDK shortcuts
cdkd                   # cdk deploy
cdks                   # cdk synth
cdkdf                  # cdk diff
cdkhotswap api-stack   # Deploy with hotswap

Rust Development

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Cargo shortcuts
cb                     # cargo build
cr                     # cargo run
ct                     # cargo test
cc                     # cargo check
cw                     # cargo watch -x check

# Helpers
rust-new my-project    # Scaffold new project
rust-lint              # Run clippy with strict settings

Go Development

1
2
3
4
5
6
7
8
9

# Go shortcuts
gob                    # go build ./...
got                    # go test ./...
gof                    # go fmt ./...
gocover                # Run tests with coverage report

# Helpers
go-new my-api          # Scaffold new project
go-lint                # Run golangci-lint

Python with uv

Built on uv for fast Python package management.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# uv shortcuts
uvs                    # uv sync
uvr script.py          # uv run
uva package            # uv add
pt                     # pytest
ptc                    # pytest with coverage

# Auto-venv activation
cd my-project          # Prompts: "Activate .venv? [Y/n]"
# Configurable: notify/auto/off

Vault System: Multi-Backend Secrets

Your SSH keys already live in your password manager. Use them directly.

1
2
3
4
5
6
7

# Choose your backend
blackdot setup          # Wizard detects Bitwarden/1Password/pass

# Sync secrets
blackdot vault pull     # Pull from vault to filesystem
blackdot vault push     # Push local changes to vault
blackdot vault sync     # Bidirectional sync with drift detection

Drift detection warns before overwriting:

⚠ Drift detected:
  • SSH-GitHub-Personal
    Vault:  SHA256:abc...
    Local:  SHA256:def...

Overwrite local with vault? [y/N]:

Secrets never touch git. The vault system uses your existing password manager.

Setup Wizard

The current wizard flow walks through 7 steps:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

$ curl -fsSL https://raw.githubusercontent.com/blackwell-systems/blackdot/main/install.sh | bash
$ blackdot setup

    ____  __           __       __      __
   / __ )/ /___ ______/ /______/ /___  / /_
  / __  / / __ `/ ___/ //_/ __  / __ \/ __/
 / /_/ / / /_/ / /__/ ,< / /_/ / /_/ / /_
/_____/_/\__,_/\___/_/|_|\__,_/\____/\__/

              Setup Wizard

Current Status:
───────────────
  [ ] Workspace  (Workspace directory)
  [ ] Symlinks   (Shell config linked)
  [ ] Packages   (Homebrew packages)
  [ ] Vault      (Vault backend)
  [ ] Secrets    (SSH keys, AWS, Git)
  [ ] Claude     (Claude Code integration)
  [ ] Templates  (Machine-specific configs)

╔═══════════════════════════════════════════════════════════════╗
║ Step 1 of 7: Workspace
╠═══════════════════════════════════════════════════════════════╣
║ ███░░░░░░░░░░░░░░░░ 14%
╚═══════════════════════════════════════════════════════════════╝

Configure workspace directory for portable Claude sessions.
Default: ~/workspace (symlinked from /workspace)

Use default? [Y/n]:

Each step is optional. Exit anytime, resume later with blackdot setup.

Package Tiers

Choose your installation size:

The wizard presents this interactively. Your choice persists in config.

Modular Shell Config

Instead of one 1000-line .zshrc, there are modular files in zsh.d/:

zsh/zsh.d/
├── 00-init.zsh           # Core initialization
├── 10-environment.zsh    # ENV vars
├── 20-history.zsh        # History config
├── 30-completion.zsh     # Tab completion
├── 40-aliases.zsh        # Aliases
├── 50-aws.zsh           # AWS helpers (if aws_helpers enabled)
├── 51-rust.zsh          # Rust tools (if rust_tools enabled)
└── 90-hooks.zsh          # Hook system integration

Each module handles one thing. Disable per-machine by symlinking to .skip:

1

ln -s 50-aws.zsh 50-aws.zsh.skip    # Skip AWS module

Modules load in order (00-99). Feature guards prevent loading disabled integrations.

What Makes This Different

Most dotfiles: Configuration files + install script.

Blackdot:

• Feature Registry - Modular control plane for all optional components
• Hook System - Extensible automation at multiple lifecycle points
• Multi-Vault - Unified API for Bitwarden/1Password/pass
• Developer Tools - Integrated AWS/Rust/Go/Python with curated aliases
• Configuration Layers - Hierarchical resolution (env > project > machine)
• Drift Detection - Warns before overwriting unsync’d changes
• Template Filters - {{ var | upper }} pipeline transformations
• Health Checks - Validates everything, auto-fixes common issues
• Claude Portability - /workspace symlink for session sync

Designed for developers who want consistency and control.

Integration with dotclaude

dotclaude and blackdot are independent. They integrate cleanly through shared assumptions like /workspace and feature gating, but neither requires the other.

• dotclaude - Manages Claude configuration (CLAUDE.md, agents, settings)
• blackdot - Manages secrets, shell, and development environment

Both respect /workspace for portable sessions. Switch Claude contexts with dotclaude while secrets stay synced via blackdot vault.

Who This Is For

This framework works best if you:

• Want a modular dotfiles system you can grow over time
• Prefer opt-in features instead of monolithic installs
• Need vault-backed secrets without committing anything to git
• Like automation you can understand and control (hooks + doctor)
• Use AWS/Rust/Go/Python and want consistent helpers

If you also use Claude Code or work across machines, the /workspace portability becomes a genuinely great bonus.

If you don’t use Claude or don’t switch machines, you still get a clean feature registry, hooks, vault-backed secrets, and layered config.

Try Before You Trust

Test in a disposable container first (if you publish the lite image):

1
2
3
4

docker run -it --rm ghcr.io/blackwell-systems/blackdot-lite
blackdot status    # Poke around safely
blackdot doctor    # See health checks
exit               # Container vanishes

30-second verification before running on your real machine.

Get Started

1
2
3
4
5
6
7
8
9

# Full install (recommended for Claude Code users)
curl -fsSL https://raw.githubusercontent.com/blackwell-systems/blackdot/main/install.sh | bash
blackdot setup

# Minimal install (shell config only, add features later)
curl -fsSL https://raw.githubusercontent.com/blackwell-systems/blackdot/main/install.sh | bash -s -- --minimal

# Custom workspace location
WORKSPACE_TARGET=~/code curl -fsSL https://raw.githubusercontent.com/blackwell-systems/blackdot/main/install.sh | bash

The wizard detects your platform, finds available vault CLIs, and prompts for choices. Takes ~2–10 minutes depending on tier selection.

Started minimal? Add features later:

1
2
3
4

blackdot features enable vault --persist        # Enable vault
blackdot features enable rust_tools --persist   # Enable Rust tools
blackdot features preset developer              # Enable full dev stack
blackdot setup                                  # Re-run wizard for vault setup

Full documentation at blackwell-systems.github.io/blackdot .

Code: github.com/blackwell-systems/blackdot Docs: blackwell-systems.github.io/blackdot Changelog: CHANGELOG.md License: MIT