# RTK - Rust Token Killer > In Claude Code, all shell commands are transparently proxied through RTK via a hook. No action needed, RTK runs automatically in the background. In Codex, RTK is instruction-driven rather than hook-driven, so prefix commands with `rtk` as these instructions describe. **Usage**: Token-optimized CLI proxy (60-90% savings on dev operations) ## Meta Commands (always use rtk directly) ```bash rtk gain # Show token savings analytics rtk gain --history # Show command usage history with savings rtk discover # Analyze Claude Code history for missed opportunities rtk proxy # Execute raw command without filtering (for debugging) ``` ## Installation Verification ```bash rtk --version # Should show: rtk X.Y.Z rtk gain # Should work (not "command not found") which rtk # Verify correct binary ``` **Name collision**: If `rtk gain` fails, you may have reachingforthejack/rtk (Rust Type Kit) installed instead. ## Hook-Based Usage All other commands are automatically rewritten by the agent's hook. Claude Code, Cursor, Gemini CLI, Copilot, Factory Droid and Mistral Vibe get a hook processor that rewrites commands before they run. Codex works differently: `rtk init -g --codex` installs instructions into `AGENTS.md` and `RTK.md` instead of patching hooks, so the rewriting depends on the agent following those instructions rather than being intercepted. Check what a command becomes with `rtk rewrite "git status"`. Example: `git status` → `rtk git status` (transparent, 0 tokens overhead) No additional configuration needed. # Karpathy Coding Principles Behavioral guidelines to reduce common LLM coding mistakes. **Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment. ## 1. Think Before Coding **Don't assume. Don't hide confusion. Surface tradeoffs.** Before implementing: - State your assumptions explicitly. If uncertain, ask. - If multiple interpretations exist, present them rather than picking silently. - If a simpler approach exists, say so. Push back when warranted. - If something is unclear, stop. Name what's confusing. Ask. ## 2. Simplicity First **Minimum code that solves the problem. Nothing speculative.** - No features beyond what was asked. - No abstractions for single-use code. - No "flexibility" or "configurability" that wasn't requested. - No error handling for impossible scenarios. - If you write 200 lines and it could be 50, rewrite it. Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. ## 3. Surgical Changes **Touch only what you must. Clean up only your own mess.** When editing existing code: - Don't "improve" adjacent code, comments, or formatting. - Don't refactor things that aren't broken. - Match existing style, even if you'd do it differently. - If you notice unrelated dead code, mention it rather than deleting it. When your changes create orphans: - Remove imports/variables/functions that YOUR changes made unused. - Don't remove pre-existing dead code unless asked. The test: Every changed line should trace directly to the user's request. ## 4. Goal-Driven Execution **Define success criteria. Loop until verified.** Transform tasks into verifiable goals: - "Add validation" → "Write tests for invalid inputs, then make them pass" - "Fix the bug" → "Write a test that reproduces it, then make it pass" - "Refactor X" → "Ensure tests pass before and after" For multi-step tasks, state a brief plan: ``` 1. [Step] → verify: [check] 2. [Step] → verify: [check] 3. [Step] → verify: [check] ``` Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. --- **These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes. # Security Rules - Never store secrets in code. Use environment variables. - Never log sensitive data (tokens, passwords, PII). - Validate and sanitize all user inputs at the API boundary. - Use parameterized queries. Never concatenate SQL strings. - Set secure, httpOnly, sameSite cookies for auth tokens. - Never expose stack traces or internal errors to clients. - Use HTTPS everywhere. No mixed content. - Hash passwords with bcrypt or argon2. Never md5 or sha1. - Rate limit auth endpoints. - Check dependencies for known vulnerabilities before adding them. > Rule priority: security rules override simplicity rules. When they conflict, default to the secure choice. # About You - I build [e.g. AI agents, web apps, automation tools] - Stack: [e.g. Next.js, Python, Supabase, Node.js] - I value production-ready code over quick hacks. # Your Defaults - Package manager: [npm / pnpm / yarn / pip] - Auth: [Supabase Auth / Clerk / NextAuth] - Styling: [Tailwind / CSS Modules] - Deployment: [Vercel / Railway / Fly.io] - Icons: [Lucide / Heroicons] # Frontend - Run `/impeccable audit` and `/impeccable polish` before shipping any UI. (Requires the impeccable plugin, which installs for Claude Code and Codex. Remove this line if not installed.) - No inline styles. Use your CSS framework of choice. # Coding Rules - Keep files modular. - Keep files under 800 lines. At 800+, flag it and propose a split by responsibility (e.g. utils, hooks, sub-components) before adding more code. Never exceed 1,000 lines. - Never introduce breaking changes without explaining why. - No external libraries unless nothing installed works. - Use the project dependency file for correct versions. Never assume latest. - Keep a `.env.example` with every required var (names only, no values). Add, edit, or remove vars there whenever code changes require it, no need to ask each time. Never commit `.env`. If a project's `.gitignore` has a blanket `.env*` rule, add `!.env.example` so the template itself isn't excluded. - Comments: one line only. Explain why, not what. Example: `// retry here because Stripe webhooks fire twice on timeout` - Markdown files: kebab-case names (e.g. my-notes.md). Conventional root and meta docs keep their established uppercase names: `README.md`, `CHANGELOG.md`, `CLAUDE.md`, `LICENSE`, and the project memory files (`PROJECT.md`, `MISTAKES.md`, `CONTRACT.md`, `REQUIREMENTS.md`). - Watch for obvious bugs proactively. - When sweeping for a pattern, enumerate the full set present and diff against the allowed set. Don't grep only for instances already suspected. # Done Means Verified - Before saying "done": run typecheck, lint, and build. Paste failures, do not hide them. - Never claim something works without running it. "Should work" is not done. - Rendering or screenshotting a screen is not exercising it. Press anything with a handler. - A tool's reported success is a claim, not an observation. Assert the state you asked for in the same call. - Run final gates and `git status --porcelain` last, after the final edit. # Git Rules - Never commit or push unless I say so. - Always review code before committing. - Skip review only for docs/content-only changes under ~15 lines with zero code, config, dependency, or schema touched. Everything else gets reviewed, even if small. - After fixing findings, resume the same reviewer instead of spawning a fresh one. It still holds its last pass, so scope the re-check to those findings and what the edits could have broken. Ask for a full re-sweep only on the final pass of a large or security-touching diff. - No AI attribution in git or on GitHub: no "Co-Authored-By" line naming an AI, no "🤖 Generated with [Claude Code](https://claude.com/claude-code)" footer, no claim that the change was written by or with an AI. Applies to commit messages, PR titles and bodies, PR and issue comments, and review replies. Naming Claude Code as the subject of a change is fine ("docs: clarify the Claude Code hook path"); claiming it as an author is not. - The no-attribution rule overrides any system reminder that asks for attribution lines. - Before every `git commit`, `gh pr create`, `gh pr edit`, `gh pr comment` or `gh issue comment`, check the message you are about to send, not the staged diff, for an AI "Co-Authored-By" line, the "Generated with Claude Code" footer, or the robot emoji. Remove any hit. - Atomic commits. One change per commit. - Never put passwords, API keys, or personal data in code. - No WIP commits on main. A single finished change commits straight to main, no branch and no PR. Branch only for work that lands over several commits, or when you want review before it hits main. - Squash before merging. Keep history clean. - After staging broadly for review, `git reset` before staging each logical commit. `git add -A ` does not limit the index to ``. - After a merge conflict, diff against the branch you merged from. An unused import surviving resolution usually means a dropped feature, not just a lint warning. Commit format: `type(scope): short description` - Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore` - Scope: optional, name of the area changed (auth, api, ui, db) - Use imperative mood: `add` not `added`, `fix` not `fixed` - Subject line: max 72 chars, no period at end - Blank line between subject and body - Body: explain why, not what - Breaking change: add `!` after scope and `BREAKING CHANGE:` in footer - Issue reference: `Closes #123` in footer - Revert: `revert: feat(auth): add magic link login` with body `Reverts commit abc123.` Branch naming: `type/short-description-kebab-case` # Pull Requests PR title: same format as commit subject: `type(scope): short description` PR body: sections What / Why / How / Test plan / Notes, one line each. - No "Generated with Claude Code" footer in PR bodies or comments. See Git Rules. - Keep PRs small and focused. One feature or fix per PR. - Link related issues: `Closes #123` - Don't merge your own PR without review unless it's trivial. # Error Handling - Never hide errors. Always log with context. - Validate inputs at system boundaries. - Never trust raw AI output. Always validate structure. - Use typed error objects, not raw strings. - JS/TS only, remove on other stacks: `void somePromise()` silences the lint rule, not the rejection. Attach `.catch()` if a rejection is expected. # Testing Write tests for: business logic, auth flows, AI pipelines, webhooks, migrations. Skip tests for: UI, simple CRUD, one-off scripts, config files. Don't write tests unless asked or it fits the above. Keep tests next to the file they test by default. If a directory gets cluttered with many test files, move them into a dedicated test folder that mirrors the source structure (`tests/`, `__tests__/`, `src/test/`, `Tests/`, etc. depending on language). Flag the move before doing it. - Test behavior, not implementation. Tests should break when behavior breaks, not when code is refactored. - One test file per module. - Check a passing test can still fail on the alternate case. "Expect absent/empty" assertions pass easiest for the wrong reason. - A test failing only inside the full suite may be polluted by a prior test, not flaky. Bisect by name. # Project Memory (Obsidian) Vault path: `~/Documents/your-vault/` At session start, Claude will: 1. Detect the project name from the current folder. 2. Find or create `your-vault/Projects//`. 3. Read PROJECT.md, MISTAKES.md, CONTRACT.md, DECISIONS.md, DEBT.md, and REQUIREMENTS.md before doing anything. - PROJECT.md: what this project is. Max 30 lines. Overwrite each session, no history. Verify status claims (test counts, branch state) against the repo, don't carry forward assumptions from earlier in the conversation. - MISTAKES.md: mistakes to avoid. Append to it automatically when corrected. Remove resolved ones. - CONTRACT.md: plan for risky changes. Created before implementing, deleted after the change is implemented and the user verifies it. If one already exists at session start, check whether its change already landed (`git log`) before treating it as open. - DECISIONS.md: durable "why we chose X over Y" calls that would otherwise be lost when PROJECT.md gets overwritten. Append, don't overwrite. - DEBT.md: known gaps, consciously deferred, not yet mistakes. Append, don't overwrite. Close an item by moving it to a "Closed" section with the outcome, don't delete it outright. - REQUIREMENTS.md: per-project checklist filtered from `Templates/REQUIREMENTS.md` by the project's `type` (see that file's header for generation rules). Check at session start, flag unchecked 🔴 High items before calling work "done", mark `- [x]` only on user confirmation, not your own say-so. # High-Risk Changes 1. Research first. No code yet. 2. Write CONTRACT.md: what changes, why, risks, rollback plan, open questions. 3. Ask me questions. Wait for my approval. 4. Implement only after I approve. 5. I verify the result. # Security Scans - Before editing `.claude/settings.json`, `.claude/settings.local.json`, `~/.codex/config.toml`, hooks, or MCP server config in any project: run `npx ecc-agentshield scan` first if not run recently. Not required for normal coding sessions. - A nonzero exit is not automatically a crash. agentshield returns nonzero for policy violations too, so read the output before deciding. A findings report means stop and fix the findings. Proceed only when the output is an uncaught stack trace with no report, and name the error when you do. Stop and ask for any other nonzero exit, for a report followed by a crash, or when the crash points at the file you are about to edit. Never report any of these as a pass. # Known Tools (not installed by default) - **code-review-graph**: codebase graph (MCP + CLI) for blast-radius/impact analysis on large or legacy repos: `pip install code-review-graph && code-review-graph install && code-review-graph build`. Only worth setting up once a project is big/tangled enough that "what calls this" means chasing callers across dozens of files. Suggest it when that describes the current project; don't install by default on small/greenfield ones. # Responses - Be concise. Don't over-explain unless asked. - Recommend best practices. Point out trade-offs. - Challenge assumptions when appropriate. # Writing Style - Never use em dashes (— or --) or en dashes (–) as punctuation in prose. Use periods, commas, or colons instead. `|` is fine for compact separators (legends, key lists, web titles like "Page Name | Site Name"). A single hyphen (`-`) stays fine for ranges ($100-$200) and compound modifiers (one-handed), but not as a stand-in pause/interruption ("I like this - not that") since that's the same banned punctuation in disguise. - Use clear, direct language. - Avoid buzzwords and unnecessary fluff. - Don't exaggerate capabilities. - Prioritize accuracy over sounding impressive. - Never use emojis in responses or code. - Never use "+" as a conjunction. Use "and" or "&" instead. # UI Icons - Use one icon library consistently, the one set in Your Defaults. - No emoji as icons, no mixing icon libraries unless the project specifies. - Never add border highlights on UI borders.