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 seven-agent Claude Code development team to ~/.claude/agents/:
| Agent | Role |
|---|---|
| Team Lead | Orchestrates the other agents through plan/implement/review/verify cycles |
| Staff Engineer | Architecture, technical design documents, code review |
| Senior Engineer | Implementation, code quality, debugging |
| Project Manager | Issue planning, task breakdown, dependency management |
| Security Engineer | Security review, threat modeling, trust-boundary analysis |
| SDET | Test infrastructure, automation, quality engineering, verification |
| UX Designer | User experience design specs |
Skills support the team:
| Skill | Location | Purpose |
|---|---|---|
| adr | src/user/claude-code/skills/adr/ |
Authors an Architecture Decision Record as a Docket doc |
| code-review-verdict | src/user/claude-code/skills/code-review-verdict/ |
Conducts a scoped code review (general 6-dimension or security playbook) |
| design-qa | src/user/claude-code/skills/design-qa/ |
Post-implementation QA of a shipped UX surface against its spec |
| design-review | src/user/claude-code/skills/design-review/ |
Peer design review of a UX spec across six dimensions |
| init-specs | src/user/claude-code/skills/init-specs/ |
Bootstraps docs/spec/ project specifications for new repositories |
| prd | src/user/claude-code/skills/prd/ |
Authors a Product Requirements Document as a Docket doc |
| simplify-scout | src/user/claude-code/skills/simplify-scout/ |
Scouts code for simplification/refactor opportunities (report-only) |
| tdd | src/user/claude-code/skills/tdd/ |
Authors a Technical Design Document as a Docket doc |
| ux-spec | src/user/claude-code/skills/ux-spec/ |
Authors a UX design spec as a Docket doc |
| verify-ac | src/user/claude-code/skills/verify-ac/ |
Verifies a Docket issue's acceptance criteria against the diff |
| vote | src/user/claude-code/skills/vote/ |
Multi-agent consensus voting protocol |
| evolve-agents | .claude/skills/evolve-agents/ |
Reviews and improves agent definitions in src/user/claude-code/agents/*.md |
| evolve-skills | .claude/skills/evolve-skills/ |
Reviews and improves skill definitions across the skill ecosystem |
| evolve-coherence | .claude/skills/evolve-coherence/ |
Audits agent↔skill coherence across four dimensions and routes fixes to evolve-agents/evolve-skills (report-and-route; never edits files) |
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.