The idea
Karpathy discipline plus Caveman compression
The project does not try to create a new personality for its own sake. It deliberately merges two useful constraints. From the Karpathy side it keeps engineering discipline: think before acting, avoid silent assumptions, prefer the simplest sufficient solution, make surgical changes, and define verifiable success criteria. From the Caveman side it keeps communication compression: answer first, cut filler, preserve exact technical tokens, and use short direct phrasing.
The result is a mode that is terse without becoming careless. A core rule is the clarity override: when safety, ambiguity, migrations, credentials, rollback, or irreversible operations are involved, the mode must expand back into clear normal technical English. That keeps the output readable and fast in the common case without letting brevity hide risk.
Think before acting
Read relevant files, surface material ambiguity, and translate vague asks into explicit completion criteria.
Prefer the smallest sufficient diff
Touch only what the task requires, match local style, and avoid unrelated cleanup or speculative abstractions.
Answer first, keep signal high
Short direct phrasing, no filler, exact technical tokens preserved, and explicit tradeoffs when they matter.
Expand when compression becomes risky
The clarity override prevents terse output from hiding assumptions, rollback risk, or security-sensitive details.
Benefits
Why teams and individual developers use it
The practical benefits are not just cosmetic. Karpathy Caveman changes how the assistant reasons, how much it touches, how easy its output is to review, and how portable that behavior remains across products. The direct benefits in practice include the categories below.
Lower review cost
Smaller diffs and shorter explanations make it easier to spot the real change, reason about impact, and review quickly.
Less silent guessing
The mode pushes assistants to expose ambiguity instead of inventing requirements under confident prose.
Better verification habits
It frames tasks around explicit outcomes, falsifiable checks, and post-change validation instead of vague completion claims.
Cleaner communication
Answer-first responses reduce wasted scanning time, especially when the user already understands the local codebase.
Safer compression
The clarity override preserves concise defaults while forcing fuller instructions around risk, security, migrations, and rollback.
Cross-tool consistency
One behavior model can be deployed across Copilot, Claude, Codex, and Cursor instead of maintaining unrelated prompt stacks.
Easier maintenance
Two canonical sources keep the mode maintainable while mirrors and bundles provide assistant-native distribution surfaces.
Better mixed-assistant rollout
Teams using multiple assistants can share the same rules without creating duplicate discovery roots or conflicting instructions.
Portable individual workflow
A solo developer can carry the same terse, minimal-diff expectations across local tools, hosted agents, and repository configurations.
Stay consistent across tools
You can keep one terse, disciplined workflow while moving between Copilot, Claude, Codex, and Cursor instead of rebuilding your prompting habits every time.
Standardize expectations
The same operating model can guide implementation, reviews, refactors, and debugging across a team, which lowers review churn and makes AI output easier to compare.
Reduce configuration drift
Canonical files, mirrored bundles, and validator-backed checks make it easier to evolve the mode without losing control of what target repositories actually receive.
Use paths
Every practical way to use the repository
The repository supports more than one rollout shape on purpose. Some users want only a manual prompt. Some want a whole assistant-native bundle. Some want one shared core across several tools. Some teams need a publishable Copilot plugin. The paths below are the supported ways to use the project without inventing undocumented combinations.
Rollout shape and day-to-day use are different
A repository can install Karpathy Caveman one way and then use it several different ways after that. In practice the mode can be consumed as always-on repository defaults, explicit prompt commands, native agents or subagents, shared skills, Copilot plugin payloads, or source bundles that help teams assemble a custom rollout deliberately.
Load repository defaults
Use AGENTS.md, CLAUDE.md, or Cursor rules when you want the mode applied by default to normal repository work.
Invoke it explicitly for one task
Use the Copilot prompt file, shared skill surfaces, or Claude-native skill invocation when you want opt-in activation instead of always-on behavior.
Select a dedicated agent or subagent
Use Copilot agents, Claude subagents, Codex roles, or Cursor agents when you want the mode wrapped in a named, native assistant entrypoint.
Keep the skill reusable
Use the shared skill format when you want one reusable task-mode definition that can travel across assistants that understand the shared Agent Skills shape.
Ship the plugin package
Use the Copilot plugin package when your distribution model is plugin-based rather than repository-file based.
Use the bundles as source guides
Use the assistant bundles and slices as authoritative source material when designing your own rollout, documentation, or internal template repository.
Use the canonical core only
Copy AGENTS.md and .agents/skills/karpathy-caveman/SKILL.md when the target environment can already use the shared formats directly.
Keep one shared source of truth
Use the shared core plus the assistant-native bundle you actually need. This is the preferred posture for repositories shared across tools.
Take the full repo-file source bundle
Use copilot/karpathy-caveman/ when you want all Copilot repository-file assets collected in one place before deciding which pieces to copy.
Install only always-on instructions
Use copilot/instruction/ if you want the Copilot-specific always-on adapter without taking prompt or plugin packaging.
Install only the slash command
Use copilot/prompt/ if you only want /karpathy-caveman as a manual trigger for the current conversation.
Ship a packaged agent and skill
Use copilot/plugin/karpathy-caveman/ when your team wants a publishable plugin payload rather than repository files.
Copy the Claude-native bundle
Use claude/karpathy-caveman/ to get AGENTS.md, CLAUDE.md, a Claude skill, and a Claude subagent together.
Copy the Codex-native bundle
Use codex/karpathy-caveman/ to get the shared core plus the Codex-native role file in .codex/agents/.
Copy the Cursor-native bundle
Use cursor/karpathy-caveman/ to get the shared core, a Cursor always-apply rule, and a Cursor-native subagent.
Assistant support
Supported assistants and their discovery surfaces
The project is precise about where each assistant should discover the mode. Different products understand different file types, so the repository maps the same behavior model onto each assistant's actual entrypoints instead of pretending one file shape fits all of them.
Architecture
How the repository is organized
The layout exists to solve two competing problems at once: keep one canonical source of truth and still provide assistant-native distribution. The answer is a layered repository that separates canonical content, direct-use files, copyable bundles, and Copilot-specific slices.
Canonical shared core
Files: AGENTS.md and .agents/skills/karpathy-caveman/SKILL.md
These are the real source of truth for the mode.
Root direct-use files
Files: prompt, agent, Cursor rule, Cursor agent, and CLAUDE.md
These make the repository itself usable while still avoiding duplicate discovery roots.
Copyable assistant bundles
Folders: copilot/karpathy-caveman/, claude/karpathy-caveman/, codex/karpathy-caveman/, cursor/karpathy-caveman/
These are the supported assistant-native distribution packages.
Copilot narrower slices
Folders: copilot/instruction/, copilot/prompt/, copilot/plugin/karpathy-caveman/
These exist because Copilot supports several materially different delivery mechanisms.
Mirrors are intentional
Assistant bundles contain mirrored copies of canonical files so target repositories can receive assistant-native layouts without manual reconstruction.
Structure is checked automatically
The validator checks required files, forbidden root paths, frontmatter, mirror drift, JSON and TOML validity, and Markdown links.
Rollout and verification
How to adopt it without guesswork
The project is meant to be copied and maintained, not just admired. A rollout should be deliberate: choose the repository posture, install the shared core when appropriate, add assistant-specific adapters, validate placement, and then test whether the assistant actually behaves the way the mode intends.
Choose the deployment shape
Decide whether the target is Copilot-only, Claude-only, Codex-only, Cursor-only, or mixed-assistant.
Install the right files
Copy the shared core and the assistant bundle or slice that matches the target workflow. Do not add duplicate roots casually.
Validate and test behavior
Check exact file placement, confirm assistant discovery, and run one small coding task to test concise reasoning and minimal diffs.
What to verify in a target repository
- Exact file placement
- Prompt, skill, rule, or agent discovery
- Concise reasoning on a small task
- Surgical edits instead of broad churn
- Explicit verification-minded behavior
How to maintain it
Edit the canonical sources first, sync mirrors second, re-run the validator third, and update bundle documentation whenever delivery guidance changes. That is the maintenance model the repository is already using.
Limits and non-goals
What the project does not claim to solve
Karpathy Caveman deliberately focuses on chat, instruction, skill, prompt, rule, and agent surfaces. It does not claim total control over every assistant behavior, and it does not try to erase the real differences between product discovery systems.
Not an autocomplete controller
These files do not fully govern ghost-text or inline suggestion systems.
Not one file for every tool
Different assistants expose different entrypoints, so the repository intentionally ships assistant-native adapters.
Not a license to over-compress
The clarity override is part of the design. Compression is useful only when it remains safe and unambiguous.
Not a blind-copy bundle
Especially for Copilot, the full bundle is a source bundle that still expects deliberate selection of what gets copied.
Resources
Where to go next inside the project
The landing page should be enough to understand the idea, but the repository also contains canonical rule files, compatibility guidance, rollout plans, assistant bundle docs, and the MIT license. These are the places worth opening next.
Main repository guide
Open README.md in the repository for the canonical text explanation of the idea, architecture, limitations, and maintenance model.
Core mode sources
Open AGENTS.md and .agents/skills/karpathy-caveman/SKILL.md when you want the actual source of truth for the behavior model.
Assistant mapping
Open docs/compatibility-matrix.md when you want the assistant-by-assistant mapping of always-on entrypoints, prompts, agents, skills, and bundles.
Adoption sequence
Open docs/rollout-plan.md when you need the step-by-step adoption model for Copilot, Claude, Codex, Cursor, or mixed-assistant repositories.
Assistant-specific install guides
Use the README files under copilot/, claude/, codex/, and cursor/ when you need exact target paths and post-install usage guidance for a specific assistant.
Repository integrity checks
Run python scripts/validate_repo.py to verify required files, forbidden roots, mirrored files, manifests, Markdown links, and this landing page's HTML links.
MIT licensing
Open LICENSE for the repository license. The project also documents inspiration from multica-ai/andrej-karpathy-skills and JuliusBrussee/caveman.
Public project home
Open the GitHub repository when you want the source tree, issues, history, or to copy the assets into another repository.