docs(spec): mibook claude-code execution machine design

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-25 11:53:36 +02:00
parent d2775e35d9
commit 62875c0b1a
1 changed files with 59 additions and 0 deletions
@@ -0,0 +1,59 @@
+# MiBook Claude Code Execution Machine
+
+**Date:** 2026-05-25
+**Branch:** feature/ha-zbt-2-thread
+**Status:** Approved
+
+## Goal
+
+Configure the MiBook as an interactive Claude Code execution machine by installing the Claude Code CLI and its companion tooling via a new, independently-toggleable NixOS profile module.
+
+## Scope
+
+Phase 1 (this spec): interactive CLI session — user logs in or SSHs in and runs `claude` directly.
+
+Phase 2 (future): headless systemd user service exposing Claude Code over an HTTP API or Unix socket, turning the MiBook into a remotely-triggerable execution node without an interactive session.
+
+## Module Structure
+
+```
+modules/environments/claude-code/default.nix   ← new module
+modules/environments/default.nix               ← add import
+machines/mibook/environments.nix               ← my.profiles.claude-code.enable = true
+```
+
+Follows the exact same pattern as every other environment module in this repo.
+
+## Option Declaration
+
+```
+my.profiles.claude-code.enable  (mkEnableOption)
+```
+
+No sub-options for Phase 1. Phase 2 would add `my.profiles.claude-code.service.enable`.
+
+## Packages (users.users.finn.packages)
+
+| Package | Source | Purpose |
+|---|---|---|
+| `claude-code` | `pkgs.unstable` | Claude Code CLI |
+| `ripgrep` | `pkgs` | Primary file search tool used by Claude Code |
+| `fd` | `pkgs` | Fast `find` replacement used by Claude Code |
+| `gh` | `pkgs` | GitHub CLI for PR/issue operations |
+| `jq` | `pkgs` | JSON processing in shell pipelines |
+
+`git`, `nodejs`, and `docker` are already provided by existing modules and are not duplicated.
+
+## No Secrets Management
+
+The Anthropic API key is handled manually by the user (browser login / `claude` interactive setup). No sops-nix or shell-profile injection needed.
+
+## Future: Headless Service
+
+A commented block in the module documents the upgrade path: a systemd user service that accepts work via an HTTP API or Unix socket, triggerable over SSH or a local network endpoint, without requiring an interactive session.
+
+## Files Changed
+
+1. `modules/environments/claude-code/default.nix` — new profile module
+2. `modules/environments/default.nix` — add `./claude-code` import
+3. `machines/mibook/environments.nix` — set `my.profiles.claude-code.enable = true`