claudenv 1.2.4 → 1.3.0

package/README.md

@@ -1,6 +1,10 @@
 # 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.
+[![npm](https://img.shields.io/npm/v/claudenv.svg)](https://www.npmjs.com/package/claudenv)
+
+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, slash commands, **plus cross-session memory and vibe-decisions logging (1.3.0).**
+
+> **New in 1.3.0** — split memory layout (`~/.claudenv/memories/` global + `.claude/memories/` project), `vibe-decisions` skill (auto-log in loop, pause-and-ask interactive), new CLI: `memory`, `decisions`, `canon`, `doctor`. Companion Python package `claudenv-memory` on PyPI (alpha). See [CHANGELOG.md](./CHANGELOG.md).
 
 ## Quick Start
 
@@ -8,244 +12,308 @@ 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.
+
+## What happens when you run `/claudenv`
+
+Claude reads your code, asks a few questions, and generates:
+
+- **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`, **`/deeper`**, **`/why`**, **`/decisions`**, **`/canon`**, **`/just-code`** (1.3.0)
+- **Hooks** — validation on tool use, audit logging, decisions-logger (PostToolUse Write), regen-index (SessionEnd) — `.claude/settings.json`
+
+Everything is committed to your repo. Team members get the same Claude experience.
 
-## How It Works
+## Autonomous Loop
 
-**One-time setup** — install and activate:
+The killer feature. `claudenv loop` runs Claude in headless mode, iterating over your project — planning improvements, implementing them one by one, committing each step.
 
 ```bash
-npm i -g claudenv && claudenv
+claudenv loop --goal "add test coverage" --trust -n 5
 ```
 
-This installs the `/claudenv` command globally into `~/.claude/`, making it available in every project.
+**What it does:**
 
-**In any project** — open Claude Code and type `/claudenv`.
+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
 
-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
+### Common recipes
 
-You now have five commands available in Claude Code:
+```bash
+# Interactive mode — pauses between iterations so you can review
+claudenv 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 |
+# Fully autonomous — no pauses, no permission prompts
+claudenv loop --trust
 
-## What Gets Generated
+# Goal-driven with Opus for max capability
+claudenv loop --goal "refactor auth to JWT" --trust --model opus -n 3
 
-```
-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
+# Budget-conscious CI run
+claudenv loop --profile ci --goal "fix lint errors" -n 10
+
+# Undo everything from the last loop
+claudenv loop --rollback
 ```
 
-### Key Files
+### Rate limit recovery
 
-| 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 |
+If Claude hits API rate limits mid-loop, claudenv saves your progress automatically:
 
-## MCP Server Recommendations
+```bash
+# Rate limited? Just resume where you left off
+claudenv loop --resume
 
-`/claudenv` automatically recommends MCP servers based on your tech stack. You can also run `/setup-mcp` independently at any time.
+# Override model on resume (e.g., switch to cheaper model)
+claudenv loop --resume --model sonnet
+```
 
-**How it works:**
+### Live progress tracking
 
-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
+Monitor what Claude is doing in real time:
 
-**Example output** (`.mcp.json`):
+```bash
+# In another terminal — tail -f style
+claudenv report --follow
 
-```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": {}
-    }
-  }
-}
+# Summary of the last loop run
+claudenv report
+
+# Last 5 events only
+claudenv report --last 5
 ```
 
-Secrets use `${ENV_VAR}` placeholders — configure them with:
+Events are stored in `.claude/work-report.jsonl` — machine-readable JSONL format.
+
+### All loop flags
+
+| Flag | Description |
+|------|-------------|
+| `--goal <text>` | What to work on (any goal — Claude interprets it) |
+| `--trust` | Full trust mode — no pauses, skip permission prompts |
+| `-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 |
+| `--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 |
+| `--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 |
+
+## Autonomy Profiles
+
+Control how much freedom Claude gets. Profiles configure permissions, hooks, model defaults, and safety guardrails.
 
 ```bash
-claude config set env.POSTGRES_CONNECTION_STRING "postgresql://..."
+claudenv autonomy                          # Interactive selection
+claudenv autonomy --profile moderate       # Apply directly
+claudenv autonomy --profile ci --dry-run   # Preview without writing
 ```
 
-`.mcp.json` is safe to commit — it never contains actual secrets.
+### Profile comparison
 
-Run `/setup-mcp --force` to auto-select Essential + Recommended servers without prompting.
+| 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 |
 
-## Iterative Improvement Loop
+All profiles hard-block `rm -rf`, force push to main/master, and `sudo` — regardless of permission settings.
 
-`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.
+### What gets generated
 
-**How it works:**
+```
+.claude/
+├── settings.json          # Permissions, hooks config
+├── hooks/
+│   ├── 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`.
 
-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
+### Using profiles with the loop
 
-**Usage:**
+Profiles set sensible defaults for model, trust, and budget:
 
 ```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
-```
+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
 
-| Flag | Description |
-|------|-------------|
-| `-n, --iterations <n>` | Max iterations (default: unlimited) |
-| `--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) |
-| `--budget <usd>` | Budget cap per iteration in USD |
-| `-d, --dir <path>` | Target project directory |
-| `--allow-dirty` | Allow running with uncommitted changes |
-| `--rollback` | Undo all changes from the most recent loop |
-| `--unsafe` | Remove default tool restrictions |
+# CLI flags always override profile defaults
+claudenv loop --profile ci --model sonnet              # ci profile but with sonnet
+```
 
-**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.
+## Memory & vibe-decisions (1.3.0)
 
-**Single iteration:** Use `/improve` inside Claude Code for a one-shot improvement without the full loop.
+Persistent memory across sessions + brief overview before non-trivial technical choices. Auto-log inside `claudenv loop` (no pauses — `autonomy=law`), pause-and-ask in interactive Claude Code chats.
 
-## Autonomous Agent Mode
+### Layout (split)
 
-`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).
+```
+~/.claudenv/memories/              # global, cross-project
+├── INDEX.md                       # briefing — auto-regenerated
+├── decisions/                     # universal tech decisions
+├── canon/index.yaml               # personal canon of references
+└── user/preferences.md            # cross-project preferences
+
+<project>/.claude/memories/        # project-scoped, committed
+├── project.md                     # stack, conventions, internal urls
+└── decisions/                     # project-only decisions
+```
 
-**Usage:**
+### Commands
 
 ```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
+# Memory
+claudenv memory init                     # initialise ~/.claudenv/memories/
+claudenv memory index                    # regenerate INDEX.md
+claudenv memory show <path>              # print a memory file
+claudenv memory edit <path>              # open in $EDITOR
+
+# Decisions
+claudenv decisions list [--scope all|global|project] [--limit N]
+claudenv decisions show <id-or-slug>
+claudenv decisions search <query>
+claudenv decisions archive <id>
+
+# Canon
+claudenv canon add <topic> <url> --why "<reason>" [--title <t>] [--author <a>]
+claudenv canon list [<topic>]
+claudenv canon search <query>
+claudenv canon prune --months 6          # find stale entries
+
+# Health
+claudenv doctor                          # OK/WARN/FAIL check
 ```
 
-### Profiles
+### Slash-commands (in Claude Code session)
+
+| Command | Purpose |
+|---|---|
+| `/deeper` | Develop the most recent decision into a full deep dive (concept → variants → trade-offs → canon) |
+| `/why <X>` | Explain technology X without logging a decision |
+| `/decisions` | List/search logged decisions via the CLI |
+| `/canon` | Browse the personal canon |
+| `/just-code` | Suppress vibe-decisions overview for the next response only |
 
-| 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 |
+### How auto-log works in `claudenv loop`
 
-All profiles hard-block `rm -rf`, force push to main/master, and `sudo`.
+`claudenv loop` appends a system-prompt fragment that switches the `vibe-decisions` skill into **auto-log mode** — it picks the approach, writes the decision file (`/memories/decisions/<date>-<slug>.md`), and continues coding without pausing. Outside loop (interactive Claude Code) the skill defaults to **pause-and-ask** mode.
 
-### Generated files
+After each iteration, `claudenv loop` regenerates `INDEX.md` so the next iteration's briefing reflects what was just decided.
 
+### Python companion: `claudenv-memory`
+
+Building your own agent on Claude Agent SDK and want the same memory layout?
+
+```bash
+pip install claudenv-memory
 ```
-.claude/
-├── 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
+
+```python
+from claudenv_memory import LocalFileMemoryBackend
+from claude_agent_sdk import ClaudeAgentOptions
+
+backend = LocalFileMemoryBackend()  # ~/.claudenv/memories + ./.claude/memories
+options = ClaudeAgentOptions(
+    model="claude-opus-4-7",
+    extra_headers={"anthropic-beta": "context-management-2025-06-27"},
+    tools=[backend.as_tool()],
+)
 ```
 
-CI profile also generates `.github/workflows/claude-ci.yml`.
+Status: 0.1.x alpha — first production consumer is claudenv 2.0. See `python/README.md`.
 
-### Loop integration
+## MCP Server Setup
 
-Use `--profile` with `claudenv loop` to apply profile settings:
+`/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.
 
-```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
+Servers are configured in `.mcp.json` with `${ENV_VAR}` placeholders — safe to commit:
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    },
+    "postgres": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-postgres@latest", "${POSTGRES_CONNECTION_STRING}"]
+    }
+  }
+}
 ```
 
-| 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 |
+Set secrets with `claude config set env.POSTGRES_CONNECTION_STRING "postgresql://..."`.
 
-## Tech Stack Detection
+## File Structure
 
-Claude AI reads your actual code, but the following are auto-detected for context:
+After full setup (`/claudenv` + `claudenv autonomy`):
 
-- **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
+```
+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
+
+claudenv memory init|index|show|edit  Manage ~/.claudenv/memories/ (1.3.0+)
+claudenv decisions list|show|search   Logged vibe-decisions (1.3.0+)
+claudenv canon add|list|search|prune  Personal canon (1.3.0+)
+claudenv doctor                       Health check (1.3.0+)
 ```
 
-## Alternative: Run Without Installing
+## Run Without Installing
 
 ```bash
 npx claudenv            # npm
@@ -253,12 +321,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