nixos/docs/superpowers/specs/2026-05-25-mibook-claude-code-design.md

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