Set up 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-decisionsskill (auto-log in loop, pause-and-ask interactive), new CLI:memory,decisions,canon,doctor. Companion Python packageclaudenv-memoryon PyPI (alpha). See CHANGELOG.md.
npm i -g claudenv && claudenvOpen Claude Code in any project and type /claudenv. That's it.
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.
The killer feature. claudenv loop runs Claude in headless mode, iterating over your project — planning improvements, implementing them one by one, committing each step.
claudenv loop --goal "add test coverage" --trust -n 5What it does:
- Creates a git safety tag (rollback anytime with
--rollback) - Claude generates an improvement plan (
.claude/improvement-plan.md) - Each iteration picks the next item, implements it, runs tests, commits
- Stops when the plan is done, iterations run out, or it detects it's stuck
# Interactive mode — pauses between iterations so you can review
claudenv loop
# Fully autonomous — no pauses, no permission prompts
claudenv loop --trust
# Goal-driven with Opus for max capability
claudenv loop --goal "refactor auth to JWT" --trust --model opus -n 3
# Budget-conscious CI run
claudenv loop --profile ci --goal "fix lint errors" -n 10
# Undo everything from the last loop
claudenv loop --rollbackIf Claude hits API rate limits mid-loop, claudenv saves your progress automatically:
# Rate limited? Just resume where you left off
claudenv loop --resume
# Override model on resume (e.g., switch to cheaper model)
claudenv loop --resume --model sonnetMonitor what Claude is doing in real time:
# In another terminal — tail -f style
claudenv report --follow
# Summary of the last loop run
claudenv report
# Last 5 events only
claudenv report --last 5Events are stored in .claude/work-report.jsonl — machine-readable JSONL format.
| 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 |
Control how much freedom Claude gets. Profiles configure permissions, hooks, model defaults, and safety guardrails.
claudenv autonomy # Interactive selection
claudenv autonomy --profile moderate # Apply directly
claudenv autonomy --profile ci --dry-run # Preview without writing| 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 — regardless of permission settings.
.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.
Profiles set sensible defaults for model, trust, and 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 sonnetPersistent 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.
~/.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
# 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| 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 |
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.
After each iteration, claudenv loop regenerates INDEX.md so the next iteration's briefing reflects what was just decided.
Building your own agent on Claude Agent SDK and want the same memory layout?
pip install claudenv-memoryfrom 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()],
)Status: 0.1.x alpha — first production consumer is claudenv 2.0. See python/README.md.
/claudenv auto-detects your tech stack and recommends MCP servers from the official registry. You can also run /setup-mcp independently.
Servers are configured in .mcp.json with ${ENV_VAR} placeholders — safe to commit:
{
"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://...".
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
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+)
npx claudenv # npm
pnpm dlx claudenv # pnpm
bunx claudenv # bunAuto-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.
- Node.js >= 20
- Claude Code CLI
MIT