Claude Code + Codex Agent Configuration System
A practical configuration kit for Claude Code, Codex, and other coding agents. It contains architectural principles, enforcement hooks, skills, drop-in rules, starter templates, and dynamic-workflow commands. Drop the relevant parts into a project so the agent starts from verified working patterns instead of rediscovering them every session.
This is not a collection of tips. It is a system that teaches your agent how to work - when to use one agent vs many, how to verify its own output, how to manage context across long sessions, how to not get poisoned by malicious packages.
Notes
Write-ups of the incidents that produced a rule or a hook here. Each states what was measured, what is inference, and what the fix does not cover.
| Starting from what you remember | Why a brand-new project arrives years out of date, why an invented package name is now a security problem rather than a 404, and where manifest and install-time checks have to sit to catch either. Ships as dependency-currency-guard.py + dependency-provenance-guard.py. |
| Why an agent circles instead of acting | Two agents, identical rules, different gate shapes. Describing a fix instead of applying it turned out to be the only move with no gate on it. |
| Gates that cannot bootstrap themselves | A check that only arms once the thing it checks for already exists will never arm. The failure looks exactly like compliance. |
| Nine skills, one skeleton, and nobody reaching for them | Nine architecture skills existed and one was reachable — the one arguing for less code. How a one-sided advisory becomes a ratchet toward monoliths, and why filing knowledge by source book makes it unreachable. |
| The form was available, so it was taken for the content | One failure shape in six materials — including three times inside the tool built to catch it. What formal verification, pytest, ESLint and mutation testing each already answer, and why "empty" has to be its own outcome. |
| A launch is a promise to look at it | A job that died in its first second looks exactly like one running quietly, and "is it running" is three independent questions of which liveness is only the first. 2,958 launches measured, 42 never checked at all. Ships as hooks/launch-watch-guard.py. |
| The deferral moves to whichever form is not guarded | Who has already built "keep going until it is done", what it cost when it looped, and why 27 of 51 open tickets here carry the same one of five legitimate reasons. Ships as the today's-tickets gate in hooks/handoff-closure-audit-guard.py. |
| A passing test is not a release | An unavailable signer, VM, or account should block only its own stage, not erase proof of an unchanged parent. Introduces VERIFIED / SEALED / BLOCKED / SUPERSEDED, a minimal stage ledger, and the boundary where the ledger would just become bureaucracy. Ships as proof-verify + hooks/plan-gate.py. |
| A save log is not a retention guarantee | Why a handler return or message journal cannot prove photo/document preservation; defines the live read-after-write, cleanup, and restart receipt that must exist before destructive cleanup. |
| Runtime wiring and hook lifecycle | Where request intake, safety guards, verification, compaction, and close-out belong; how continuity stays durable without putting archive/index work on every prompt. |
Installation
Three paths depending on what you need:
Option 1: Claude Code plugin (fastest)
claude plugin install https://github.com/AnastasiyaW/claude-code-config
Then in your Claude Code chat:
Read AGENTS.md and pick the principles, hooks, and skills that match my project.
Option 2: Global install (hooks + skills available in every project)
git clone https://github.com/AnastasiyaW/claude-code-config ~/claude-code-config
# Copy the always-on safety hooks to your global config
python ~/claude-code-config/scripts/install_hooks.py --global
# Claude Code: copy a selected skill directory, not its parent category
mkdir -p ~/.claude/skills
cp -r ~/claude-code-config/skills/ai-ml/ml-research-lab ~/.claude/skills/
# Codex desktop and Claude Code: sync all public skills with backups for changed local copies
python ~/claude-code-config/scripts/sync_skills_to_codex.py --apply --also-claude
~/.claude/hooks/ stores the hook scripts; ~/.claude/settings.json is where they are registered. The install script merges safe defaults into your existing settings.
Option 3: Project-local (hooks/skills only in this project)
cd /your/project
git clone https://github.com/AnastasiyaW/claude-code-config .claude-config
python .claude-config/scripts/install_hooks.py --local
cp -r .claude-config/skills .claude/skills
This keeps everything under .claude/ in your repo, nothing global.
Choosing what to install
| Project type | Minimum viable set |
|---|---|
| Any project | 5 safety hooks (destructive-command, secret-leak, git-destructive, git-auto-backup, session-drift-validator) + Principles 09 (Supply Chain), 10 (Agent Security), 11 (Documentation Integrity) |
| Web app | above + frontend-design skill + Principles 04 (Deterministic Orchestration), 05 (Structured Reasoning) |
| ML / data pipeline | above + flux2-*, diffusion-engineering, vlm-segmentation skills + Principles 03 (Autoresearch), 12 (Low-Signal Training) |
| Multi-agent / parallel sessions | above + mclaude + Principles 01 (Harness), 06 (Multi-Agent), 18 (Multi-Session Coordination), 19 (Inter-Agent Communication) |
| Library / package | above + Principles 08 (Skills Best Practices), 17 (DBS Skill Creation) |
| More than one CLI agent (Claude + Gemini / Codex) | above + rules/cross-harness-agents-md.md (one AGENTS.md per project, no symlinks) + gemini-delegate skill |
See AGENTS.md for the procedure an agent follows after install, HOW-IT-WORKS.md for the mechanics of each layer, and docs/runtime-wiring.md for the live verification contract.
Moved the config to a new machine or account and most skills stopped being
offered? Nothing raises an error when that happens — see
docs/skill-tree-recovery.md and run
python scripts/recover_skill_trees.py --report.
What This Gives You
Architectural Principles - each one prevents a specific failure mode observed in real agent workflows:
- Self-evaluation bias? Separate Generator and Evaluator agents (Harness Design)
- Agent claims "done" but it's broken? Require durable proof artifacts (Proof Loop)
- Tests feel repetitive or a specialized gate blocks smoke? Use the universal candidate-state sequence: focused slice, risk-based review, one full matrix, then only the relevant immutable-candidate compatibility proof (testing strategy)
- Need to improve a prompt/skill/config? Automated Read-Change-Test loop (Autoresearch)
- LLM skips steps in complex workflows? Shell scripts for mechanical tasks, one step at a time (Deterministic Orchestration)
- Wrong debugging conclusions? Structured Premises-Trace-Conclusions format (Structured Reasoning)
- Task too big for one agent? Coordinator + specialized sub-agents (Multi-Agent Decomposition)
- Context degrades in long sessions? Treat CLAUDE.md as runtime config, not docs (Codified Context)
- Supply chain attack? Two config lines block packages younger than 7 days (Supply Chain Defense)
- Prompt injection via repo/MCP/web? Six-layer defense with real CVEs (Agent Security)
- Docs reference files that no longer exist? SessionStart hook validates every reference (Documentation Integrity) - ships with a working validator script
- Multi-agent infrastructure overhead? Separate brain from hands with lazy provisioning (Managed Agents)
- Agent cuts corners on critical rules? Absolute prohibitions with incident history (Red Lines)
- Long-running project lost its history? Condensed timeline per project, alongside handoffs (Project Chronicles)
- Skill is a monolithic wall of text? Split into Direction, Blueprints, Solutions (DBS Framework)
- Parallel chats fight over GPUs or overwrite each other's state? Append-only handoffs + lock-file coordination (Multi-Session Coordination)
- One chat needs to send a specific request to another? File-based mailbox with email-style threading and delivery receipts (Inter-Agent Communication)
- AI-assisted code review findings get rediscovered next PR? Review finding → regression test → invariant → cross-reference (Knowledge Base Enforcement)
- Zero-day vulnerabilities buried in source tree? LLM + rules + SAST pipeline (Vulnerability Detection Pipeline)
- User needs to choose between visual options (UI, design, diagrams)? HTML fragment server + file-based event queue (Visual Context Pattern)
- *Output keeps reverting to generic defaults (Inter font, SELECT , etc.)? Anti-attractor procedure + three-layer enforcement (Anti-pattern as Config)
- Merge conflict resolved "by logic" and lost half the work? Two-agent isolated reconciliation + verified-data priority (Merge Conflict Resolution)
- Built a coordination primitive from scratch? Map it to the classical analog first (Chubby lease, WAL, SMTP) and inherit 30 years of failure-mode literature (Coordination Primitives Mapping)
- Bug fix detoured into "this was already broken before me"? Five valid deferral reasons + mandatory durable proof artifacts (No-Pre-Existing Evasion)
- Long-run project's scope and progress scattered across 30+ handoffs? Three-artifact harness (PROBLEMS.md + feature_list.json + init.sh) with WIP=1 invariant and L1/L2/L3 evidence requirements (Feature Tracking)
- Feature rationale evaporates into git log after 6 weeks? Three-tier KB (Global -> Layer -> Feature narrative) with ULTRAPACK-style task.md, auto-allocated F-NNN ID, hyperlinked invariants (Feature-Layer Architecture)
- Model collapses to "predict zero" on residual/delta tasks? Traps and fixes for low-signal training (overlay maps, denoise deltas, color-correction residuals), from 4 rounds of real failure (Low-Signal Residual Training)
- Deep research results evaporate with the conversation? Save structured findings to an incoming folder -> review -> knowledge base pipeline (Research Pipeline)
- Need a human-browsable memory view without a second source of truth? Use an optional Obsidian-compatible Markdown hub over the private archive (Obsidian Mind adoption note)
- Need a repeatable claim check or local UI/CLI harness? Use the selectively adopted Cursor Team Kit patterns:
verify-this,control-cli,control-ui,deslop, and opt-in strict quality review. - Building a brand-new agent and not sure what to decide first? 15-section MVP blueprint: autonomy level -> tool risk classes -> permission matrix -> budgets -> evals -> release checklist (MVP Agent Blueprint)
Need smaller diagnostic command output? The optional RTK integration is
pinned, checksum-verified, fail-open, and tested separately from safety hooks.
See docs/rtk-integration.md and
scripts/rtk_integration.py; it is never a substitute for raw evidence.
Ready-to-use hooks that enforce rules mechanically, not probabilistically (install via scripts/install_hooks.py; full map with bypass keys in rules/safety-hooks.md):
| Hook | Event | What It Does |
|---|---|---|
| session-drift-validator | SessionStart |
Validates file references in CLAUDE.md at session start |
| destructive-command-guard | PreToolUse |
Blocks rm -rf, git push --force, DROP TABLE |
| secret-leak-guard | PreToolUse |
Prevents committing API keys, tokens, passwords |
| session-handoff-reminder | Stop |
Reminds to write handoff before closing long sessions |
| session-handoff-check | SessionStart |
Shows recent handoffs from previous sessions (latest per project) |
| handoff-closure-audit-guard | PreToolUse |
Blocks handoff writes that lack a closure audit for the primary task and related/scope-adjacent tasks |
| stop-phrase-guard | Stop |
Detects behavioral-regression phrases (ownership dodging, permission-seeking, premature stopping, deferral-via-"what next?") |
| keyword-skill-router | UserPromptSubmit |
Detects natural-language keywords and suggests matching skills (bilingual RU/EN) |
| api-key-leak-detector | PostToolUse |
Scans tool output for exposed API keys, tokens, secrets |
| command-injection-guard | PreToolUse |
Blocks shell substitution with non-trivial commands |
| git-destructive-guard | PreToolUse |
Blocks git reset --hard, push --force, force branch deletion (-D, -fD, -Df, long flags); allows merged-only branch -d |
| git-auto-backup | PreToolUse |
Creates backup branch before destructive git operations |
| self-harm-guard | PreToolUse |
Prevents agent from killing its own process, locking SSH, bare reboot |
| test-muting-guard | PreToolUse |
Blocks adding @skip, .only(), @Ignore to existing tests |
| backup-retention-cleanup | Stop |
Cleans up old backup branches (14-day retention) |
| file-cohesion-guard | PreToolUse |
Advisory: warns when a durable file is written to a scratch location (home root, Desktop, Downloads, /tmp) instead of the project structure |
| human-confirmation-guard | PreToolUse |
Requires explicit user confirmation before any deletion-intent command |
| ask-question-guard | PreToolUse |
Blocks deferral/menu AskUserQuestion ("what next?", "which of these?") on reversible work — decide and proceed instead |
| over-engineering-advisor | PostToolUse |
Advisory nudge when an edit adds a large code block or a new dependency — "is this the minimal solution?" (never blocks) |
| module-shape-advisor | PostToolUse |
The mirror of the row above: advisory nudge when the whole FILE has outgrown its shape — "where is the seam?" Fires on cumulative size, not on your edit, because that is how a file gets there (never blocks) |
| dependency-currency-guard | PreToolUse |
Blocks a manifest edit that names a package which does not exist, is too new or too little used to be a real recall (the slopsquat profile), or pins a fast-moving library far behind current |
| dependency-provenance-guard | PreToolUse |
Blocks direct wheels/archives/Git sources and extra indexes; requires lock/hash-aware installs, fails closed on registry outages, and checks exact registry versions plus artifact digests |
| dependency-alternatives | On demand | Searches official PyPI/npm metadata and returns only stable, age- and digest-verified candidate packages; never edits or installs |
| pre-push-public-repo-scan | git pre-push |
Two independent scans — regex and semantic — of a push to a PUBLIC repo; either one alarming blocks it. Private repos skip. Host and script names load from a local list, never from this file |
| shape_common | (library) | Not a hook: the one definition of "what shape is this file in", shared by module-shape-advisor and scripts/architecture_audit.py so the two cannot answer differently |
| harness-load-advisor | Stop |
Notices when a closing message reports a high-cost or specialized gate (signing, VM/GPU/OS/browser/performance) blocking lower-risk work, and says so. A feedback guard, not a bypass — it never lifts the gate |
| outward-claim-evidence-guard | Stop |
Blocks a narrow set of externally measurable claims (hash, filename-derived hash, size, version, deploy) when the final report lacks a probe/result line. It enforces reporting discipline, not truth by itself. |
| repeated-attempt-guard | PreToolUse + PostToolUse |
Stops the guess-and-retry loop: advisory on the third failed attempt at the same target, blocking on the fourth, unless something has been read since the last failure. One Read clears it — the block is lifted by the action that would have solved it three attempts earlier. Needs both events: PostToolUse records outcomes, PreToolUse decides |
| launch-watch-guard | PostToolUse + Stop |
Starting a job is a promise to look at it. Records every launch (nohup, detached docker run, sbatch, schtasks, run_in_background) and refuses to end the session while one has never been probed — a job that died in its first second looks exactly like one running quietly. One nvidia-smi, docker ps or tail of its log clears it. Measured: 2,958 launches over 30 days, 42 never probed at all, across 28 of 175 sessions |
| open-items-are-work-orders | UserPromptSubmit |
"What is still open?" is a work order, not a status request. Answers the question with the actual open PROBLEMS.md entries — oldest first, ages attached, dominant label called out — and states that they get closed in this turn rather than restated. Fires on 0.06% of real messages (context only, never blocks) |
| unbuffered-progress-advisor | PreToolUse |
A backgrounded Python run with no -u block-buffers its stdout, so a stall looks exactly like slowness — twice worth half an hour. Advisory, gated on the harness's own run_in_background rather than on parsing the command text: the text-matching version fired 459 times on real history, all false (never blocks) |
| live-tree-guard | PreToolUse |
The primary checkout receives finished work; it is not where work is done. Blocks editing a tracked file in the primary tree of a repo that opted in with .claude/live-tree — a lock says "please do not", a separate worktree means there is nothing to overwrite. Exempt: linked worktrees, append-only per-session artifacts, untracked new files. See live-tree-is-receive-only |
| shared-branch-guard | PreToolUse |
In a repo opted in with .claude/shared-branch, blocks any git reset and pathless git commit; these commands can rewrite or publish another worker's staged state. |
| pre-push-personal-email-guard | (git pre-push) | Refuses to publish commits authored with a personal email address — commit metadata in a public repo is readable through the API without cloning, and an address plus proven activity is a ready-made phishing target |
| activity-journal-guard | PreToolUse |
Enforces the shared activity journal — blocks a mutating command on a tracked shared resource that does not log to its journal |
| coord-claim-guard | PreToolUse |
Claim-before-edit gate for multi-session / coord-enabled repos (blocks editing a file without an active claim) |
| continuity-contract-guard | PreToolUse |
Protects Claude/Codex continuation: no silent whole-file Write, out-of-scope edits, or near-whole-file replacement |
| continuity-session-check | SessionStart |
Surfaces the shared .claude/continuity/CONTINUITY.json contract and its preserve/do-not-redo decisions |
| cyrillic-bash-guard | PreToolUse |
Blocks raw non-ASCII (Cyrillic/CJK) in Windows Bash commands — encoding-corruption guard |
| feature-list-validator | Stop |
Validates feature_list.json discipline (WIP=1; done needs evidence) — companion to problems-md-validator |
| handoff-resume-gate | SessionStart |
Resume freshness-gate — complements session-handoff-check by gating on stale/unacknowledged handoffs |
| long-run-detector | SessionStart |
Auto-detects a long-running project and nudges adopting the [LONG-RUN] harness (feature_list.json / init.sh) |
| verify-deleted-guard | PostToolUse |
Verifies a destructive operation actually completed (object really gone) |
| transfer-contract-guard | PreToolUse + PostToolUse + Stop |
Requires a durable source/destination/setting/deadline record for clone/copy/move/sync, reminds about proof, and blocks orphaned transfers |
| db-snapshot-guard | PreToolUse |
Auto-snapshots the database before bypassed destructive SQL |
| claude-attribution-guard | PreToolUse |
Blocks commits/PRs carrying Co-Authored-By: Claude footers (see rules/no-claude-attribution.md) |
| pre-push-claude-attribution | git pre-push |
Final attribution gate before commits reach the remote |
| precompact-handoff-guard | PreCompact |
Demands a fresh handoff before context compaction; writes an AUTO-DRAFT fallback if none exists |
| test-gate-stop-hook | Stop |
Selects fast/integration evidence by Git-visible risk and blocks closing while selected tests are red or unproven |
| problems-md-validator | Stop |
Blocks closing with OPEN problems lacking a valid deferral reason |
| task-inbox-show | SessionStart |
Surfaces pending tasks from .claude/task-inbox/ |
| plan-gate | UserPromptSubmit |
Non-blocking nudge: substantive build/refactor with no concrete plan -> freeze acceptance criteria; multi-stage/release work without .proof/stage-ledger.json also gets a separate once/day reminder to seal accepted inputs and record external blockers |
Supporting hooks and shared utilities (wire these when the project needs the corresponding workflow):
| Hook | Event | What It Does |
|---|---|---|
| conversation-history-capture | Stop |
Archives the local session transcript for searchable continuation |
| directory-creation-guard | PreToolUse |
Applies lifecycle labels and placement checks to new directories |
| docs-staleness-guard | SessionStart |
Surfaces stale project guidance before work begins |
| feedback-pending-show | SessionStart |
Shows queued corrections waiting for review |
| git-source-gate | Stop |
Checks that durable work is represented in Git before closure |
| github-workflow-security | PreToolUse |
Adds a security checklist before editing GitHub Actions workflows |
| kb-validate-gate | Stop |
Runs the project knowledge-base validator when opted in |
| session-feedback-capture | Stop |
Queues durable correction notes without blocking session closure |
| safety_common.py | shared | Shared event parsing and decision helpers for opt-in hooks |
Starter templates for common project types: web-app, ML project, library, code review, project chronicle, memory files, memory reference, proof plan, bug-fix prompt (anti-"pre-existing" constraints baked in), long-run project harness pack (drop-in feature_list.schema.json + feature_list.template.json + init.sh.template for any project crossing 5+ features and 5+ sessions). |
Dynamic workflow commands (workflows/) - ready-to-drop .js orchestration scripts for Claude Code dynamic workflows (/deep-review-flow, /research-cn-ru) plus EFFECTIVE-AGENTS.md - measured cost lessons (one agent() ≈ 95-150k tokens; resume as the main economy lever).
Cross-harness setup (rules/cross-harness-agents-md.md) - share one AGENTS.md per project between Claude Code, Gemini CLI, and Codex without symlinks: Claude imports it via @AGENTS.md, Gemini reads it via context.fileName, Codex natively. Companion skill gemini-delegate covers multi-account Gemini CLI delegation (quota ladders, account switcher scripts/gemini-switch.sh, trust boundaries).
For serial Claude/Codex handoff, use the cross-harness-continuation contract. It records the Git baseline, claimed files, accepted decisions, rejected approaches, and verification. The guard blocks silent rewrites and scope drift; an intentional redesign must use an explicit, reasoned replan mode.
Your agent picks the approach that fits. The alternatives/ directory compares 2-5 approaches for each problem, with pros, cons, and "when to choose" guidance:
| Problem | Approaches Compared |
|---|---|
| Multi-step orchestration | Harness Design, Proof Loop, Deterministic Orchestration, Prompt-only |
| Code review | Sequential checklist, Parallel competency, Cross-model, LLM + static |
| Iterative optimization | Autoresearch, HyperAgent, Manual, Eval-driven |
| Codebase scoping before changes | Belief Map / Code Graph, Symbol Index / LSP, Targeted rg, Full Context Upfront |
| Context in long sessions | JIT Loading, Full Context Upfront, Compaction, Fresh Sessions |
| Session transitions | Manual HANDOFF.md, Auto hooks, Session Journal, ContextHarness, Memory |
| Reasoning-quality regression | Config reset, Stop-phrase guard, Metric monitoring, Fresh-session A/B, Proof Loop |
Long-Run Project Harness (new in v3.17/v3.18)
If you have a project that crosses 5+ features and 5+ sessions of work, three drop-in artifacts close the gap that PROBLEMS.md + handoffs + chronicles alone leave open:
| Artifact | Question it answers | Where |
|---|---|---|
init.sh |
Is the project healthy right now? (binary check, <3 min target) | templates/long-run-project/init.sh.template |
feature_list.json |
What features exist and what state are they in? (machine-readable) | templates/long-run-project/feature_list.schema.json + .template.json |
PROBLEMS.md |
What is broken right now? Recovery procedures? | Already covered in rules — pairs with the two above |
Hard rules attached to this pack:
- WIP=1: at most one feature in
status: "in-progress"at any time - **L1+L2+L3 e
No comments yet
Be the first to share your take.