dotfiles

Personal dotfiles for automated development environment setup in GitHub Codespaces.

What's included

• Claude Code - AI-powered development assistant
• Codex CLI - OpenAI's standalone agent CLI, installed alongside Claude (separate infra and auth)
• MCP Server Support - Puppeteer for browser automation (screenshots, web scraping, testing)
• WireGuard VPN - On-demand VPN access from Codespaces (requires WIREGUARD_CONFIG secret)
• Automated installation and optional authentication scripts with error handling
• Custom skills symlinked from echo repo
• Claude Code plugins - installed and enabled automatically (e.g. Slack, frontend-design); MCP-backed plugins still need a one-time OAuth per Codespace
• Plan mode enabled by default
• .claude-docs/ directory for Claude-accessible scripts and documentation

Files

• install.sh - Main setup script, creates .claude-docs/ directories
• scripts/install-claude.sh - Claude Code installer with verification and authentication
• scripts/install-codex.sh - Codex CLI installer (native installer + auth-mode detection)
• scripts/install-wireguard.sh - WireGuard VPN installer, loads config from Codespace secret
• scripts/check-permissions.sh - Stop hook: surfaces local allow rules to promote to global
• scripts/session-start.sh - SessionStart hook: prompts Claude to offer /echo at session start
• scripts/copy-memory.sh - PostToolUse hook: copies memory files to .claude-docs/memory/ for visibility
• scripts/test.sh - Test suite for verifying setup
• .claude-docs/ - Git-ignored directory for Claude-generated documentation and plans

Setup

To use these dotfiles with GitHub Codespaces, follow the official dotfiles setup guide.

Authentication

Manual Login (Recommended)

No setup required - just run claude and login when prompted. Takes ~30 seconds per new Codespace.

This is the simplest and most cost-effective approach, using your existing Claude.ai Pro subscription.

Alternative: API Key

For automated workflows or if you prefer zero-friction setup, set ANTHROPIC_API_KEY as a Codespace secret:

• Get your API key from https://console.anthropic.com/settings/keys
• Note: API usage is significantly more expensive than a Claude.ai Pro subscription for heavy use

Codex CLI

OpenAI's Codex CLI is installed on every Codespace startup by scripts/install-codex.sh, using the native installer (binary lands in ~/.local/bin). It's a standalone agent — separate infrastructure, config (~/.codex/), and auth from Claude. Launch it with codex, just like claude.

Authentication — ChatGPT subscription (not API billing):

The installer pins Codex to subscription auth by writing forced_login_method = "chatgpt" to ~/.codex/config.toml (idempotent — never clobbers an existing config). To sign in on a new Codespace:

codex login --device-auth   # paste the code shown; ~30s, one-time per Codespace

--device-auth uses a device-code flow, so it works headlessly with no port forwarding. Login is cached in ~/.codex/auth.json.

Avoid setting OPENAI_API_KEY. Codespaces injects secrets as env vars, and a present key steers Codex toward usage-based API billing. forced_login_method=chatgpt guards against this, but for clean subscription use, don't set that secret.

Claude does not invoke Codex automatically. There is no Bash(codex:*) allow rule, so any codex command Claude attempts (e.g. via a /consult-style second opinion) prompts for approval first — keeping cross-agent calls visible.

Custom Skills

Custom skills live in the echo repo under commands/. At install time, dotfiles clones echo to ~/.echo and symlinks command files into ~/.claude/commands/.

Requires: ECHO_REPO codespace secret set to the echo repo clone URL (e.g., https://github.com/mxstrand/echo).

See the echo repo for the full list of available skills.

Plugins

Claude Code plugins are installed non-interactively during setup by install-claude.sh:

• enabledPlugins in ~/.claude/settings.json turns each plugin on.
• A CLAUDE_PLUGINS map ("plugin@marketplace" => "github-repo") drives claude plugin marketplace add + claude plugin install. It's idempotent and skips already-installed plugins.

To add a plugin, add an entry to both places in scripts/install-claude.sh.

Note: plugins that bundle an MCP server (e.g. Slack) still require a one-time interactive OAuth in each new Codespace — installation makes the plugin available and enabled, but does not authenticate the connection.

Memory Persistence

Claude's memory files are ephemeral — they live in ~/.claude/projects/ and get destroyed with the codespace. To persist memories across codespaces:

1. A PostToolUse hook copies memory writes to .claude-docs/memory/ in the project root for visibility
2. Review and commit keepers to the echo repo under memories/
3. At session start, echo's /memories command loads portable memories from ~/.echo/memories/ into the current project's Claude memory path and auto-generates the MEMORY.md index

Testing

./scripts/test.sh  # Run test suite

Local Installation

git clone https://github.com/YOUR-USERNAME/dotfiles.git
cd dotfiles
./install.sh