evolving-claude

A self-improving global Claude Code setup that turns Claude into a disciplined AI software engineer.

Not a pile of prompts — a system. Ten specialized subagents with deliberate model routing, on-demand skills, deterministic safety hooks, a three-tier memory model, and a feedback loop that lets the configuration improve itself as you work.

The idea in one picture

Context is the scarce resource. Every part of this setup exists to keep the main conversation lean and let Claude do focused, verifiable work:

• Subagents do heavy/isolated work in their own context so the main thread stays clean.
• Skills load procedures on demand instead of bloating always-on instructions.
• Hooks enforce safety and formatting deterministically — no LLM judgment needed.
• Memory persists learnings across sessions and projects.
• A self-improvement loop captures friction during real work and folds fixes back into the config.

What's inside

10 subagents (agents/) with cost-aware model routing

8 skills (skills/) — manual /commands

• init-project — detects one of four project states (empty / unconfigured / skeleton / configured) and scaffolds tailored project config, interviewing you via the planner.
• update-config — the self-improvement loop: reviews the friction queue and evolves this config.
• commit, open-pr, fix-issue — git-host-aware (gh vs glab).
• review-diff, tdd, onboard-codebase — quality & understanding workflows.

Hooks (hooks/)

• block-dangerous.sh — blocks rm -rf /, force-push to protected branches, curl-pipe-to-shell.
• guard-secrets.sh — refuses to write secret files.
• format-on-edit.sh — auto-formats edited files (no-op if the formatter isn't installed).
• project-bootstrap.sh — detects project config state at session start and suggests setup.
• config-review-queue.sh — append-only friction log (survives /clear and /compact).
• statusline.sh — model + branch + context-usage in the status line.

Three-tier memory

1. Project memory — <repo>/.claude/memory/PROJECT.md (stack, commands, gotchas).
2. Per-agent project memory — <repo>/.claude/memory/agents/<agent>/NOTES.md.
3. Global agent memory — ~/.claude/agent-memory/<agent>/ for cross-project style.

All AI memory lives under .claude/memory/ — docs/ stays human-only.

Install

# Back up any existing config first
mv ~/.claude ~/.claude.bak 2>/dev/null || true

git clone https://github.com/ZaaliMohamed123/evolving-claude ~/.claude
cd ~/.claude

# Copy the settings template and set your hook paths
cp settings.example.json settings.json
# edit settings.json: replace /home/USER/ in the hook paths with your home directory

chmod +x hooks/*.sh

The template ships only permissions, hooks, and the status line — no auth or model config, since a normal Pro/Max or API-key user doesn't need it. Just log in with claude (or your ANTHROPIC_API_KEY) as usual.

Custom gateway? If you route through a proxy like LiteLLM, add your own env block (ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, model aliases) to your local settings.json — it's git-ignored, so it stays private.

Recommended tooling

The agents and hooks use these CLIs when present, and fall back gracefully when they're not. Installing them makes exploration faster and cheaper (they respect .gitignore and are far quicker than the built-in search).

# Debian / Ubuntu
sudo apt-get update && sudo apt-get install -y ripgrep fd-find tree
# fd is called 'fdfind' on Debian/Ubuntu — add a friendlier alias:
mkdir -p ~/.local/bin && ln -sf "$(command -v fdfind)" ~/.local/bin/fd

# macOS (Homebrew)
brew install ripgrep fd tree

# GitHub CLI:  https://cli.github.com   ·   GitLab CLI: https://gitlab.com/gitlab-org/cli

Optional MCP servers

Two MCPs add capabilities no CLI provides. Everything else is intentionally left to CLIs to keep context lean. Add them at user scope so they're available in every project:

# Structured multi-step reasoning for hard problems
claude mcp add --scope user sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking

# Real browser control for UI verification / E2E checks
claude mcp add --scope user playwright -- npx -y @playwright/mcp@latest

Verify with claude mcp list.

Design principles

• Context is scarce — delegate, load on demand, enforce deterministically.
• Prefer CLIs over MCPs — gh/glab/rg/fd beat MCP servers on context cost.
• Right mechanism for the job — rule → CLAUDE.md; procedure → skill; deterministic → hook; isolated work → subagent.
• The config should learn — friction during real work becomes config improvements.

License

MIT — see LICENSE.