loklaan/dotfiles

Cross-platform dev environment, one script away.
Managed with chezmoi · versioned with mise · secrets via Bitwarden

---

A single install.sh bootstraps a complete development environment from a clean machine — shell, git, dev tools, secrets, and AI assistant configuration. Everything is templated, idempotent, and version-locked so the same setup reproduces identically across personal laptops, work machines, and ephemeral dev containers.

Chezmoi manages the file lifecycle: Go templates resolve per-machine configuration at apply time, externals pin plugin archives to exact versions, and numbered scripts handle post-install automation in dependency order. Secrets never touch the repo — Bitwarden Secrets Manager provides them at render time through a token-gated guard pattern that degrades gracefully when credentials aren't available.

System Model

This repository projects a portable desired-state model into a live user environment. It resolves machine-specific variation, reconciles file and operational state, and observes whether the machine has converged.

See the Dotfiles System Model for the concepts and invariants that should survive changes to the underlying tools.

Features

Install

Usage:
  install.sh [OPTIONS]

Description:
  Installs dotfiles and packages.

Environment Variables:
  DEBUG:                     Set to 1 to enable command tracing (set -x) in logs.
  CONFIG_BWS_ACCESS_TOKEN:   Optional. Bitwarden Secrets access token.
                             When empty, prompts interactively (or skips if non-TTY).
  CONFIG_SIGNING_KEY:        Optional. The primary key of the signing GPG keypair.
                             When empty, commit signing is disabled.
  CONFIG_GH_USER:            Dotfiles GitHub user. (default: loklaan)
  CONFIG_EMAIL:              Personal email for Git. (default: bunn@lochlan.io)
  CONFIG_EMAIL_WORK:         Work email for Git. (default: lochlan@canva.com)

Options:
  --help:                    Display this help message

Full Install

(inc. chezmoi, bitwarden, mise)

# Clone to chezmoi's source directory
git clone https://github.com/loklaan/dotfiles.git ~/.local/share/chezmoi

# Run install (will prompt for BWS token interactively)
~/.local/share/chezmoi/install.sh

# Or non-interactive (CI, Docker, etc.)
CONFIG_BWS_ACCESS_TOKEN=... CONFIG_SIGNING_KEY=... ~/.local/share/chezmoi/install.sh

Quick Install (curl)

curl -fsSL https://raw.githubusercontent.com/loklaan/dotfiles/main/install.sh | bash

Update to Latest

# Safe for re-runs, to keep devbox provisioning idempotent:
~/.local/share/chezmoi/install.sh

# Or:
chezmoi update

Testing the Install

Validate installation in a clean environment:

./install.test.sh

Runs end-to-end installation test in Docker (Alpine Linux) with dummy data from chezmoi.test.toml.

Secret Management

Secrets are stored in Bitwarden Secrets Manager and fetched at template render time. Each machine stores its BWS access token locally (~/.config/chezmoi/secrets/bws-access-token.txt, mode 0600). Templates read the token and call bitwardenSecrets to resolve secret values during chezmoi apply.

See .agents/rules/secrets-architecture.md for detailed architecture documentation.

Structure

home/
├── .chezmoiexternals/          # External deps (plugins, fonts) via archives
├── .chezmoiscripts/            # Pre & post-install automation scripts
├── dev/                        # Code projects
├── private_dot_config/
│   ├── private_zsh/            # Modular zsh configuration
│   │   ├── init/               # Startup modules (env, login, options, plugins, prompt)
│   │   └── plugins/            # Vendored plugin configs (starship, ghostty, clipboard)
│   └── ...                     # Other tool configs
└── private_dot_local/bin/      # Custom utilities

Code Agent Adoption

Claude Code and OpenCode share a vendor-neutral set of rules and Agent Skills under ~/.agents/, with vendor-specific paths (~/.claude/, ~/.config/opencode/) symlinking into it. Skills are auto-packed into zips for reuse in Claude Chat, and are designed to port cleanly across vendors.

Agent Orchestration

Agent sessions running across machines (macbooks + Coder dev boxes) are reached via three complementary tools: orca (desktop SSH client, auto-discovers Coder hosts from ~/.ssh/config), paseo (daemon-per-host on Coder boxes via systemd, desktop/mobile clients on macbooks), and openchamber (1:1 deep UI for a single local opencode). The paseo daemon is opt-in per machine via a chezmoi prompt — default off, real opt-out by reapplying with the flag flipped.

See .agents/rules/agent-orchestration.md for the network model, process model, server model, and operating runbook.

Code Projects

The ~/dev/ directory organizes projects by ownership and purpose:

• ~/dev/canva/ - Work projects—I work at Canva! Come join!
• ~/dev/me/ - Personal projects.
• ~/dev/open/ - Open source projects. Others, usually.

In repos where I actively develop, I may include a .me/ directory for helpful scripts, temporary data or jupyter notebooks, etc. These are not managed by chezmoi, and are gitignored globally.