neovim-ide/README.md

arch-dev

Riced Neovim IDE · Arch Linux · Stateful · Mobile-Aware

"Like Gentoo without the compiling." I use Arch BTW

Kanagawa Wave · rolling release · AUR-powered · git-snapshotted home

---

Branches

Branch	Purpose
main	Latest stable
v2	Active development
v1.7 (tag)	Frozen v1.7 reference

---

What's in v2

v2.0 — AI tooling

• Claude Code CLI (snapshot after install + login)
• Gemini CLI
• Aider
• nvm + Node.js (for AI tools that need it)

v2.1 — Image & ASCII tooling

• ImageMagick — image manipulation
• chafa — modern terminal image rendering (truecolor + sixel)
• jp2a — fast JPEG/PNG to ASCII art

Workflow: AI rough sketch → chafa --symbols ascii → hand-tweak

v2.2 — Tailscale

• Tailscale baked in via AUR
• /dev/net/tun device pass-through for kernel-mode networking
• NET_ADMIN + NET_RAW capabilities granted
• First-run auth, then snap tailscale for persistence

# Inside container, first time:
sudo tailscaled &
sudo tailscale up    # follow auth URL
snap tailscale "authenticated to tailnet"

v2.3 — Companion plugin (separate repo)

tailscale.nvim — original FOSS work, no equivalent exists yet:

• Lualine status component
• Telescope peer picker
• Quick IP copy + status window
• Repo: github.com//tailscale.nvim

---

v1.7 — What's there now

• Stateful /home/dev via named Docker volume
• Git-backed snapshot/rollback system (snap, snaps, rollback)
• Auto-snapshot on dotfile updates
• Mobile detection (MOBILE=1 for Termius)
• Kanagawa Wave colorscheme (desktop) / habamax (mobile)
• LSP/lint/format for Python, Bash, Lua
• Telescope, oil, lazygit, leap, treesitter

---

Quick Start

docker compose build
docker compose run --rm arch-dev

First run seeds /home/dev from the baked-in skeleton and creates a skeleton snapshot you can always roll back to.

---

Snapshot System

Your home is a git repo (state in ~/.arch-dev-state/). Save good states, roll back when things break.

snap node-working "NodeJS env with nvm + pnpm"  # save state
snaps                                            # list snapshots
snapd                                            # diff vs last snapshot
rollback node-working                            # reset to snapshot

---

Volume Architecture

Path	Type	Purpose
/workspace	bind mount → ./workspace	Project files, host-visible
/home/dev	named volume	Stateful user home
/etc/skel-arch-dev/	image layer	Read-only template

Reset home to factory: docker volume rm <project>_arch-dev-home

---

Container Capabilities

The container drops ALL capabilities then re-adds only what's needed:

Cap	Why
NET_BIND_SERVICE	Bind to ports < 1024 (mosh)
SETUID / SETGID	sudo
AUDIT_WRITE	sudoers_audit plugin
NET_ADMIN / NET_RAW	Tailscale

Plus device pass-through for /dev/net/tun (Tailscale kernel mode).

---

State Tracking — Two Systems

System	What	Where
git on v2 branch	Dockerfile, dotfiles, build recipe	Gitea repo
snap inside container	Runtime state, installed tools, auth	Docker volume

Both required for full reproducibility — Dockerfile builds the OS, snapshots restore the user state on top of it.

---

Mobile (Termius)

Set MOBILE=1 in Termius host profile env vars to activate:

• Single-line minimal starship prompt
• Auto-attach screen on connect
• habamax colorscheme (kanagawa needs truecolor)
• termguicolors disabled in neovim
• Bufferline disabled

With Tailscale (v2.2+), you can reach arch-dev from any device on your tailnet without exposing ports — perfect for mobile dev anywhere.