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, cross-session memory, and a self-extending harness that equips Claude with new skills on demand (1.3.2).
New in 1.3.2 — self-extending harness. Claude can now introspect what claudenv gives it (
claudenv capabilities), find what's missing for the task, and equip it from the awesome-claude-skills registry (claudenv skills search|add) — plus first-class kimi-webbridge browser automation. New/harnesscommand + skill drive it autonomously. See CHANGELOG.md.1.3.0 — split memory layout,
vibe-decisionsskill, CLI:memory,decisions,canon,doctor. Companion Python packageclaudenv-memoryon PyPI (alpha).
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.
claudenv is Claude's harness — a CLI plus skills, connectors, memory, and a
browser bridge. The harness skill makes Claude self-aware of it and lets it
extend itself: understand what it already has, find what's missing for the
task, and equip it — autonomously.
claudenv capabilities # self-introspection: skills, memory, workspace,
# connectors, kimi-webbridge, MCP, registry
claudenv skills search "pdf" # find a skill (curated + awesome-claude-skills)
claudenv skills add docx # install it into ~/.claude/skills/
claudenv skills add kimi-webbridge # bootstrap browser automationIn Claude Code, /harness (or just describe a task that needs a capability you
lack) runs the whole flow: introspect → gap-analysis → discover → equip →
configure connectors/MCP/memory → bootstrap the browser.
claudenv skills discovers skills from
awesome-claude-skills. The
registry is a heterogeneous markdown README, so each entry is resolved by install
class:
| Class | Example | Behavior |
|---|---|---|
repo-path |
github.com/anthropics/skills/tree/main/skills/docx |
fetch raw SKILL.md |
in-repo |
a ./folder/ link in the README |
fetch from the awesome repo |
repo-root |
github.com/user/skill |
best-effort probe, else guide |
bootstrap |
kimi-webbridge | run an install command (e.g. install.sh) |
guide |
a vendor dashboard / Composio connector | open the link to set up |
A curated bundled catalog ships with claudenv, so search/add work
offline; claudenv skills refresh parses and caches the live registry.
A fetched SKILL.md is auto-loaded, model-facing instruction text — a
prompt-injection surface. So:
- Curated (★) entries have a vetted source URL + install class (the bytes are
fetched live, not content-pinned) → the only entries allowed to auto-equip,
including inside
claudenv loop. - Live entries (parsed from the README or a raw URL) are gated in code:
skills addwrites nothing without--yes.claudenv loopnever passes it.
skills add only ever writes under ~/.claude/skills/<slug>/, never overwrites
without --force, validates the body, and never executes fetched content.
Bootstrap installers are printed first and run only with --yes.
claudenv skills add kimi-webbridge makes browser automation work even if it
isn't installed yet — it detects an existing daemon and starts it, or surfaces the
official bootstrap. claudenv capabilities and claudenv doctor report its
health. Once up, Claude drives your real browser (with your login sessions) via
the kimi-webbridge skill.
/claudenv installs a dynamic-workflows skill that teaches Claude when to reach for the built-in Workflow tool — deterministic multi-agent orchestration (fan-out, pipelines, adversarial-verify, multi-file migrations) — and when to stay single-threaded. It triggers on wide, decomposable work (reviewing/migrating across many files, research over many sources, generate-N-then-judge) and stays out of the way for single-file or sequential edits.
claudenv loop drives the same capability: alongside the no-pause loop-mode fragment, it injects a guarded Parallel decomposition directive into the execution prompt that tells the loop to run a dynamic workflow when the picked plan item splits into 3+ independent sub-tasks (and to stay single-threaded otherwise). Fan-out is hard-capped (multi-agent work costs ~15× the tokens and runs under the per-iteration budget); if the Workflow runtime is unavailable it degrades to parallel Agent calls. The directive lives in the user prompt because the Workflow tool's opt-in keys on the user message — a system-prompt hint alone won't trigger it.
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+)
claudenv workspace add|list|use|show Isolated per-company memory spaces (1.3.1+)
claudenv source list|show Data-source connectors of active workspace (1.3.1+)
claudenv capabilities [--json] [-d <dir>] Self-introspection map (1.3.2+)
claudenv skills search <query> Find skills (curated + awesome-claude-skills) (1.3.2+)
claudenv skills list Skills installed under ~/.claude/skills/ (1.3.2+)
claudenv skills info <name> Trust level, install class, source (1.3.2+)
claudenv skills add <name> [--force] Install a skill (--yes to run bootstraps) (1.3.2+)
claudenv skills refresh Refetch the live registry into cache (1.3.2+)
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