claudenv 1.2.4 → 1.2.5

package/README.md

@@ -1,6 +1,6 @@
 # claudenv
 
-One command to set up [Claude Code](https://docs.anthropic.com/en/docs/claude-code) in any project. Claude AI analyzes your codebase and generates all the documentation it needs to work effectively.
+Set up [Claude Code](https://docs.anthropic.com/en/docs/claude-code) in any project with one command. claudenv analyzes your codebase and generates everything Claude needs to work effectively — documentation, rules, hooks, MCP servers, and slash commands.
 
 ## Quick Start
 
@@ -8,244 +8,222 @@ One command to set up [Claude Code](https://docs.anthropic.com/en/docs/claude-co
 npm i -g claudenv && claudenv
 ```
 
-Done. Open Claude Code in any project and type `/claudenv`.
+Open Claude Code in any project and type `/claudenv`. That's it.
 
-## How It Works
+## What happens when you run `/claudenv`
 
-**One-time setup** — install and activate:
+Claude reads your code, asks a few questions, and generates:
 
-```bash
-npm i -g claudenv && claudenv
-```
-
-This installs the `/claudenv` command globally into `~/.claude/`, making it available in every project.
-
-**In any project** — open Claude Code and type `/claudenv`.
+- **CLAUDE.md** — project overview, architecture, key commands
+- **Rules** — coding style, testing patterns, workflow guidelines (`.claude/rules/`)
+- **MCP servers** — auto-detected from your stack, configured in `.mcp.json`
+- **Slash commands** — `/init-docs`, `/update-docs`, `/validate-docs`, `/setup-mcp`, `/improve`
+- **Hooks** — validation on tool use, audit logging (`.claude/settings.json`)
 
-Claude AI will:
-1. Read your manifest files, configs, and source code
-2. Detect your tech stack, frameworks, and tooling
-3. Ask you about the project (description, deployment, conventions)
-4. Generate all documentation files
-5. Search the [MCP Registry](https://registry.modelcontextprotocol.io) and configure MCP servers
-6. Install slash commands for ongoing maintenance
+Everything is committed to your repo. Team members get the same Claude experience.
 
-You now have five commands available in Claude Code:
+## Autonomous Loop
 
-| Command | What it does |
-|---------|-------------|
-| `/init-docs` | Regenerate documentation from scratch |
-| `/update-docs` | Scan for changes and propose updates |
-| `/validate-docs` | Check that documentation is complete and correct |
-| `/setup-mcp` | Recommend and configure MCP servers |
-| `/improve` | Analyze and make one improvement |
+The killer feature. `claudenv loop` runs Claude in headless mode, iterating over your project — planning improvements, implementing them one by one, committing each step.
 
-## What Gets Generated
-
-```
-your-project/
-├── CLAUDE.md                              # Project overview, commands, architecture
-├── _state.md                              # Session memory (decisions, focus, issues)
-├── .mcp.json                              # MCP server configuration
-└── .claude/
-    ├── rules/
-    │   ├── code-style.md                  # Coding conventions (scoped by file paths)
-    │   ├── testing.md                     # Test patterns and commands
-    │   └── workflow.md                    # Claude Code best practices
-    ├── settings.json                      # Validation hooks
-    ├── commands/
-    │   ├── init-docs.md                   # /init-docs
-    │   ├── update-docs.md                 # /update-docs
-    │   ├── validate-docs.md              # /validate-docs
-    │   ├── setup-mcp.md                  # /setup-mcp
-    │   └── improve.md                    # /improve
-    ├── skills/
-    │   └── doc-generator/                 # Auto-triggers when docs need updating
-    └── agents/
-        └── doc-analyzer.md                # Read-only analysis subagent
+```bash
+claudenv loop --goal "add test coverage" --trust -n 5
 ```
 
-### Key Files
+**What it does:**
 
-| File | Purpose |
-|------|---------|
-| `CLAUDE.md` | Compact project overview with `@import` references to rule files |
-| `_state.md` | Persists context between sessions — current focus, decisions, known issues |
-| `.claude/rules/workflow.md` | Best practices: plan mode, `/compact`, subagents, git discipline |
-| `.claude/rules/code-style.md` | Language and framework-specific coding conventions |
-| `.claude/rules/testing.md` | Test framework patterns and commands |
-| `.mcp.json` | MCP server configuration with `${ENV_VAR}` placeholders |
+1. Creates a git safety tag (rollback anytime with `--rollback`)
+2. Claude generates an improvement plan (`.claude/improvement-plan.md`)
+3. Each iteration picks the next item, implements it, runs tests, commits
+4. Stops when the plan is done, iterations run out, or it detects it's stuck
 
-## MCP Server Recommendations
+### Common recipes
 
-`/claudenv` automatically recommends MCP servers based on your tech stack. You can also run `/setup-mcp` independently at any time.
+```bash
+# Interactive mode — pauses between iterations so you can review
+claudenv loop
 
-**How it works:**
+# Fully autonomous — no pauses, no permission prompts
+claudenv loop --trust
 
-1. Claude analyzes your project's dependencies, databases, cloud services, and tools
-2. Searches the [official MCP Registry](https://registry.modelcontextprotocol.io) for matching servers
-3. Verifies trust via npm download counts (filters out servers with <100 monthly downloads)
-4. Presents recommendations grouped as **Essential** / **Recommended** / **Optional**
-5. Generates `.mcp.json` with selected servers
+# Goal-driven with Opus for max capability
+claudenv loop --goal "refactor auth to JWT" --trust --model opus -n 3
 
-**Example output** (`.mcp.json`):
+# Budget-conscious CI run
+claudenv loop --profile ci --goal "fix lint errors" -n 10
 
-```json
-{
-  "mcpServers": {
-    "context7": {
-      "command": "npx",
-      "args": ["-y", "@upstash/context7-mcp@latest"],
-      "env": {}
-    },
-    "postgres": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-postgres@latest", "${POSTGRES_CONNECTION_STRING}"],
-      "env": {}
-    }
-  }
-}
+# Undo everything from the last loop
+claudenv loop --rollback
 ```
 
-Secrets use `${ENV_VAR}` placeholders — configure them with:
+### Rate limit recovery
+
+If Claude hits API rate limits mid-loop, claudenv saves your progress automatically:
 
 ```bash
-claude config set env.POSTGRES_CONNECTION_STRING "postgresql://..."
-```
+# Rate limited? Just resume where you left off
+claudenv loop --resume
 
-`.mcp.json` is safe to commit — it never contains actual secrets.
+# Override model on resume (e.g., switch to cheaper model)
+claudenv loop --resume --model sonnet
+```
 
-Run `/setup-mcp --force` to auto-select Essential + Recommended servers without prompting.
+### Live progress tracking
 
-## Iterative Improvement Loop
+Monitor what Claude is doing in real time:
 
-`claudenv loop` spawns Claude Code in headless mode to analyze and improve your project iteratively. Each run creates a git safety tag so you can always rollback.
+```bash
+# In another terminal — tail -f style
+claudenv report --follow
 
-**How it works:**
+# Summary of the last loop run
+claudenv report
 
-1. **Planning** (iteration 0) — Claude analyzes the project and generates `.claude/improvement-plan.md` with prioritized hypotheses
-2. **Execution** (iterations 1-N) — each iteration picks the top unfinished item from the plan, implements it, runs tests, and commits
-3. **Convergence** — the loop stops when the plan is complete, max iterations are reached, or the loop detects it's stuck
+# Last 5 events only
+claudenv report --last 5
+```
 
-**Usage:**
+Events are stored in `.claude/work-report.jsonl` — machine-readable JSONL format.
 
-```bash
-claudenv loop                              # Interactive, pauses between iterations
-claudenv loop --trust                      # Full trust, no pauses, no permission prompts
-claudenv loop --trust -n 5                 # 5 iterations in full trust
-claudenv loop --goal "add test coverage"   # Focused improvement
-claudenv loop --trust --model opus -n 3    # Use Opus, 3 iterations
-claudenv loop --budget 1.00 -n 10          # Budget cap per iteration
-claudenv loop --rollback                   # Undo all loop changes
-```
+### All loop flags
 
 | Flag | Description |
 |------|-------------|
-| `-n, --iterations <n>` | Max iterations (default: unlimited) |
+| `--goal <text>` | What to work on (any goal — Claude interprets it) |
 | `--trust` | Full trust mode — no pauses, skip permission prompts |
-| `--goal <text>` | Focus area for improvements |
-| `--profile <name>` | Autonomy profile: safe, moderate, full, ci |
-| `--no-pause` | Don't pause between iterations |
-| `--max-turns <n>` | Max agentic turns per iteration (default: 30) |
-| `--model <model>` | Model to use (default: sonnet) |
+| `-n, --iterations <n>` | Max iterations (default: unlimited) |
+| `--model <model>` | Model: `opus`, `sonnet`, `haiku` |
+| `--profile <name>` | Autonomy profile (sets model, trust, budget) |
 | `--budget <usd>` | Budget cap per iteration in USD |
-| `-d, --dir <path>` | Target project directory |
-| `--allow-dirty` | Allow running with uncommitted changes |
+| `--max-turns <n>` | Max agentic turns per iteration (default: 30) |
+| `--resume` | Continue from last rate-limited loop |
 | `--rollback` | Undo all changes from the most recent loop |
-| `--unsafe` | Remove default tool restrictions |
-
-**Git safety:** Before the first iteration, a `claudenv-loop-<timestamp>` git tag is created. Each iteration commits separately. Use `claudenv loop --rollback` to reset everything, or cherry-pick individual commits.
-
-**Single iteration:** Use `/improve` inside Claude Code for a one-shot improvement without the full loop.
-
-## Autonomous Agent Mode
+| `--worktree` | Run each iteration in an isolated git worktree |
+| `--allow-dirty` | Allow running with uncommitted changes |
+| `--no-pause` | Don't pause between iterations |
+| `--unsafe` | Remove default tool restrictions (allows rm -rf) |
+| `-d, --dir <path>` | Target project directory |
 
-`claudenv autonomy` configures Claude Code for autonomous operation with predefined security profiles. Inspired by [trailofbits/claude-code-config](https://github.com/trailofbits/claude-code-config).
+## Autonomy Profiles
 
-**Usage:**
+Control how much freedom Claude gets. Profiles configure permissions, hooks, model defaults, and safety guardrails.
 
 ```bash
-claudenv autonomy                          # Interactive profile selection
-claudenv autonomy --profile moderate       # Non-interactive, writes files directly
-claudenv autonomy --profile moderate -y    # Same — -y only needed for profile selection
-claudenv autonomy --profile ci --dry-run   # Preview generated files
-claudenv autonomy --profile full           # Full autonomy — requires typing "full" to confirm
-claudenv autonomy --profile full --yes     # Full autonomy, skip confirmation
+claudenv autonomy                          # Interactive selection
+claudenv autonomy --profile moderate       # Apply directly
+claudenv autonomy --profile ci --dry-run   # Preview without writing
 ```
 
-### Profiles
+### Profile comparison
 
-| Profile | Description | Permissions | Credentials |
-|---------|-------------|-------------|-------------|
-| `safe` | Read-only + limited bash | Allow-list only | Blocked |
-| `moderate` | Full dev with deny-list | Allow + deny lists | Blocked |
-| `full` | Unrestricted + audit logging | `--dangerously-skip-permissions` | Warn-only |
-| `ci` | Headless CI/CD (50 turns, $5 budget) | `--dangerously-skip-permissions` | Warn-only |
+| Profile | Model | Permissions | Credentials | Use case |
+|---------|-------|-------------|-------------|----------|
+| **safe** | sonnet | Allow-list only (read + limited bash) | Blocked | Exploring unfamiliar codebases |
+| **moderate** | sonnet | Allow + deny lists (full dev tools) | Blocked | Day-to-day development |
+| **full** | opus | Unrestricted (`--dangerously-skip-permissions`) | Warn-only | Maximum capability runs |
+| **ci** | haiku | Unrestricted + 50 turn / $5 budget limits | Warn-only | CI/CD pipelines |
 
-All profiles hard-block `rm -rf`, force push to main/master, and `sudo`.
+All profiles hard-block `rm -rf`, force push to main/master, and `sudo` — regardless of permission settings.
 
-### Generated files
+### What gets generated
 
 ```
 .claude/
-├── settings.json               # Permissions + hooks config
+├── settings.json          # Permissions, hooks config
 ├── hooks/
-│   ├── pre-tool-use.sh         # PreToolUse guard (blocks dangerous ops)
-│   └── audit-log.sh            # PostToolUse audit → audit-log.jsonl
-└── aliases.sh                  # Shell aliases: claude-safe, claude-yolo, claude-ci, claude-local
+│   ├── pre-tool-use.sh    # Blocks dangerous operations (reads stdin JSON from Claude Code)
+│   └── audit-log.sh       # Logs every tool call to audit-log.jsonl
+└── aliases.sh             # Shell aliases: claude-safe, claude-yolo, claude-ci, claude-local
 ```
 
 CI profile also generates `.github/workflows/claude-ci.yml`.
 
-### Loop integration
+### Using profiles with the loop
 
-Use `--profile` with `claudenv loop` to apply profile settings:
+Profiles set sensible defaults for model, trust, and budget:
 
 ```bash
-claudenv loop --profile moderate --goal "add types"   # Uses profile's deny-list
-claudenv loop --profile ci -n 5                       # CI defaults: 50 turns, $5 budget
+claudenv loop --profile ci --goal "fix lint errors"    # haiku, $5 budget, 50 turns
+claudenv loop --profile full --goal "major refactor"   # opus, unrestricted
+claudenv loop --profile moderate --goal "add types"    # sonnet, deny-list guarded
+
+# CLI flags always override profile defaults
+claudenv loop --profile ci --model sonnet              # ci profile but with sonnet
 ```
 
-| Flag | Description |
-|------|-------------|
-| `-p, --profile <name>` | Profile: safe, moderate, full, ci |
-| `-d, --dir <path>` | Project directory (default: `.`) |
-| `--overwrite` | Overwrite existing files |
-| `-y, --yes` | Skip prompts |
-| `--dry-run` | Preview without writing |
+## MCP Server Setup
 
-## Tech Stack Detection
+`/claudenv` auto-detects your tech stack and recommends MCP servers from the [official registry](https://registry.modelcontextprotocol.io). You can also run `/setup-mcp` independently.
 
-Claude AI reads your actual code, but the following are auto-detected for context:
+Servers are configured in `.mcp.json` with `${ENV_VAR}` placeholders — safe to commit:
 
-- **Languages**: TypeScript, JavaScript, Python, Go, Rust, Ruby, PHP, Java, Kotlin, C#
-- **Frameworks**: Next.js, Vite, Nuxt, SvelteKit, Astro, Angular, Django, FastAPI, Flask, Rails, Laravel, Spring Boot, and more
-- **Package managers**: npm, yarn, pnpm, bun, poetry, pipenv, uv, cargo, go modules
-- **Test frameworks**: Vitest, Jest, Playwright, Cypress, pytest, RSpec, go test, cargo test
-- **CI/CD**: GitHub Actions, GitLab CI, Jenkins, CircleCI
-- **Linters/formatters**: ESLint, Biome, Prettier, Ruff, RuboCop, golangci-lint, Clippy
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    },
+    "postgres": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-postgres@latest", "${POSTGRES_CONNECTION_STRING}"]
+    }
+  }
+}
+```
+
+Set secrets with `claude config set env.POSTGRES_CONNECTION_STRING "postgresql://..."`.
+
+## File Structure
+
+After full setup (`/claudenv` + `claudenv autonomy`):
+
+```
+your-project/
+├── CLAUDE.md                     # Project overview for Claude
+├── _state.md                     # Session memory (persists between conversations)
+├── .mcp.json                     # MCP server configuration
+└── .claude/
+    ├── settings.json             # Permissions + hooks
+    ├── rules/
+    │   ├── code-style.md         # Coding conventions
+    │   ├── testing.md            # Test patterns
+    │   └── workflow.md           # Claude workflow best practices
+    ├── hooks/
+    │   ├── pre-tool-use.sh       # Safety guardrails
+    │   └── audit-log.sh          # Audit logging
+    ├── commands/                  # Slash commands
+    │   ├── init-docs.md
+    │   ├── update-docs.md
+    │   ├── validate-docs.md
+    │   ├── setup-mcp.md
+    │   └── improve.md
+    ├── aliases.sh                # Shell aliases
+    ├── work-report.jsonl         # Loop progress events
+    ├── loop-log.json             # Loop state (for resume/rollback)
+    ├── improvement-plan.md       # Current loop plan
+    └── audit-log.jsonl           # Tool call audit trail
+```
 
 ## CLI Reference
 
 ```
-claudenv                  Install /claudenv into ~/.claude/ (default)
-claudenv install          Same as above (explicit)
-claudenv install -f       Reinstall, overwriting existing files
-claudenv uninstall        Remove /claudenv from ~/.claude/
-claudenv init [dir]       Legacy: static analysis + terminal prompts (no AI)
-claudenv init -y          Legacy: skip prompts, auto-detect everything
-claudenv generate         Templates only, no scaffold
-claudenv validate         Check documentation completeness
-claudenv loop             Iterative improvement loop (spawns Claude)
-claudenv loop --trust     Full trust mode, no pauses
-claudenv loop --profile moderate  Use autonomy profile in loop
-claudenv loop --rollback  Undo all loop changes
-claudenv autonomy         Configure autonomous agent mode (interactive)
-claudenv autonomy -p moderate     Apply moderate profile
-claudenv autonomy -p ci --dry-run Preview CI config without writing
+claudenv                              Install /claudenv into ~/.claude/
+claudenv install [-f]                 Same as above (-f to overwrite)
+claudenv uninstall                    Remove from ~/.claude/
+
+claudenv loop [options]               Autonomous improvement loop
+claudenv loop --resume                Resume rate-limited loop
+claudenv loop --rollback              Undo all loop changes
+claudenv report [--follow] [--last n] View loop progress
+
+claudenv autonomy [-p <profile>]      Configure autonomy profiles
+claudenv init [dir] [-y]              Legacy: static analysis (no AI)
+claudenv generate [-d <dir>]          Templates only, no scaffold
+claudenv validate [-d <dir>]          Check documentation completeness
 ```
 
-## Alternative: Run Without Installing
+## Run Without Installing
 
 ```bash
 npx claudenv            # npm
@@ -253,12 +231,9 @@ pnpm dlx claudenv       # pnpm
 bunx claudenv           # bun
 ```
 
-## Uninstall
+## Tech Stack Detection
 
-```bash
-claudenv uninstall      # Remove from ~/.claude/
-npm uninstall -g claudenv
-```
+Auto-detected for context: TypeScript, JavaScript, Python, Go, Rust, Ruby, PHP, Java, Kotlin, C# / Next.js, Vite, Nuxt, SvelteKit, Astro, Django, FastAPI, Flask, Rails, Laravel, Spring Boot / npm, yarn, pnpm, bun, poetry, uv, cargo / Vitest, Jest, Playwright, pytest, RSpec / GitHub Actions, GitLab CI / ESLint, Biome, Prettier, Ruff, Clippy.
 
 ## Requirements
 

package/bin/cli.js

@@ -10,9 +10,10 @@ import { generateDocs, writeDocs, installScaffold } from '../src/generator.js';
 import { validateClaudeMd, validateStructure, crossReferenceCheck } from '../src/validator.js';
 import { runExistingProjectFlow, runColdStartFlow, buildDefaultConfig } from '../src/prompts.js';
 import { installGlobal, uninstallGlobal } from '../src/installer.js';
-import { runLoop, rollback, checkClaudeCli } from '../src/loop.js';
+import { runLoop, rollback, checkClaudeCli, readLoopLog } from '../src/loop.js';
 import { generateAutonomyConfig, printSecuritySummary, getFullModeWarning } from '../src/autonomy.js';
 import { getProfile, listProfiles } from '../src/profiles.js';
+import { readReport, formatReport, formatEventLine, watchReport } from '../src/report.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkgJson = JSON.parse(await readFile(join(__dirname, '..', 'package.json'), 'utf-8'));
@@ -131,6 +132,7 @@ program
   .option('-d, --dir <path>', 'Target project directory')
   .option('--allow-dirty', 'Allow running with uncommitted git changes')
   .option('--rollback', 'Undo all changes from the most recent loop run')
+  .option('--resume', 'Resume from last rate-limited iteration')
   .option('--unsafe', 'Remove default tool restrictions (allows rm -rf)')
   .option('--worktree', 'Run each iteration in an isolated git worktree')
   .option('--profile <name>', 'Autonomy profile: safe, moderate, full, ci')
@@ -141,6 +143,36 @@ program
       return;
     }
 
+    // --- Resume mode ---
+    if (opts.resume) {
+      const resumeCwd = opts.dir ? resolve(opts.dir) : process.cwd();
+      const prevLog = await readLoopLog(resumeCwd);
+      if (!prevLog || !prevLog.pausedAt) {
+        console.error('\n  No resumable loop found. Run a loop first or check .claude/loop-log.json.\n');
+        process.exit(1);
+      }
+      const saved = prevLog.options || {};
+      console.log(`\n  Resuming loop from iteration ${prevLog.pausedAt.iteration}`);
+      console.log(`  Goal: ${saved.goal || 'General improvement'}`);
+      console.log(`  Session: ${prevLog.pausedAt.sessionId || 'new'}\n`);
+
+      await runLoop({
+        iterations: opts.iterations || Infinity,
+        trust: saved.trust || false,
+        goal: saved.goal,
+        pause: false,
+        maxTurns: saved.maxTurns || 30,
+        model: opts.model || saved.model,
+        budget: saved.budget,
+        cwd: resumeCwd,
+        allowDirty: true,
+        worktree: saved.worktree || false,
+        startIteration: prevLog.pausedAt.iteration,
+        initialSessionId: prevLog.pausedAt.sessionId,
+      });
+      return;
+    }
+
     // --- Pre-flight: check Claude CLI ---
     const cli = checkClaudeCli();
     if (!cli.installed) {
@@ -176,6 +208,7 @@ program
         disallowedTools: profile.disallowedTools,
         maxTurns: profile.maxTurns,
         budget: profile.maxBudget,
+        model: profile.model,
       };
       console.log(`  Profile: ${profile.name} — ${profile.description}`);
     }
@@ -189,7 +222,8 @@ program
     if (opts.worktree) console.log(`  Worktree: enabled (each iteration in isolated worktree)`);
     if (opts.iterations) console.log(`  Max iterations: ${opts.iterations}`);
     if (opts.goal) console.log(`  Goal: ${opts.goal}`);
-    if (opts.model) console.log(`  Model: ${opts.model}`);
+    const model = opts.model || profileDefaults.model || undefined;
+    if (model) console.log(`  Model: ${model}`);
     if (opts.budget || profileDefaults.budget) console.log(`  Budget: $${opts.budget || profileDefaults.budget}/iteration`);
     if (opts.maxTurns || profileDefaults.maxTurns) console.log(`  Max turns: ${opts.maxTurns || profileDefaults.maxTurns}`);
 
@@ -199,7 +233,7 @@ program
       goal: opts.goal,
       pause,
       maxTurns: opts.maxTurns || profileDefaults.maxTurns || 30,
-      model: opts.model,
+      model,
       budget: opts.budget || profileDefaults.budget,
       cwd,
       allowDirty: opts.allowDirty || false,
@@ -209,6 +243,40 @@ program
     });
   });
 
+// --- report ---
+program
+  .command('report')
+  .description('View work report from autonomous loop runs')
+  .option('-f, --follow', 'Live stream events (tail -f style)')
+  .option('--last <n>', 'Show last N events', parseInt)
+  .option('-d, --dir <path>', 'Project directory')
+  .action(async (opts) => {
+    const cwd = opts.dir ? resolve(opts.dir) : process.cwd();
+    const events = await readReport(cwd);
+
+    if (opts.follow) {
+      // Print existing events first
+      if (events.length > 0) {
+        const show = opts.last ? events.slice(-opts.last) : events;
+        process.stdout.write(formatReport(show));
+      }
+      console.log('  Watching for new events... (Ctrl+C to stop)\n');
+      await watchReport(cwd, (event) => {
+        process.stdout.write(formatEventLine(event));
+      });
+      return;
+    }
+
+    if (events.length === 0) {
+      console.log('\n  No work report found. Run `claudenv loop` first.\n');
+      return;
+    }
+
+    const show = opts.last ? events.slice(-opts.last) : events;
+    console.log();
+    process.stdout.write(formatReport(show));
+  });
+
 // --- autonomy ---
 program
   .command('autonomy')
@@ -247,7 +315,8 @@ async function runInstall(opts) {
   console.log(`
   Done! Now open Claude Code in any project and type:
 
-    /claudenv
+    /claudenv    — Set up project documentation
+    /autonomy   — Manage autonomy profiles
 
   Claude will analyze your project and generate documentation.
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudenv",
-  "version": "1.2.4",
+  "version": "1.2.5",
   "description": "One command to integrate Claude Code into any project — installs /claudenv command for AI-powered documentation generation",
   "type": "module",
   "bin": {

package/scaffold/global/.claude/commands/autonomy.md

@@ -0,0 +1,90 @@
+---
+description: Manage autonomy profiles — switch between safe/moderate/full/ci or view current status
+allowed-tools: Bash, Read, Glob, Grep
+argument-hint: <status|safe|moderate|full|ci> [--dry-run]
+---
+
+# Autonomy Profile Manager
+
+Manage Claude Code autonomy profiles directly from within a session.
+
+## Instructions
+
+Parse `$ARGUMENTS` and execute the matching action below.
+
+### 1. Determine the action
+
+- If `$ARGUMENTS` is empty or `status` → go to **Status**
+- If `$ARGUMENTS` starts with `safe`, `moderate`, `full`, or `ci` → go to **Switch Profile**
+- Otherwise → go to **Usage Help**
+
+### 2. Status
+
+Show the current autonomy configuration:
+
+1. Check if `.claude/hooks/pre-tool-use.sh` exists in the current project directory.
+   - If it exists, read the first 5 lines to find the `# Profile:` comment header and report the active profile name.
+   - If it doesn't exist, report "No autonomy profile configured for this project."
+2. Check if `.claude/settings.json` exists. If so, read it and summarize the permissions (allowedTools, disallowedTools counts).
+3. List available profiles: `safe`, `moderate`, `full`, `ci`.
+
+### 3. Switch Profile
+
+The target profile is the first word of `$ARGUMENTS`. Check for `--dry-run` flag in the remaining arguments.
+
+**If the profile is `full`:**
+Before proceeding, display this warning:
+
+```
+⚠️  FULL AUTONOMY MODE — UNRESTRICTED ACCESS
+
+This profile grants Claude Code complete access including:
+• All file system operations (read, write, delete)
+• Credential files (~/.ssh, ~/.aws, ~/.gnupg, ~/.kube, etc.)
+• All git operations including force push
+• No permission prompts (--dangerously-skip-permissions)
+
+Safety net: audit logging + hard blocks on rm -rf / and force push to main
+```
+
+Ask the user to confirm before proceeding. If they decline, abort.
+
+**Apply the profile:**
+
+Build the command:
+```
+claudenv autonomy --profile <name> --yes --overwrite
+```
+
+If `--dry-run` is present in `$ARGUMENTS`, append `--dry-run` to the command.
+
+Run the command via Bash. If the command fails with "command not found", tell the user:
+
+```
+claudenv is not on PATH. Install it with:
+  npm install -g claudenv
+```
+
+After successful execution, show the output and confirm the profile was applied.
+
+### 4. Usage Help
+
+Display:
+```
+Usage: /autonomy <action> [options]
+
+Actions:
+  status              Show current autonomy profile and permissions
+  safe                Switch to safe profile (read-only + limited bash)
+  moderate            Switch to moderate profile (read/write + controlled bash)
+  full                Switch to full profile (unrestricted — requires confirmation)
+  ci                  Switch to CI profile (optimized for CI/CD pipelines)
+
+Options:
+  --dry-run           Preview generated files without writing them
+
+Examples:
+  /autonomy status
+  /autonomy moderate
+  /autonomy full --dry-run
+```

package/src/autonomy.js

@@ -63,6 +63,7 @@ export function printSecuritySummary(profile) {
   console.log(`\n  Security summary — ${profile.name} profile\n`);
   console.log(`  ${'─'.repeat(50)}`);
 
+  console.log(`  Default model:      ${profile.model || 'sonnet'}`);
   console.log(`  Skip permissions:   ${profile.skipPermissions ? 'YES (--dangerously-skip-permissions)' : 'No'}`);
   console.log(`  Credential policy:  ${profile.credentialPolicy}`);
 

package/src/hooks-gen.js

@@ -101,11 +101,21 @@ export function generatePreToolUseHook(profile, detected = {}) {
   return `#!/usr/bin/env bash
 # Pre-tool-use hook — generated by claudenv autonomy (profile: ${profile.name})
 # Exit 0 = allow, Exit 2 = block
+# Claude Code sends hook data via stdin as JSON: {"tool_name":"...","tool_input":{...}}
 
 set -euo pipefail
 
-TOOL_NAME="\${CLAUDE_TOOL_NAME:-}"
-TOOL_INPUT="\${CLAUDE_TOOL_INPUT:-}"
+# Read hook input from stdin (Claude Code sends JSON)
+HOOK_INPUT=$(cat)
+TOOL_NAME=$(echo "$HOOK_INPUT" | sed -n 's/.*"tool_name":"\\([^"]*\\)".*/\\1/p')
+
+# Extract actionable string based on tool type
+# Uses [^"]* to stop at the first unescaped quote — safely ignores other JSON fields
+if [ "$TOOL_NAME" = "Bash" ]; then
+  TOOL_INPUT=$(echo "$HOOK_INPUT" | sed -n 's/.*"command":"\\([^"]*\\)".*/\\1/p')
+else
+  TOOL_INPUT=$(echo "$HOOK_INPUT" | sed -n 's/.*"file_path":"\\([^"]*\\)".*/\\1/p')
+fi
 
 # === Hard blocks (all profiles) ===
 
@@ -157,11 +167,14 @@ export function generateAuditLogHook() {
   return `#!/usr/bin/env bash
 # Post-tool-use audit hook — generated by claudenv autonomy
 # Logs every tool invocation to .claude/audit-log.jsonl
+# Claude Code sends hook data via stdin as JSON: {"tool_name":"...","tool_input":{...}}
 
 set -uo pipefail
 
-TOOL_NAME="\${CLAUDE_TOOL_NAME:-unknown}"
-TOOL_INPUT="\${CLAUDE_TOOL_INPUT:-}"
+# Read hook input from stdin (Claude Code sends JSON)
+HOOK_INPUT=$(cat)
+TOOL_NAME=$(echo "$HOOK_INPUT" | sed -n 's/.*"tool_name":"\\([^"]*\\)".*/\\1/p')
+TOOL_INPUT=$(echo "$HOOK_INPUT" | sed -n 's/.*"tool_input":\\(.*\\)/\\1/p' | sed 's/}$//')
 SESSION_ID="\${CLAUDE_SESSION_ID:-}"
 
 # Truncate input for logging (max 500 chars)

package/src/installer.js

@@ -92,6 +92,7 @@ export async function uninstallGlobal(options = {}) {
 
   const targets = [
     join(targetBase, 'commands', 'claudenv.md'),
+    join(targetBase, 'commands', 'autonomy.md'),
     join(targetBase, 'commands', 'setup-mcp.md'),
     join(targetBase, 'commands', 'improve.md'),
     join(targetBase, 'skills', 'claudenv'),

package/src/loop.js

@@ -1,9 +1,22 @@
 import { execSync, spawn } from 'node:child_process';
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { readFile, writeFile, mkdir, appendFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { select } from '@inquirer/prompts';
 import { createWorktree, removeWorktree, mergeWorktree, getCurrentBranch } from './worktree.js';
 
+// =============================================
+// Work report helpers
+// =============================================
+
+/**
+ * Append a report event to .claude/work-report.jsonl
+ */
+async function writeReportEvent(cwd, event) {
+  const line = JSON.stringify({ ts: new Date().toISOString(), ...event }) + '\n';
+  await mkdir(join(cwd, '.claude'), { recursive: true });
+  await appendFile(join(cwd, '.claude', 'work-report.jsonl'), line);
+}
+
 // =============================================
 // Pre-flight: check Claude CLI
 // =============================================
@@ -68,16 +81,22 @@ export function spawnClaude(prompt, options = {}) {
 
     const child = spawn('claude', args, {
       cwd: options.cwd || process.cwd(),
-      // stdin=inherit avoids Node.js spawn hang bug, stdout=pipe to capture JSON, stderr=inherit for real-time output
-      stdio: ['inherit', 'pipe', 'inherit'],
+      // stdin=inherit avoids Node.js spawn hang bug, stdout=pipe to capture JSON, stderr=pipe for rate limit detection
+      stdio: ['inherit', 'pipe', 'pipe'],
     });
 
     let stdout = '';
+    let stderrBuf = '';
 
     child.stdout.on('data', (chunk) => {
       stdout += chunk.toString();
     });
 
+    child.stderr.on('data', (chunk) => {
+      process.stderr.write(chunk); // keep real-time output
+      stderrBuf += chunk.toString();
+    });
+
     child.on('error', (err) => {
       if (err.code === 'ENOENT') {
         reject(new Error('Claude CLI not found. Install it from https://docs.anthropic.com/en/docs/claude-code'));
@@ -88,7 +107,10 @@ export function spawnClaude(prompt, options = {}) {
 
     child.on('close', (code) => {
       if (code !== 0) {
-        reject(new Error(`Claude exited with code ${code}`));
+        const isRateLimit = /rate.?limit|429|overloaded|too many requests/i.test(stderrBuf);
+        const err = new Error(`Claude exited with code ${code}`);
+        err.isRateLimit = isRateLimit;
+        reject(err);
         return;
       }
 
@@ -450,6 +472,8 @@ function printFinalSummary(log) {
  * @param {string} [options.cwd] - Working directory
  * @param {boolean} [options.allowDirty] - Allow dirty git state
  * @param {boolean} [options.worktree] - Run each iteration in an isolated git worktree
+ * @param {number} [options.startIteration] - Resume from this iteration (skip planning)
+ * @param {string} [options.initialSessionId] - Session ID to resume from
  */
 export async function runLoop(options = {}) {
   const cwd = options.cwd || process.cwd();
@@ -480,18 +504,19 @@ export async function runLoop(options = {}) {
   console.log(`\n  Git safety tag: ${gitTag}`);
   console.log(`  Pre-loop commit: ${preLoopCommit}`);
 
-  // --- Initialize loop log ---
+  // --- Initialize loop log (carry over previous data on resume) ---
+  const prevLogData = startIteration > 0 ? await readLoopLog(cwd) : null;
   const log = {
-    started: new Date().toISOString(),
+    started: prevLogData?.started || new Date().toISOString(),
     goal: options.goal || 'General improvement',
-    model: options.model || 'sonnet',
-    gitTag,
-    preLoopCommit,
-    iterations: [],
+    model: options.model || null,
+    gitTag: prevLogData?.gitTag || gitTag,
+    preLoopCommit: prevLogData?.preLoopCommit || preLoopCommit,
+    iterations: prevLogData?.iterations || [],
     completedAt: null,
     stopReason: null,
-    totalIterations: 0,
-    hypotheses: [],
+    totalIterations: prevLogData?.totalIterations || 0,
+    hypotheses: prevLogData?.hypotheses || [],
   };
 
   // --- Shared spawn options ---
@@ -505,8 +530,9 @@ export async function runLoop(options = {}) {
     appendSystemPrompt: options.goal ? buildAutonomySystemPrompt(options.goal) : undefined,
   };
 
-  let sessionId = null;
+  let sessionId = options.initialSessionId || null;
   let shuttingDown = false;
+  const startIteration = options.startIteration || 0;
 
   // --- Ctrl+C handling ---
   const sigintHandler = () => {
@@ -521,37 +547,59 @@ export async function runLoop(options = {}) {
   process.on('SIGINT', sigintHandler);
 
   try {
-    // --- Iteration 0: Planning ---
-    console.log('\n  Starting iteration 0 (planning)...\n');
-
-    const planPrompt = buildPlanningPrompt(options.goal);
-    const planResult = await spawnClaude(planPrompt, { ...spawnOpts, sessionId });
-    sessionId = planResult.sessionId || sessionId;
-
-    const planIteration = {
-      number: 0,
-      startedAt: log.started,
-      completedAt: new Date().toISOString(),
-      sessionId,
-      summary: 'Generated improvement plan',
-      commitHash: getCurrentCommit(cwd),
-      usage: planResult.usage,
-    };
-    log.iterations.push(planIteration);
-    printIterationSummary(planIteration);
-    await writeLoopLog(cwd, log);
+    // --- Report: loop start ---
+    await writeReportEvent(cwd, {
+      event: 'loop_start',
+      goal: options.goal || 'General improvement',
+      model: options.model || null,
+      gitTag,
+      resume: startIteration > 0,
+    });
 
-    if (shuttingDown) {
-      log.stopReason = 'interrupted';
-      log.completedAt = new Date().toISOString();
-      log.totalIterations = 0;
+    // --- Iteration 0: Planning (skip if resuming) ---
+    if (startIteration === 0) {
+      console.log('\n  Starting iteration 0 (planning)...\n');
+      await writeReportEvent(cwd, { event: 'iteration_start', iteration: 0, type: 'planning' });
+
+      const planPrompt = buildPlanningPrompt(options.goal);
+      const planResult = await spawnClaude(planPrompt, { ...spawnOpts, sessionId });
+      sessionId = planResult.sessionId || sessionId;
+
+      const planIteration = {
+        number: 0,
+        startedAt: log.started,
+        completedAt: new Date().toISOString(),
+        sessionId,
+        summary: 'Generated improvement plan',
+        commitHash: getCurrentCommit(cwd),
+        usage: planResult.usage,
+      };
+      log.iterations.push(planIteration);
+      printIterationSummary(planIteration);
       await writeLoopLog(cwd, log);
-      printFinalSummary(log);
-      return;
+      await writeReportEvent(cwd, {
+        event: 'iteration_end',
+        iteration: 0,
+        summary: 'Generated improvement plan',
+        commitHash: planIteration.commitHash,
+        tokens: planResult.usage ? { in: planResult.usage.input_tokens, out: planResult.usage.output_tokens } : null,
+      });
+
+      if (shuttingDown) {
+        log.stopReason = 'interrupted';
+        log.completedAt = new Date().toISOString();
+        log.totalIterations = 0;
+        await writeLoopLog(cwd, log);
+        printFinalSummary(log);
+        return;
+      }
+    } else {
+      console.log(`\n  Resuming from iteration ${startIteration}...\n`);
     }
 
-    // --- Execution iterations 1-N ---
-    for (let i = 1; i <= maxIterations; i++) {
+    // --- Execution iterations 1-N (or startIteration-N if resuming) ---
+    const firstIter = startIteration > 0 ? startIteration : 1;
+    for (let i = firstIter; i <= maxIterations; i++) {
       if (shuttingDown) break;
 
       // --- Pause between iterations ---
@@ -607,11 +655,12 @@ export async function runLoop(options = {}) {
         }
       }
 
+      await writeReportEvent(cwd, { event: 'iteration_start', iteration: i, type: 'execution' });
+
       let iterResult;
       try {
         iterResult = await spawnClaude(execPrompt, { ...spawnOpts, cwd: iterCwd, sessionId });
       } catch (err) {
-        console.error(`\n  Iteration ${i} failed: ${err.message}`);
         // In worktree mode, clean up the worktree on failure
         if (worktreeInfo) {
           try {
@@ -624,6 +673,26 @@ export async function runLoop(options = {}) {
             iteration: i,
           });
         }
+
+        // Rate limit detection — save state for resume
+        if (err.isRateLimit) {
+          log.stopReason = 'rate_limit';
+          log.pausedAt = { iteration: i, sessionId };
+          log.options = {
+            goal: options.goal,
+            model: options.model,
+            trust: options.trust,
+            maxTurns: options.maxTurns,
+            budget: options.budget,
+            worktree: options.worktree,
+          };
+          await writeLoopLog(cwd, log);
+          await writeReportEvent(cwd, { event: 'rate_limit', iteration: i, message: err.message });
+          console.log(`\n  Rate limited at iteration ${i}. Resume with: claudenv loop --resume`);
+          break;
+        }
+
+        console.error(`\n  Iteration ${i} failed: ${err.message}`);
         log.stopReason = 'error';
         break;
       }
@@ -696,6 +765,13 @@ export async function runLoop(options = {}) {
       log.totalIterations = i;
       printIterationSummary(iteration);
       await writeLoopLog(cwd, log);
+      await writeReportEvent(cwd, {
+        event: 'iteration_end',
+        iteration: i,
+        summary: iteration.summary,
+        commitHash: iteration.commitHash,
+        tokens: iterResult.usage ? { in: iterResult.usage.input_tokens, out: iterResult.usage.output_tokens } : null,
+      });
 
       // --- Convergence check ---
       if (detectConvergence(iterResult.result)) {
@@ -740,6 +816,11 @@ export async function runLoop(options = {}) {
 
   log.completedAt = new Date().toISOString();
   await writeLoopLog(cwd, log);
+  await writeReportEvent(cwd, {
+    event: 'loop_end',
+    reason: log.stopReason,
+    totalIterations: log.totalIterations,
+  });
   printFinalSummary(log);
 }
 

package/src/profiles.js

@@ -18,6 +18,7 @@ export const AUTONOMY_PROFILES = {
   safe: {
     name: 'safe',
     description: 'Read-only + limited bash — safe for exploration',
+    model: 'sonnet',
     allowedTools: [
       'Read',
       'Glob',
@@ -41,6 +42,7 @@ export const AUTONOMY_PROFILES = {
   moderate: {
     name: 'moderate',
     description: 'Full development with deny-list — safe for most development work',
+    model: 'sonnet',
     allowedTools: [
       'Read',
       'Edit',
@@ -72,6 +74,7 @@ export const AUTONOMY_PROFILES = {
   full: {
     name: 'full',
     description: 'Full autonomy — unrestricted access with audit logging',
+    model: 'opus',
     allowedTools: [],
     disallowedTools: [],
     skipPermissions: true,
@@ -81,6 +84,7 @@ export const AUTONOMY_PROFILES = {
   ci: {
     name: 'ci',
     description: 'Headless CI/CD mode — full autonomy with turn/budget limits',
+    model: 'haiku',
     allowedTools: [],
     disallowedTools: [],
     skipPermissions: true,

package/src/report.js

@@ -0,0 +1,160 @@
+// =============================================
+// Work report reader/formatter/watcher
+// =============================================
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { createReadStream, watch, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const REPORT_FILE = '.claude/work-report.jsonl';
+
+/**
+ * Read all report events from the JSONL file.
+ * @param {string} cwd - Working directory
+ * @returns {Promise<Array<object>>}
+ */
+export async function readReport(cwd) {
+  try {
+    const content = await readFile(join(cwd, REPORT_FILE), 'utf-8');
+    return content
+      .split('\n')
+      .filter((line) => line.trim())
+      .map((line) => {
+        try {
+          return JSON.parse(line);
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Format report events as a human-readable timeline.
+ * @param {Array<object>} events
+ * @returns {string}
+ */
+export function formatReport(events) {
+  if (events.length === 0) return '  No report events found.\n';
+
+  const lines = [];
+  lines.push('  Work Report');
+  lines.push(`  ${'─'.repeat(50)}`);
+
+  for (const ev of events) {
+    const time = ev.ts ? new Date(ev.ts).toLocaleTimeString() : '??:??:??';
+    switch (ev.event) {
+      case 'loop_start':
+        lines.push(`  ${time}  LOOP START`);
+        lines.push(`           Goal: ${ev.goal || 'General improvement'}`);
+        if (ev.model) lines.push(`           Model: ${ev.model}`);
+        if (ev.gitTag) lines.push(`           Tag: ${ev.gitTag}`);
+        break;
+
+      case 'iteration_start':
+        lines.push(`  ${time}  ITERATION ${ev.iteration} start${ev.type ? ` (${ev.type})` : ''}`);
+        break;
+
+      case 'iteration_end':
+        lines.push(`  ${time}  ITERATION ${ev.iteration} done`);
+        if (ev.summary) lines.push(`           ${ev.summary.slice(0, 120)}`);
+        if (ev.commitHash) lines.push(`           Commit: ${ev.commitHash}`);
+        if (ev.tokens) lines.push(`           Tokens: ${ev.tokens.in || 0} in / ${ev.tokens.out || 0} out`);
+        break;
+
+      case 'rate_limit':
+        lines.push(`  ${time}  RATE LIMITED at iteration ${ev.iteration}`);
+        if (ev.message) lines.push(`           ${ev.message}`);
+        break;
+
+      case 'loop_end':
+        lines.push(`  ${time}  LOOP END — ${ev.reason || 'unknown'} (${ev.totalIterations || '?'} iterations)`);
+        break;
+
+      default:
+        lines.push(`  ${time}  ${ev.event || 'unknown'}`);
+    }
+    lines.push('');
+  }
+
+  lines.push(`  ${'─'.repeat(50)}`);
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Format a single event as a compact one-line string (for follow/watch mode).
+ * @param {object} ev
+ * @returns {string}
+ */
+export function formatEventLine(ev) {
+  const time = ev.ts ? new Date(ev.ts).toLocaleTimeString() : '??:??:??';
+  switch (ev.event) {
+    case 'loop_start':
+      return `  ${time}  LOOP START — ${ev.goal || 'General improvement'}${ev.model ? ` [${ev.model}]` : ''}\n`;
+    case 'iteration_start':
+      return `  ${time}  ITERATION ${ev.iteration} start${ev.type ? ` (${ev.type})` : ''}\n`;
+    case 'iteration_end': {
+      let line = `  ${time}  ITERATION ${ev.iteration} done`;
+      if (ev.commitHash) line += ` [${ev.commitHash}]`;
+      if (ev.tokens) line += ` (${ev.tokens.in || 0}/${ev.tokens.out || 0} tokens)`;
+      line += '\n';
+      if (ev.summary) line += `           ${ev.summary.slice(0, 120)}\n`;
+      return line;
+    }
+    case 'rate_limit':
+      return `  ${time}  RATE LIMITED at iteration ${ev.iteration}${ev.message ? ` — ${ev.message}` : ''}\n`;
+    case 'loop_end':
+      return `  ${time}  LOOP END — ${ev.reason || 'unknown'} (${ev.totalIterations || '?'} iterations)\n`;
+    default:
+      return `  ${time}  ${ev.event || 'unknown'}\n`;
+  }
+}
+
+/**
+ * Watch the report file for new events and call cb for each.
+ * @param {string} cwd - Working directory
+ * @param {function} cb - Callback receiving each new event object
+ * @returns {{ close: function }} Watcher handle
+ */
+export async function watchReport(cwd, cb) {
+  const filePath = join(cwd, REPORT_FILE);
+  let position = 0;
+
+  // Ensure the file exists (watch throws on non-existent files)
+  try {
+    const { size } = statSync(filePath);
+    position = size;
+  } catch {
+    await mkdir(join(cwd, '.claude'), { recursive: true });
+    await writeFile(filePath, '');
+  }
+
+  const watcher = watch(filePath, () => {
+    // On change, read new lines from last position
+    const stream = createReadStream(filePath, { start: position, encoding: 'utf-8' });
+    let buffer = '';
+
+    stream.on('data', (chunk) => {
+      buffer += chunk;
+      position += Buffer.byteLength(chunk, 'utf-8');
+    });
+
+    stream.on('end', () => {
+      const lines = buffer.split('\n').filter((l) => l.trim());
+      for (const line of lines) {
+        try {
+          cb(JSON.parse(line));
+        } catch {
+          // skip malformed lines
+        }
+      }
+    });
+  });
+
+  return {
+    close: () => watcher.close(),
+  };
+}