docs(plan): mibook claude-code module implementation plan
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
marthsincemelee
@@ -0,0 +1,232 @@
|
|||||||
|
# MiBook Claude Code Module Implementation Plan
|
||||||
|
|
||||||
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||||
|
|
||||||
|
**Goal:** Add a `my.profiles.claude-code` NixOS module that installs the Claude Code CLI and companion tooling on the MiBook.
|
||||||
|
|
||||||
|
**Architecture:** A single new environment module (`modules/environments/claude-code/default.nix`) declares the `my.profiles.claude-code.enable` option and installs packages for user `finn`. It is registered in `modules/environments/default.nix` and toggled on in `machines/mibook/environments.nix`.
|
||||||
|
|
||||||
|
**Tech Stack:** Nix flakes, NixOS module system, `pkgs.unstable` overlay (already present in repo)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## File Map
|
||||||
|
|
||||||
|
| Action | Path | Responsibility |
|
||||||
|
|---|---|---|
|
||||||
|
| Create | `modules/environments/claude-code/default.nix` | Declares option + installs packages |
|
||||||
|
| Modify | `modules/environments/default.nix` | Registers the new module so NixOS loads it |
|
||||||
|
| Modify | `machines/mibook/environments.nix` | Enables the profile for the MiBook host |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Task 1: Verify `claude-code` exists in `nixpkgs-unstable`
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Read-only check — no file changes
|
||||||
|
|
||||||
|
- [ ] **Step 1: Check if the package is available**
|
||||||
|
|
||||||
|
Run:
|
||||||
|
```bash
|
||||||
|
nix eval --extra-experimental-features 'nix-command flakes' 'github:NixOS/nixpkgs/nixos-unstable#claude-code.version' 2>&1
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected (success): prints a version string like `"0.2.x"`
|
||||||
|
|
||||||
|
Expected (failure): `error: attribute 'claude-code' missing`
|
||||||
|
|
||||||
|
- [ ] **Step 2: If the package exists — note the attribute path and continue to Task 2**
|
||||||
|
|
||||||
|
The module will use `pkgs.unstable.claude-code`.
|
||||||
|
|
||||||
|
- [ ] **Step 3: If the package does NOT exist — add a custom derivation first**
|
||||||
|
|
||||||
|
Create `pkgs/claude-code/default.nix`:
|
||||||
|
```nix
|
||||||
|
{ lib, buildNpmPackage, fetchFromGitHub }:
|
||||||
|
buildNpmPackage rec {
|
||||||
|
pname = "claude-code";
|
||||||
|
version = "0.2.116"; # update to latest release tag
|
||||||
|
|
||||||
|
src = fetchFromGitHub {
|
||||||
|
owner = "anthropics";
|
||||||
|
repo = "claude-code";
|
||||||
|
rev = "v${version}";
|
||||||
|
hash = lib.fakeHash; # run nix build to get real hash
|
||||||
|
};
|
||||||
|
|
||||||
|
npmDepsHash = lib.fakeHash; # run nix build to get real hash
|
||||||
|
|
||||||
|
meta = {
|
||||||
|
description = "Claude Code CLI by Anthropic";
|
||||||
|
homepage = "https://github.com/anthropics/claude-code";
|
||||||
|
license = lib.licenses.unfree;
|
||||||
|
mainProgram = "claude";
|
||||||
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Then register it in `pkgs/default.nix`:
|
||||||
|
```nix
|
||||||
|
final: prev: {
|
||||||
|
claude-code = final.callPackage ./claude-code { };
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
And use `pkgs.claude-code` (not `pkgs.unstable.claude-code`) in the module.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Task 2: Create the `claude-code` module
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Create: `modules/environments/claude-code/default.nix`
|
||||||
|
|
||||||
|
- [ ] **Step 1: Create the module file**
|
||||||
|
|
||||||
|
Create `modules/environments/claude-code/default.nix` with this exact content:
|
||||||
|
```nix
|
||||||
|
{
|
||||||
|
config,
|
||||||
|
lib,
|
||||||
|
pkgs,
|
||||||
|
...
|
||||||
|
}:
|
||||||
|
let
|
||||||
|
cfg = config.my.profiles.claude-code;
|
||||||
|
in
|
||||||
|
{
|
||||||
|
options.my.profiles.claude-code = with lib; {
|
||||||
|
enable = mkEnableOption "Claude Code CLI";
|
||||||
|
};
|
||||||
|
|
||||||
|
config = lib.mkIf cfg.enable {
|
||||||
|
users.users.finn.packages = with pkgs; [
|
||||||
|
unstable.claude-code
|
||||||
|
ripgrep
|
||||||
|
fd
|
||||||
|
gh
|
||||||
|
jq
|
||||||
|
];
|
||||||
|
|
||||||
|
# Future: headless Claude Code service
|
||||||
|
# A natural next step is exposing Claude Code as a persistent background service —
|
||||||
|
# e.g. a systemd user service that accepts work via an HTTP API or Unix socket,
|
||||||
|
# triggerable over SSH or a local network endpoint. This would turn the MiBook
|
||||||
|
# into a true remote execution node without requiring an interactive session.
|
||||||
|
# See: my.profiles.claude-code.service.enable (not yet implemented)
|
||||||
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
> Note: if Task 1 Step 3 was taken (custom derivation), replace `unstable.claude-code` with `claude-code`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Task 3: Register the module
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Modify: `modules/environments/default.nix`
|
||||||
|
|
||||||
|
- [ ] **Step 1: Add the import**
|
||||||
|
|
||||||
|
In `modules/environments/default.nix`, add `./claude-code` to the imports list (alphabetical order puts it between `./audiobookshelf` and `./development`):
|
||||||
|
|
||||||
|
```nix
|
||||||
|
{ ... }:
|
||||||
|
{
|
||||||
|
imports = [
|
||||||
|
./actual
|
||||||
|
./apps
|
||||||
|
./audiobookshelf
|
||||||
|
./claude-code
|
||||||
|
./development
|
||||||
|
./home-assistant
|
||||||
|
./hyprland
|
||||||
|
./zsh
|
||||||
|
./paperless
|
||||||
|
./prowlarr
|
||||||
|
./radarr
|
||||||
|
./docker
|
||||||
|
./homepage
|
||||||
|
./kde-desktop
|
||||||
|
./readarr
|
||||||
|
./sonarr
|
||||||
|
./jellyfin
|
||||||
|
./jellyseerr
|
||||||
|
];
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] **Step 2: Verify the option is now defined (without enabling it)**
|
||||||
|
|
||||||
|
Run:
|
||||||
|
```bash
|
||||||
|
nix eval --extra-experimental-features 'nix-command flakes' '.#nixosConfigurations.mibook.options.my.profiles.claude-code.enable.description'
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: `"Whether to enable Claude Code CLI."`
|
||||||
|
|
||||||
|
If this errors, the module isn't loading — re-check the import path.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Task 4: Enable on MiBook and verify the build
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Modify: `machines/mibook/environments.nix`
|
||||||
|
|
||||||
|
- [ ] **Step 1: Enable the profile**
|
||||||
|
|
||||||
|
In `machines/mibook/environments.nix`, add `claude-code.enable = true` inside the `my.profiles` block:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
my.profiles = {
|
||||||
|
kde-desktop.enable = true;
|
||||||
|
zsh.enable = true;
|
||||||
|
apps = {
|
||||||
|
desktop_apps = true;
|
||||||
|
dev_apps = true;
|
||||||
|
};
|
||||||
|
development.enable = true;
|
||||||
|
docker.enable = true;
|
||||||
|
claude-code.enable = true;
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] **Step 2: Verify the package appears in finn's user packages**
|
||||||
|
|
||||||
|
Run:
|
||||||
|
```bash
|
||||||
|
nix eval --extra-experimental-features 'nix-command flakes' '.#nixosConfigurations.mibook.config.users.users.finn.packages' --apply 'builtins.map (p: p.name)' 2>&1 | grep -i claude
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: a line containing `claude-code-<version>`
|
||||||
|
|
||||||
|
- [ ] **Step 3: Dry-run build to confirm the full config evaluates**
|
||||||
|
|
||||||
|
Run:
|
||||||
|
```bash
|
||||||
|
nix build '.#nixosConfigurations.mibook.config.system.build.toplevel' --extra-experimental-features 'nix-command flakes' --dry-run 2>&1 | tail -5
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: exits 0, output lists derivations to build (or "nothing to do" if already cached). No evaluation errors.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Task 5: Commit
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- All changed files from Tasks 1–4
|
||||||
|
|
||||||
|
- [ ] **Step 1: Stage and commit**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add modules/environments/claude-code/default.nix \
|
||||||
|
modules/environments/default.nix \
|
||||||
|
machines/mibook/environments.nix
|
||||||
|
git commit -m "feat(mibook): add claude-code profile module"
|
||||||
|
```
|
||||||
|
|
||||||
|
If Task 1 Step 3 was taken, also stage `pkgs/claude-code/default.nix` and `pkgs/default.nix`.
|
||||||
Reference in New Issue
Block a user