claude-scaffold
April 21, 2026 · View on GitHub
Claude Code infrastructure for ML and AI engineers — deploy once, sync everywhere, and cut input token costs by 71%.
Three things in one repo: scaffolding (22 skills, profiles, hooks deployed to any project), token optimization (bash output filters + context defaults measured at 71.4% savings on Sonnet 4.6), and multi-repo management (update --all keeps every project in sync with one command).
Three Pillars
1. Scaffolding — deploy discipline to every project
claude-scaffold is a central infrastructure layer you configure once and deploy everywhere. 22 domain skills load automatically based on what you're working on. Profiles adapt CLAUDE.md for different roles. Hooks enforce quality checks without any manual wiring.
claude-scaffold ← you configure this once
│
├── deploy → project-a/.claude/
├── deploy → project-b/.claude/
└── deploy → project-c/.claude/
2. Token Optimization — 71.4% input token savings (measured)
A bash output filter hook wraps verbose commands before they run. Instead of Claude reading 2,000 lines of pytest output, it reads the 20 lines that matter.
Benchmark: 25 tasks × Sonnet 4.6 via OpenRouter
Baseline: 25,084 input tokens
Optimized: 7,178 input tokens
Savings: 71.4%
3. Multi-Repo Management — one command keeps 29+ projects in sync
npx claude-scaffold update --all # sync all registered projects
npx claude-scaffold update --all --dry-run # preview what changes
npx claude-scaffold status # show version drift across projects
When you improve a hook, skill, or CLAUDE.md — every project gets it. No copy-pasting, no drift.
Thinking Defaults
Applies Anthropic's recommended thinking settings by default — max effort, adaptive thinking opt-out, full thinking summaries. Written into every deployed .claude/settings.json:
{
"env": {
"CLAUDE_CODE_EFFORT_LEVEL": "max",
"CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING": "1"
},
"showThinkingSummaries": true
}
Non-overwrite on init/update (existing user values preserved). Override via CLI:
npx claude-scaffold init /path --profile ml-engineer \
--effort medium --adaptive-thinking on --thinking-summaries off
Post-deploy explicit overwrite via tune:
npx claude-scaffold tune --effort high # change effort only
npx claude-scaffold tune --effort off # remove the key (let Claude Code default apply)
npx claude-scaffold tune --adaptive-thinking on # re-enable adaptive thinking
Quick Start
# Interactive wizard — asks profile, language, CI, deploy target
npx claude-scaffold init /path/to/my-project
# One-liner with profile
npx claude-scaffold init /path/to/my-project --profile ml-engineer --lang en
Profiles: ml-engineer · ai-developer · fastapi-developer · fullstack · hub · task-hub
Languages: en · ru
# Edit session context after deploy
code /path/to/my-project/dev/status.md
# Keep all projects in sync
npx claude-scaffold status # show all registered projects + version drift
npx claude-scaffold update --all # sync all outdated projects
npx claude-scaffold update /path # sync a single project
Python deploy alternative (no npm required): docs/INTEGRATION.md
Advanced: Org Profiles (Teams)
For teams with shared conventions — infrastructure topology, naming rules, internal links — org profiles add an organization-specific CLAUDE.md layer on top of scaffold core. This layer survives update --all and is updated independently.
npx claude-scaffold init /path/to/repo --profile ai-developer --org-profile techcon-ml --org-type ml-pipeline
npx claude-scaffold list-org-profiles
npx claude-scaffold update-org-profile --org techcon-ml
npx claude-scaffold update-org-profile --org techcon-ml --repos /path/a,/path/b
Org profiles live in org-profiles/<org-name>/ in the scaffold repo. They are gitignored by default — internal org data stays private.
Features
On every Claude Code prompt, hooks automatically inject dev/status.md, match the prompt against 22 skill rules (keywords + changed files + platform triggers), inject up to 2 additional skills, check for a session contract, and suggest discover on first session.
22 Skills
| Skill | Triggers On |
|---|---|
python-project-standards | Always loaded (always_load: true) |
critical-analysis | hypothesis, experiment, bottleneck, рефактор, метрика (≥2 keywords, priority=0) |
fastapi-patterns | FastAPI, routers, endpoints, Pydantic |
htmx-frontend | HTMX, Jinja2 templates, server-side rendering |
ml-data-handling | pickle, ONNX, Parquet, S3, artifacts |
multimodal-router | PDF, DOCX, video, image analysis, Gemini |
langgraph-patterns | langgraph + state/graph/node (≥2 keywords) |
rag-vector-db | Qdrant, pgvector, embeddings, chunking, RAG |
nlp-slm-patterns | Presidio, spaCy, Ollama, vLLM, PII |
predictive-analytics | sklearn, MLflow, Optuna, feature engineering |
experiment-tracking | MLflow, model registry, log_metric, experiment |
data-validation | pandera, great expectations, schema validation |
infra-yandex-cloud | terraform + yandex/docker (≥2 keywords) |
test-first-patterns | pytest, BDD, Gherkin, fixtures, coverage |
github-actions | .github/workflows/*.yml, CI/CD jobs |
claude-api-patterns | anthropic SDK, tool_use, MessageCreate |
prompt-engineering | system_prompt, few_shot, chain-of-thought, eval |
database-migration-safety | alembic, migration, schema, upgrade/downgrade (≥2 keywords) |
supply-chain-auditor | dependency, CVE, audit, pip install (≥2 keywords) |
design-doc-creator | Meta — manual only, not auto-loaded |
skill-developer | Meta — manual only, not auto-loaded |
9 Agents · 5 Commands · 8 Hooks
Agents: design-doc-architect · test-architect · multimodal-analyzer · code-reviewer · infra-provisioner · refactor-planner · project-status-reporter · debug-assistant · status-updater
Commands: /init-design-doc · /new-project · /review · /dev-status · /infra
| Hook | Event | Action |
|---|---|---|
skill-activation-prompt.js | UserPromptSubmit | Inject status.md + matched skills + plan-mode reminder |
session-safety.js | PreToolUse | Classify Bash commands (CRITICAL/MODERATE/SAFE), create git snapshots |
bash-output-filter.js | PreToolUse | Wrap verbose commands with output filters |
session-start.js | SessionStart | Detect platform (win32/unix), inject Windows rules, onboarding |
session-checkpoint.js | PostToolUse | Auto-checkpoint at plan approval; fires compact signal when context is critical |
post-tool-use-tracker.js | PostToolUse (Bash|Edit|Write) | Log tool calls to .claude/logs/ |
session-status-monitor.js | StatusLine | Display ctx: ⚠ X% in status bar; writes context_critical flag to session cache |
python-quality-check.js | Stop | Run ruff + mypy at session end |
Session Safety
session-safety.js classifies every Bash command as CRITICAL, MODERATE, or SAFE using destructive-patterns.json. On CRITICAL commands (git reset --hard, rm -rf, DROP TABLE, curl | bash, etc.) the hook creates a git tag recovery point before the operation runs:
- First snapshot:
claude/s-{session8}· Nth:claude/s-{session8}-N - Restore:
git reset --hard claude/s-{session8}
Audit trail:
npx claude-scaffold session-logs --tail 20
npx claude-scaffold session-logs --list
npx claude-scaffold session-logs --session abc12345
JSONL logs are written to .claude/logs/sessions/ (gitignored) and auto-rotated after 30 files.
Bash Output Filter
Wraps verbose commands with output filters before they run:
| Command | Filter Applied |
|---|---|
pytest ... | grep FAILED/PASSED/ERROR + tail -80 |
git log ... | head -30 |
docker build ... | tail -30 |
npm install ... | grep added/removed/vulnerabilities + tail -20 |
mypy ... | grep error/warning/Found + tail -30 |
ruff check ... | tail -25 |
Rules live in .claude/hooks/filter_rules.json (editable). Audit log at .claude/logs/filter-log.jsonl.
Cross-Repo Dependencies · Infrastructure Manifest · Agent Extensions
Declare dependencies between projects with deps.yaml; reminders appear at session start for open blockers. Prevent IP/hostname hallucinations with INFRA.yaml. Extend base agents via .claude/agent-extensions/<agent>.md — concatenated at deploy time, never overwritten.
npx claude-scaffold deps status
npx claude-scaffold deps add my-hub --type knowledge
npx claude-scaffold deps update-blocker BLK-001 --status resolved
Session Contract · Skill Discovery · Model Router
claude-scaffold new-session "implement JWT auth" # track session goals
claude-scaffold discover # detect stack + suggest skills
claude-scaffold use sonnet # switch active model profile
claude-scaffold install-aliases # use-sonnet, use-haiku shell aliases
Full details in docs/REFERENCE.md.
Preset Profiles
| Profile | Skills |
|---|---|
ml-engineer | python-project-standards, ml-data-handling, predictive-analytics, rag-vector-db, langgraph-patterns, test-first-patterns |
ai-developer | python-project-standards, fastapi-patterns, multimodal-router, langgraph-patterns, github-actions, test-first-patterns |
fastapi-developer | python-project-standards, fastapi-patterns, htmx-frontend, test-first-patterns, github-actions |
fullstack | python-project-standards, fastapi-patterns, htmx-frontend, test-first-patterns, github-actions |
hub | python-project-standards, critical-analysis, rag-vector-db, prompt-engineering |
task-hub | python-project-standards, critical-analysis |
Skill Registry
Browse, search, and install verified skills from the official registry or community sources:
npx claude-scaffold registry search "frontend"
npx claude-scaffold registry install astro-skill
npx claude-scaffold registry list
npx claude-scaffold registry update
npx claude-scaffold registry add-source "my-org" "https://..." --trust community
Trust levels: verified (auto-install), community (confirmation required), untrusted (manual review).
Model Routing
External providers (for non-code tasks)
| Task | Model | Provider |
|---|---|---|
| Code, architecture, tests, refactoring | claude-sonnet-4-6 | Claude Code subscription |
| PDF / image / video / audio analysis | google/gemini-3-flash-preview | OpenRouter |
| Documents > 400k tokens | google/gemini-3-flash-preview | OpenRouter |
Routing is explicit — triggered manually via multimodal-router skill, never automatic.
Per-repo model routing (v2.6+)
Each registered repo has a base profile (power / standard / balanced) that determines which model it uses under each global mode:
| Mode | power repos | standard repos | balanced repos |
|---|---|---|---|
default | Sonnet 4.6 | Haiku 4.5 | Sonnet 4.6 |
economy | Haiku 4.5 | Haiku 4.5 | Haiku 4.5 |
no-sonnet | Opus 4.7 | Haiku 4.5 | Haiku 4.5 |
Switch globally:
claude-scaffold mode status # show active mode + per-repo drift
claude-scaffold mode default # sonnet for non-standard repos
claude-scaffold mode economy # haiku everywhere (low quota)
claude-scaffold mode no-sonnet # opus for power repos, haiku for rest
claude-scaffold mode auto-assign # bulk profile assignment by repo name
claude-scaffold mode set-profile power path/to/repo # per-repo override
You can also just tell Claude in natural language — phrases like "переходим в экономный режим", "switch to economy mode", "делаем задачу в no-sonnet" are caught by the mode-detector hook and mapped to the right action (persistent mode switch or session-local /model swap).
Hub repos (base_profile: power) receive an automatic ## [MODE ROUTING GUIDE] injection on session start, instructing the agent to proactively suggest mode switches based on task complexity.
Weekly quota tracker (v2.6.1+)
Uses ccusage (installed as optionalDependency) for local analysis of ~/.claude/projects/**/*.jsonl:
claude-scaffold quota init-budget # scaffold ~/.claude/quota-budget.json
claude-scaffold quota status # weekly usage vs budget
claude-scaffold quota refresh # force re-scan (bypass 5-min cache)
When weekly usage crosses the warn threshold (default 80%) or block threshold (default 95%), the SessionStart hook injects a ## [QUOTA WARNING] block. The statusbar shows │ 🟡 Week: 85% or │ 🔴 Week: 97% next to context and model.
Deploy Options
Option A — NPX (no clone needed)
npx claude-scaffold init /path/to/my-project
npx claude-scaffold init /path/to/my-project --profile ml-engineer --lang en
Option B — Clone and deploy (Python, no npm required)
git clone https://github.com/pyramidheadshark/claude-scaffold
cd claude-scaffold
python scripts/deploy.py # interactive wizard
python scripts/deploy.py /path/to/my-project \
--skills python-project-standards,fastapi-patterns,test-first-patterns \
--ci-profile fastapi
Verify the hook works
cd /path/to/my-project
echo '{"prompt":"pyproject.toml ruff setup"}' | node .claude/hooks/skill-activation-prompt.js
# → JSON with python-project-standards in additionalContext
Compatibility
| OS | Node | Python | Status |
|---|---|---|---|
| Windows 11 (Git Bash) | ≥18 | ≥3.11 | Tested |
| macOS 14+ | ≥18 | ≥3.11 | Tested |
| Ubuntu 22.04+ | ≥18 | ≥3.11 | Tested |
Running Tests
npm test # 568 Jest + 62 Python
npm run test:hook # hook tests only
npm run check:budget # verify all skills under 300 lines
npm run metrics # skill load frequency report
# Benchmark (requires OPENROUTER_API_KEY)
npm run bench:check # verify SDK + API key
npm run bench:full # baseline + optimized runs → dev/benchmark-log.md
VS Code Setup
anthropic.claude-code— official Claude Code extensioncharliermarsh.ruff— real-time lintingeamodio.gitlens— inline git historyusernamehw.errorlens— inline error display (pairs with mypy)