# 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.

**Contingency:** If `pkgs.unstable.claude-code` does not exist at eval time, the fallback is a custom derivation in `pkgs/claude-code/default.nix` added to the local overlay — the same mechanism used for other absent packages.

## 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`