self-improve

name	self-improve
description	Run the self-improvement pipeline to analyze usage, plan, and apply Claude Code configuration improvements
user_invocable	true
argument_hint	[run|status|history|show <run-id>]

/self-improve — Claude Code Self-Improvement Pipeline

Analyze Claude Code usage insights, plan configuration improvements, get human approval, and execute approved changes.

Prerequisite: The /insights command must have been run recently (within 14 days). This pipeline consumes the existing /insights report and facets — it does not regenerate them.

Subcommands

/self-improve or /self-improve run

Trigger the self-improvement pipeline. This runs the four-stage process:

1. Analysis — Read the /insights report and facets, compare suggestions against current config, produce structured findings
2. Planning — Reason about findings and produce actionable change items with target files, descriptions, risk levels, and required permissions
3. Approval — Desktop notification prompts the user to approve, review, or reject the plan (includes consolidated permissions list)
4. Execution — Create an isolated git worktree, apply approved changes, commit, push branch, and open a PR to main

To trigger:

systemctl --user start claude-self-improve.service

Or run the pipeline script directly:

~/proj/AUTOMATE/insights/self-improve-pipeline

The pipeline will notify the user if the /insights report is missing or stale (>14 days old).

/self-improve status

Show the systemd timer status and last run outcome:

# Timer status
systemctl --user status claude-self-improve.timer
systemctl --user list-timers claude-self-improve*

# Last service run
systemctl --user status claude-self-improve.service
journalctl --user -u claude-self-improve.service --no-pager -n 30

/self-improve history

List recent pipeline runs with their outcomes. Read from ~/proj/AUTOMATE/insights/runs/:

# List all runs
ls -la ~/proj/AUTOMATE/insights/runs/

# For each run directory, summarize by reading:
# - pipeline.log (timestamps, stage progression)
# - analysis.json (finding count)
# - plan.json (item count)
# - approval.json (decision)
# - execution.json (success/failure counts)

Present results as a table with columns: Run ID, Findings, Plan Items, Approval, Executed, Cost.

/self-improve show <run-id>

Display full details of a specific run. The <run-id> is the timestamp directory name (e.g., 2026-02-19_090000).

Read and present:

1. ~/proj/AUTOMATE/insights/runs/<run-id>/pipeline.log — Timeline of events
2. ~/proj/AUTOMATE/insights/runs/<run-id>/analysis.json — All findings with categories and severities
3. ~/proj/AUTOMATE/insights/runs/<run-id>/plan.json — Planned changes and skipped findings
4. ~/proj/AUTOMATE/insights/runs/<run-id>/approval.json — Approval decision and method
5. ~/proj/AUTOMATE/insights/runs/<run-id>/execution.json — Per-item execution results (if approved)
6. ~/proj/AUTOMATE/insights/runs/<run-id>/plan-summary.md — Human-readable plan summary (includes required permissions)
7. ~/proj/AUTOMATE/insights/runs/<run-id>/pr-body.md — PR description body (if PR was created)

Pipeline Architecture

Stage 1: Analyze     Stage 2: Plan        Stage 3: Approve     Stage 4: Execute          Stage 5: Publish
claude -p (read)  ->  claude -p (no tools) -> notify-send (human) -> claude -p (worktree) -> git push + gh pr
     |                    |                      |                     |                       |
 analysis.json        plan.json            approval.json         execution.json           PR to main
                    + permissions                                 + commit on branch

All artifacts stored in: ~/proj/AUTOMATE/insights/runs/<timestamp>/ Changes are committed on an isolated self-improve/<run-id> branch and a PR is opened for asynchronous review.

Safety Features

• Budget caps per stage (default ~$11 total per run)
• Mandatory human approval before any file modifications
• Explicit permissions — each plan item enumerates required tool permissions, displayed for review during approval
• Worktree isolation — Stage 4 runs in a disposable git worktree; the main working tree is never touched
• Nix module routing — Claude Code config changes (CLAUDE.md, hooks, permissions, skills) must target Nix module source files, not runtime files in ~/.claude/
• PR-based review — changes are committed on a side branch and a PR is opened; nothing lands on main without explicit merge
• No nixos-rebuild — Nix changes are written but not activated
• Full audit trail — every run preserved in its own timestamped directory
• Deny rules from permissions.nix remain in effect (secrets, .env files protected)

Configuration

The pipeline is configured via the spirenix.cli.claude-code.selfImprove NixOS module options:

Option	Default	Purpose
enable	false	Enable the pipeline
insightsDir	$HOME/proj/AUTOMATE/insights	Base directory
repoDir	$HOME/nix-config/nixos	Git repo root for worktree branches
schedule	Sun *-*-* 09:00:00	Systemd timer schedule
analysisModel	opus	Model for analysis stage
planModel	opus	Model for planning stage
executionModel	opus	Model for execution stage
budgetAnalysis	3.00	Max USD for analysis
budgetPlan	3.00	Max USD for planning
budgetExecution	5.00	Max USD for execution
approvalTimeout	1800	Seconds before auto-reject (30 min)