Skip to content

Architecture - caveman-savings

Component overview

Two independent, stateless PowerShell scripts that operate on a single device's local filesystem. Neither has a server, a daemon, or a network dependency. They coordinate only through two well-known filesystem locations: ~/.claude (Claude Code's config directory, overridable via $env:CLAUDE_CONFIG_DIR) and %LOCALAPPDATA%\caveman-compress\backups.

flowchart TD
    subgraph Device["One house PC"]
        A[Apply-CavemanSavings.ps1]
        M[Migrate-CavemanBackups.ps1]
        CC["~/.claude/CLAUDE.md"]
        CS["~/.claude/settings.json"]
        MEM["~/.claude/projects/*/memory/*.md"]
        BAK["%LOCALAPPDATA%/caveman-compress/backups/"]
        SKILL["caveman-compress skill (external plugin, optional)"]
    end

    A -- "Step 1: compress" --> MEM
    A -- "backs up originals to" --> BAK
    A -- "invokes if installed" --> SKILL
    A -- "Step 2: install/update rule block" --> CC
    A -- "Step 3: cap MCP output" --> CS

    M -- "reads old shared-slot backups from" --> BAK
    M -- "reads project memory files from" --> MEM
    M -- "relocates backups within" --> BAK

Sequence: Apply-CavemanSavings.ps1 on a fresh device

sequenceDiagram
    participant U as Operator
    participant A as Apply-CavemanSavings.ps1
    participant FS as "~/.claude filesystem"
    participant PY as python (optional, caveman-compress skill)

    U->>A: pwsh -File Apply-CavemanSavings.ps1
    A->>FS: resolve $claudeDir (CLAUDE_CONFIG_DIR or ~/.claude)
    alt claudeDir missing
        A-->>U: throw "Claude config dir not found"
    end

    A->>FS: find caveman-compress skill in plugin cache
    alt skill found and python on PATH
        A->>PY: python -m scripts <memory-file>
        PY-->>A: compressed file (or non-zero exit)
        A->>FS: back up original to LOCALAPPDATA\caveman-compress\backups\<project>\memory
    else skill or python missing
        A-->>U: Write-Warning, skip Step 1
    end

    A->>FS: read/write CLAUDE.md (insert or replace cavecrew-begin/end block)
    A->>FS: read/write settings.json (set env.MAX_MCP_OUTPUT_TOKENS, back up .bak first)
    A-->>U: "Done. Takes effect on next Claude Code session."

Design notes

  • Idempotency over cleverness. Every step checks its own prior output (a backup file's presence, a marker comment's presence, a JSON property's current value) before acting, so the script is always safe to re-run rather than requiring the operator to track state.
  • No secrets, ever. Both scripts touch only local configuration and cache directories. There is nothing here to authenticate against, so there is nothing to leak.
  • Migrate-CavemanBackups.ps1 exists because of a real bug in an earlier Apply-* revision (shared, collision-prone backup slot). It is a one-time cleanup utility, kept around (rather than folded into Apply-* and deleted) because devices upgrade on their own schedule and may still be running the old shared-slot behavior for a while.