Codex Claude Code Config

Claude Code + Codex Agent Configuration System

[](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)

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.

---

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: sync all public skills with backups for changed local copies
python ~/claude-code-config/scripts/sync_skills_to_codex.py --apply

~/.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](rules/cross-harness-agents-md.md) (one AGENTS.md per project, no symlinks) + gemini-delegate skill |

See [AGENTS.md](AGENTS.md) for the procedure an agent follows after install, [HOW-IT-WORKS.md](HOW-IT-WORKS.md) for the mechanics of each layer, and [docs/runtime-wiring.md](docs/runtime-wiring.md) for the live verification contract.

---

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](principles/01-harness-design.md))
• Agent claims "done" but it's broken? Require durable proof artifacts ([Proof Loop](principles/02-proof-loop.md))
• Need to improve a prompt/skill/config? Automated Read-Change-Test loop ([Autoresearch](principles/03-autoresearch.md))
• LLM skips steps in complex workflows? Shell scripts for mechanical tasks, one step at a time ([Deterministic Orchestration](principles/04-deterministic-orchestration.md))
• Wrong debugging conclusions? Structured Premises-Trace-Conclusions format ([Structured Reasoning](principles/05-structured-reasoning.md))
• Task too big for one agent? Coordinator + specialized sub-agents ([Multi-Agent Decomposition](principles/06-multi-agent-decomposition.md))
• Context degrades in long sessions? Treat CLAUDE.md as runtime config, not docs ([Codified Context](principles/07-codified-context.md))
• Supply chain attack? Two config lines block packages younger than 7 days ([Supply Chain Defense](principles/09-supply-chain-defense.md))
• Prompt injection via repo/MCP/web? Six-layer defense with real CVEs ([Agent Security](principles/10-agent-security.md))
• Docs reference files that no longer exist? SessionStart hook validates every reference ([Documentation Integrity](principles/11-documentation-integrity.md)) - ships with a working validator script
• Multi-agent infrastructure overhead? Separate brain from hands with lazy provisioning ([Managed Agents](principles/14-managed-agents.md))
• Agent cuts corners on critical rules? Absolute prohibitions with incident history ([Red Lines](principles/15-red-lines.md))
• Long-running project lost its history? Condensed timeline per project, alongside handoffs ([Project Chronicles](principles/16-project-chronicles.md))
• Skill is a monolithic wall of text? Split into Direction, Blueprints, Solutions ([DBS Framework](principles/17-dbs-skill-creation.md))
• Parallel chats fight over GPUs or overwrite each other's state? Append-only handoffs + lock-file coordination ([Multi-Session Coordination](principles/18-multi-session-coordination.md))
• One chat needs to send a specific request to another? File-based mailbox with email-style threading and delivery receipts ([Inter-Agent Communication](principles/19-inter-agent-communication.md))
• AI-assisted code review findings get rediscovered next PR? Review finding → regression test → invariant → cross-reference ([Knowledge Base Enforcement](principles/21-knowledge-base-enforcement.md))
• Zero-day vulnerabilities buried in source tree? LLM + rules + SAST pipeline ([Vulnerability Detection Pipeline](principles/20-vulnerability-detection-pipeline.md))
• User needs to choose between visual options (UI, design, diagrams)? HTML fragment server + file-based event queue ([Visual Context Pattern](principles/22-visual-context-pattern.md))
• **Output keeps reverting to generic defaults (Inter font, SELECT , etc.)?* Anti-attractor procedure + three-layer enforcement ([Anti-pattern as Config](principles/23-anti-pattern-as-config.md))
• Merge conflict resolved "by logic" and lost half the work? Two-agent isolated reconciliation + verified-data priority ([Merge Conflict Resolution](principles/24-merge-conflict-resolution.md))
• 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](principles/25-coordination-primitives-mapping.md))
• Bug fix detoured into "this was already broken before me"? Five valid deferral reasons + mandatory durable proof artifacts ([No-Pre-Existing Evasion](principles/26-no-pre-existing-evasion.md))
• 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](principles/27-feature-tracking.md))
• 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](principles/28-feature-layer-architecture.md))
• 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](principles/12-low-signal-residual-training.md))
• Deep research results evaporate with the conversation? Save structured findings to an incoming folder -> review -> knowledge base pipeline ([Research Pipeline](principles/13-research-pipeline.md))
• 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](principles/29-mvp-agent-blueprint.md))

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](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/installhooks.py](scripts/installhooks.py); full map with bypass keys in [rules/safety-hooks.md](rules/safety-hooks.md)):

| Hook | Event | What It Does | |---|---|---| | [session-drift-validator](hooks/session-drift-validator.py) | SessionStart | Validates file references in CLAUDE.md at session start | | [destructive-command-guard](hooks/destructive-command-guard.py) | PreToolUse | Blocks rm -rf, git push --force, DROP TABLE | | [secret-leak-guard](hooks/secret-leak-guard.py) | PreToolUse | Prevents committing API keys, tokens, passwords | | [session-handoff-reminder](hooks/session-handoff-reminder.py) | Stop | Reminds to write handoff before closing long sessions | | [session-handoff-check](hooks/session-handoff-check.py) | SessionStart | Shows recent handoffs from previous sessions (latest per project) | | [handoff-closure-audit-guard](hooks/handoff-closure-audit-guard.py) | PreToolUse | Blocks handoff writes that lack a closure audit for the primary task and related/scope-adjacent tasks | | [stop-phrase-guard](hooks/stop-phrase-guard.py) | Stop | Detects behavioral-regression phrases (ownership dodging, permission-seeking, premature stopping, deferral-via-"what next?") | | [keyword-skill-router](hooks/keyword-skill-router.py) | UserPromptSubmit | Detects natural-language keywords and suggests matching skills (bilingual RU/EN) | | [api-key-leak-detector](hooks/api-key-leak-detector.py) | PostToolUse | Scans tool output for exposed API keys, tokens, secrets | | [command-injection-guard](hooks/command-injection-guard.py) | PreToolUse | Blocks shell substitution with non-trivial commands | | [git-destructive-guard](hooks/git-destructive-guard.py) | PreToolUse | Blocks git reset --hard, push --force, branch -D | | [git-auto-backup](hooks/git-auto-backup.py) | PreToolUse | Creates backup branch before destructive git operations | | [self-harm-guard](hooks/self-harm-guard.py) | PreToolUse | Prevents agent from killing its own process, locking SSH, bare reboot | | [test-muting-guard](hooks/test-muting-guard.py) | PreToolUse | Blocks adding @skip, .only(), @Ignore to existing tests | | [backup-retention-cleanup](hooks/backup-retention-cleanup.py) | Stop | Cleans up old backup branches (14-day retention) | | [file-cohesion-guard](hooks/file-cohesion-guard.py) | 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](hooks/human-confirmation-guard.py) | PreToolUse | Requires explicit user confirmation before any deletion-intent command | | [ask-question-guard](hooks/ask-question-guard.py) | PreToolUse | Blocks deferral/menu AskUserQuestion ("what next?", "which of these?") on reversible work — decide and proceed instead | | [over-engineering-advisor](hooks/over-engineering-advisor.py) | PostToolUse | Advisory nudge when an edit adds a large code block or a new dependency — "is this the minimal solution?" (never blocks) | | [activity-journal-guard](hooks/activity-journal-guard.py) | 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](hooks/coord-claim-guard.py) | PreToolUse | Claim-before-edit gate for multi-session / coord-enabled repos (blocks editing a file without an active claim) | | [continuity-contract-guard](hooks/continuity-contract-guard.py) | PreToolUse | Protects Claude/Codex continuation: no silent whole-file Write, out-of-scope edits, or near-whole-file replacement | | [continuity-session-check](hooks/continuity-session-check.py) | SessionStart | Surfaces the shared .claude/continuity/CONTINUITY.json contract and its preserve/do-not-redo decisions | | [cyrillic-bash-guard](hooks/cyrillic-bash-guard.py) | PreToolUse | Blocks raw non-ASCII (Cyrillic/CJK) in Windows Bash commands — encoding-corruption guard | | [feature-list-validator](hooks/feature-list-validator.py) | Stop | Validates featurelist.json discipline (WIP=1; done needs evidence) — companion to problems-md-validator | | [handoff-resume-gate](hooks/handoff-resume-gate.py) | SessionStart | Resume freshness-gate — complements session-handoff-check by gating on stale/unacknowledged handoffs | | [long-run-detector](hooks/long-run-detector.py) | SessionStart | Auto-detects a long-running project and nudges adopting the [LONG-RUN] harness (featurelist.json / init.sh) | | [verify-deleted-guard](hooks/verify-deleted-guard.py) | PostToolUse | Verifies a destructive operation actually completed (object really gone) | | [db-snapshot-guard](hooks/db-snapshot-guard.py) | PreToolUse | Auto-snapshots the database before bypassed destructive SQL | | [claude-attribution-guard](hooks/claude-attribution-guard.py) | PreToolUse | Blocks commits/PRs carrying Co-Authored-By: Claude footers (see [rules/no-claude-attribution.md](rules/no-claude-attribution.md)) | | [pre-push-claude-attribution](hooks/pre-push-claude-attribution.py) | git pre-push | Final attribution gate before commits reach the remote | | [precompact-handoff-guard](hooks/precompact-handoff-guard.py) | PreCompact | Demands a fresh handoff before context compaction; writes an AUTO-DRAFT fallback if none exists | | [test-gate-stop-hook](hooks/test-gate-stop-hook.py) | Stop | Blocks closing a session while tests are red | | [problems-md-validator](hooks/problems-md-validator.py) | Stop | Blocks closing with OPEN problems lacking a valid deferral reason | | [task-inbox-show](hooks/task-inbox-show.py) | SessionStart | Surfaces pending tasks from .claude/task-inbox/ | | [plan-gate](hooks/plan-gate.py) | UserPromptSubmit | Non-blocking nudge: substantive build/refactor ask + no plan artifact in the project -> one-line "freeze acceptance criteria first" reminder (max once/day) |

Supporting hooks and shared utilities (wire these when the project needs the corresponding workflow):

| Hook | Event | What It Does | |---|---|---| | [conversation-history-capture](hooks/conversation-history-capture.py) | Stop | Archives the local session transcript for searchable continuation | | [directory-creation-guard](hooks/directory-creation-guard.py) | PreToolUse | Applies lifecycle labels and placement checks to new directories | | [docs-staleness-guard](hooks/docs-staleness-guard.py) | SessionStart | Surfaces stale project guidance before work begins | | [feedback-pending-show](hooks/feedback-pending-show.py) | SessionStart | Shows queued corrections waiting for review | | [git-source-gate](hooks/git-source-gate.py) | Stop | Checks that durable work is represented in Git before closure | | [github-workflow-security](hooks/github-workflow-security.py) | PreToolUse | Adds a security checklist before editing GitHub Actions workflows | | [kb-validate-gate](hooks/kb-

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AnastasiyaW
• Source: AnastasiyaW/codex-claude-code-config
• License: MIT

Install and usage instructions live in the source repository linked above.