Blackdot is a modular CLI tool designed to simplify developer environment management by automating configuration, secrets storage, and tool integration across platforms. Offering multi-vault secrets synchronization (Bitwarden, 1Password, pass), extensible hooks for custom workflows, feature flags for runtime control, shell integration (Zsh, PowerShell), and health checks for system validation, Blackdot ensures consistent development setups.
Ideal for developers seeking a unified solution to manage their environments and sensitive data, Blackdot supports macOS, Linux, Windows, WSL2, and Docker. It enables seamless configuration of tools like AWS, Docker, Go, Rust, Python, SSH, NVM, and SDKMAN, with optional package tiers (minimal, enhanced, full) via Homebrew or winget. The tool’s feature registry allows users to enable or disable capabilities at runtime, while its self-healing mechanisms ensure system integrity.
Blackdot integrates with Claude Code for portable development sessions and provides templates for machine-specific configurations, ensuring consistent workflows across devices. With a focus on automation and security, it streamlines developer productivity by eliminating manual setup and configuration tasks.
README
Blackdot
Your secrets, shell config, and dev environment follow you to any machine with one command.
Blackdot is a dotfiles framework built in Go. It manages shell configuration, secrets (via Bitwarden, 1Password, or pass), developer tool setup, and Claude Code integration across macOS, Linux, Windows, WSL2, and Docker.
# macOS / Linux / WSL
curl -fsSL https://raw.githubusercontent.com/blackwell-systems/blackdot/main/install.sh | bash
# Windows (PowerShell)
irm https://raw.githubusercontent.com/blackwell-systems/blackdot/main/install-windows.ps1 | iex
Shell — Zsh with Powerlevel10k, modular config (zsh.d/), 90+ aliases. PowerShell module on Windows.
Secrets — Unified API across Bitwarden, 1Password, and pass. Bidirectional sync, drift detection, schema validation. Your SSH keys, AWS creds, and git config restore on any new machine in seconds.
Developer tools — AWS, Docker, Go, Rust, Python, SSH, NVM, SDKMAN integrations with deep shell support — not just aliases, but completions, helpers, and workflow automation. Three package tiers (minimal/enhanced/full) via Homebrew or winget.
Claude Code + dotclaude — Portable sessions via /workspace symlink so conversations persist across machines. Profile sync for work/personal/client contexts. Git safety hooks that block push --force and reset --hard before they run. Full Claude Code guide
Feature registry — Central control plane. Enable/disable any capability at runtime. Four presets (minimal, developer, claude, full) with dependency resolution. Feature docs
Self-healing — blackdot doctor --fix validates your setup and auto-repairs common issues. Drift detection compares local state against your vault.
blackdot features # See what's enabled
blackdot features preset developer # Enable developer tools
blackdot vault pull # Restore secrets from vault
blackdot doctor # Health check + auto-fix
blackdot status # Visual dashboard
Setup Wizard
The installer walks you through seven steps. Progress is saved — exit anytime and resume with blackdot setup.
╔═══════════════════════════════════════════════════════════════╗
║ Step 3 of 7: Packages
╠═══════════════════════════════════════════════════════════════╣
║ ████████░░░░░░░░░░░░ 43%
╚═══════════════════════════════════════════════════════════════╝
Which package tier would you like?
1) minimal 17 packages (~2 min) # Essentials only
2) enhanced 42 packages (~5 min) # Modern tools ← RECOMMENDED
3) full 50 packages (~10 min) # Everything (Docker, etc.)
The Go binary (blackdot) is the core. Shell modules in zsh.d/ call back into it for feature checks. Config resolves through 5 layers: environment > project > machine > user > defaults.
blackdot features preset minimal # Shell only
blackdot features preset developer # + vault, tools, git hooks
blackdot features preset claude # + portable sessions, dotclaude
blackdot features preset full # Everything
vs chezmoi, holman, thoughtbot, and other dotfiles managers
vs chezmoi
chezmoi is the most popular dotfiles manager and excellent at file-based config management. Blackdot takes a different approach — it's an application framework, not a file syncer:
Blackdot
chezmoi
Core model
Feature registry + vault sync
Template-based file management
Secrets
Unified API across 3 vault backends
External tool integration
Sync direction
Bidirectional (local ↔ vault)
One-way (template → target)
Configuration
5-layer priority resolution
Single config file
Health checks
doctor --fix with auto-repair
doctor (diagnostic only)
AI integration
Claude Code sessions + dotclaude
None
Learning curve
CLI commands
YAML + Go templates
vs traditional dotfiles repos
Traditional repos are collections of config files with a bootstrap script. Blackdot adds structure on top: a feature registry, vault-backed secrets, health checks, drift detection, and a CLI that ties it all together. The tradeoff is complexity — if you just want to symlink some rc files, a simple repo is fine.
Blackdot is worth it when you:
Manage secrets across multiple machines
Want to enable/disable capabilities without editing files
