arch-dev — Project Context for Claude Code

What this is

A portable, stateless Arch Linux development environment running in Docker. Headless, riced, mobile-aware. Built for serious dev work from any box — including from a phone via Termius.

The tagline that stuck: "Riced Neovim IDE"

The Human

Wayne. Works primarily from mobile (Android + Termius). Prefers vim keybindings everywhere. Wants things clean and professional — "Apple good" was the benchmark set early on. Doesn't want walls of text. Will call you out if you guess instead of reading docs. Has a Gitea instance at https://code.waynehayesdevelopment.com

Architecture

arch-dev/
├── Dockerfile              # Arch rolling release, pacman + AUR (yay)
├── docker-compose.yml      # Named volume for stateful /home/dev
├── entrypoint.sh           # First-run seeding + dotfile update detection
├── .gitignore
├── workspace/              # Bind mount — host-visible project files
└── dotfiles/               # Baked into /etc/skel-arch-dev/ in image
    ├── .zshrc              # 256-color only, mobile detection, snapshot fns
    ├── .aliases
    ├── .screenrc           # Mobile multiplexer
    ├── .config/
    │   ├── starship.toml          # Desktop: 256-color Kanagawa Wave approx
    │   ├── starship-mobile.toml   # Mobile: single line, no icons
    │   ├── tmux/tmux.conf         # Desktop mux, Ctrl+Space prefix
    │   └── nvim/                  # Full LSP/lint/format setup

The Stateful Home System (v1.7)

/home/dev is a named Docker volume (arch-dev-home). Persists across --rm container exits. NOT wiped on exit — only on docker volume rm.

On first run, entrypoint seeds the volume from /etc/skel-arch-dev/ (baked into the image). Subsequent runs detect if image dotfiles are newer and auto-update (with auto-snapshot first).

Git-backed snapshots

~/.arch-dev-state/ is a separate-git-dir tracking /home/dev. No .git folder in ~ — avoids nested git conflicts with project repos.

Shell functions (defined in .zshrc):

snapshot <name> [msg] / snap — tag current state
snapshots / snaps — list tags + recent commits
rollback <name> / snapr — reset to tag (confirms first, auto-snaps)
diff-state / snapd — what's changed since last commit
show-snapshot <name> — inspect a tag
unsnapshot <name> — delete a tag
_archdev_git — raw git wrapper (separate git dir)

The Color Problem (solved in v1.4+)

Termius on Android cannot render truecolor RGB escape codes. They show as purple/magenta backgrounds on everything.

Rules:

No COLORTERM=truecolor in compose or shell
No hex colors (#7E9CD8) in starship, zsh-syntax-highlighting, tmux
All shell-visible configs use 256-color ANSI codes (fg=110 etc.)
termguicolors in neovim is conditional: vim.env.MOBILE ~= "1"
Mobile colorscheme: habamax (built-in, 256-color clean)
Desktop colorscheme: kanagawa-wave (needs termguicolors)
Bufferline disabled on mobile (emits RGB for tab backgrounds)
noice.nvim removed entirely (bled colors into terminal)

Kanagawa Wave 256-color approximations:

110 = crystalBlue    106 = springGreen    139 = oniViolet
173 = boatYellow     167 = peachRed        66 = waveAqua
242 = fujiGray       250 = fujiWhite      236 = waveBlue

Mobile Detection

MOBILE=1 env var (set in Termius host profile) activates:

Minimal single-line starship prompt (no icons)
screen auto-attach instead of tmux
habamax colorscheme in neovim
termguicolors disabled
Bufferline disabled
Compact aliases (g for git, etc.)

Plugin API Changes (hard-won knowledge)

Every one of these bit us. Read docs before touching:

Plugin	Issue	Fix
`leap.nvim`	Moved GitHub→Codeberg	`url = "https://codeberg.org/andyg/leap.nvim"`
`leap.nvim`	`add_default_mappings()` removed	Use `<Plug>(leap)` keymaps directly
`nvim-treesitter`	`.configs` module gone	`require("nvim-treesitter").setup{}`, `branch="main"`, `lazy=false`
`nvim-surround`	v4 removed `keymaps` table	`require("nvim-surround").setup()` defaults only
`nvim-lspconfig`	Framework deprecated in 0.11	`vim.lsp.config()` + `vim.lsp.enable()`
`vim.lsp.with()`	Deprecated	Handlers in `vim.lsp.config("*", { handlers = {} })`
`on_attach`	Old pattern	`LspAttach` autocmd

What's NOT in v1 (coming in v2)

nvm + nodejs
Claude CLI
Gemini CLI
Aider
nvim AI plugin (copilot/avante/codecompanion)

v2 plan: install AI tools in the stateful container, snapshot as ai-tools, then layer nodejs on top.

Git / Repo

Gitea: https://code.waynehayesdevelopment.com/wayne/neovim-ide
main branch = current stable (v1.7)
v2 branch = active development
v1.7 tag = frozen reference

Wayne is new to multi-branch git workflow — be explicit about which branch to be on before any git operations.

Tone / Style Notes

Short responses. Wayne reads on mobile.
No bullet-point walls. Prose or tight tables.
Don't guess at APIs — fetch the docs first.
When something breaks, ask for the actual error before debugging.
Wayne will test each version and report back with screenshots.
"Apple good" is the visual quality bar.

5.3 KiB Raw Blame History