Declarative dotfiles manager built on the Vorpal build system. Instead of shell scripts or symlink managers, the entire development environment -- CLI tools, configuration files, themes, and symlinks -- is defined as a Rust program that produces reproducible, content-addressed artifacts.
This project also defines a Claude Code agent team configuration with agent personas, skills, and orchestration workflows that are deployed alongside the dotfiles.
The project produces two top-level artifacts:
dev-- Development toolchain (Protoc and Rust toolchain) used to build the project itself.user-- Full user environment containing all CLI tools, configurations, and filesystem symlinks.
When you run vorpal build 'user', Vorpal builds artifacts into /var/lib/vorpal/store/ and creates symlinks from the home directory into the store.
The user environment includes 16 CLI tools managed as Vorpal artifacts:
| Tool | Description |
|---|---|
| awscli2 | AWS command-line interface |
| bat | Syntax-highlighted cat replacement |
| direnv | Per-directory environment variables |
| doppler | Secrets management |
| fd | Fast file finder |
| gh | GitHub CLI |
| git | Version control |
| gopls | Go language server |
| jj | Git-compatible VCS |
| jq | JSON processor |
| k9s | Kubernetes terminal UI |
| kubectl | Kubernetes CLI |
| lazygit | Terminal UI for git |
| nnn | Terminal file manager |
| ripgrep | Fast recursive search |
| tmux | Terminal multiplexer |
Each tool configuration is defined as a builder struct in Rust:
- BatConfig -- Bat theme and settings (plain-text config)
- ClaudeCode -- Claude Code
settings.jsonwith permissions, MCP servers, hooks, and plugins - GhosttyConfig -- Ghostty terminal emulator settings (key-value config)
- K9sSkin -- K9s Kubernetes UI skin (Tokyo Night theme, YAML)
- Opencode -- OpenCode AI tool settings with keybinds, LSP, agents, and themes (JSON)
- statusline.sh -- Bash script for Claude Code status bar with model, git, and cost info
The project deploys a five-agent Claude Code development team to ~/.claude/agents/:
| Agent | Role |
|---|---|
| Staff Engineer | Architecture, technical design documents, code review |
| Senior Engineer | Implementation, code quality, debugging |
| Project Manager | Issue planning, task breakdown, dependency management |
| SDET | Test infrastructure, automation, quality engineering, verification |
| UX Designer | User experience design specs |
Four skills orchestrate the team:
| Skill | Location | Purpose |
|---|---|---|
| dev | skills/dev/ |
Coordinates all five agents for planning and executing development work |
| specs | skills/specs/ |
Bootstraps docs/spec/ project specifications for new repositories |
| evolve-agents | .claude/skills/evolve-agents/ |
Reviews and improves agent definitions in agents/*.md |
| evolve-skills | .claude/skills/evolve-skills/ |
Reviews and improves skill definitions across the skill ecosystem |
The build creates the following symlinks on the host filesystem:
| Source (Vorpal store) | Target |
|---|---|
| bat config | ~/.config/bat/config |
| bat Tokyo Night theme | ~/.config/bat/themes/tokyonight.tmTheme |
| Claude Code settings | ~/.claude/settings.json |
| Agent definitions | ~/.claude/agents/ |
| Skill definitions | ~/.claude/skills/ |
| Status line script | ~/.claude/statusline.sh |
| Ghostty config | ~/Library/Application Support/com.mitchellh.ghostty/config |
| K9s skin | ~/Library/Application Support/k9s/skins/tokyo_night.yaml |
| Neovim markdown ftplugin | ~/.config/nvim/after/ftplugin/markdown.vim |
| OpenCode config | ~/.config/opencode/opencode.json |
| Vorpal binary | ~/.vorpal/bin/vorpal |
- Vorpal runtime installed on the host system
- macOS on Apple Silicon (aarch64-darwin) -- the primary supported platform
Build the development toolchain first, then the user environment:
vorpal build 'dev'
vorpal build 'user'The build system uses S3-backed remote caching (altf4llc-vorpal-registry) for artifact storage. Configure AWS credentials for remote cache access.
GitHub Actions (.github/workflows/vorpal.yaml) runs on every push to main and on pull requests:
- build-dev -- Builds the
devartifact and uploadsVorpal.lock. - build -- Builds the
userartifact (depends onbuild-dev).
Both jobs run on macos-latest using setup-vorpal-action.
| Dependency | Purpose |
|---|---|
| vorpal-sdk | Core Vorpal SDK (context, artifacts, environment types) |
| vorpal-artifacts | Pre-built artifact types for common CLI tools |
| anyhow | Error handling |
| indoc | Indented string literals for config templates |
| serde + serde_json | JSON serialization |
| tokio | Async runtime |
Dependency updates are managed by Renovate with auto-merge for minor and patch updates on stable crates.