Skip to content
Back to search

occam-kit

SkillWorks with CodexGitHub

Scientific, token-frugal agent harness & portable skills for Claude Code, Codex CLI, Cursor, Gemini CLI, and Antigravity.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/moeraafatz--occam-kit/badge.svg)](/listings/moeraafatz--occam-kit)

HTML

<a href="/listings/moeraafatz--occam-kit"><img src="/api/listings/moeraafatz--occam-kit/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 201 lines · 1 finding marked
  1. <p align="center">
  2. <img src="assets/banner.png" alt="Occam-Kit — Scientific, Token-Frugal Universal Agent Harness" width="100%" />
  3. </p>
  4. <p align="center">
  5. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-white?style=flat-square" alt="MIT License" /></a>
  6. <a href="https://github.com/Moeraafatz/occam-kit/releases"><img src="https://img.shields.io/badge/release-v1.1.0-30D158?style=flat-square" alt="Release v1.1.0" /></a>
  7. <img src="https://img.shields.io/badge/dependencies-0%20(Python%203.9%2B%20stdlib)-30D158?style=flat-square" alt="Zero Dependencies" />
  8. <img src="https://img.shields.io/badge/standard-agentskills.io%20%2B%20AGENTS.md-09090B?style=flat-square" alt="Agent Skills Open Standard" />
  9. <img src="https://img.shields.io/badge/startup%20tax-262%20tokens%20total-FF9F0A?style=flat-square" alt="262 Tokens Startup Tax" />
  10. </p>
  11. # occam-kit
  12. **Occam's Razor for AI coding agents — free, MIT open source, zero dependencies.**
  13. `occam-kit` is a portable agent harness and skill pack for **Claude Code, OpenAI Codex CLI, Cursor, Gemini CLI, Antigravity, and GitHub Copilot**. It helps coding agents build projects with scientific rigor **while using the smallest context window and cheapest capable model tier possible**:
  14. 1. **Brainstorm & Analyze First** — Asks 3–5 surgical questions, exposes contradictions in requirements, cuts unnecessary scope, and locks a compact 1-page spec before writing code.
  15. 2. **Verify From Primary Sources** — Enforces an explicit source-tier hierarchy (`T1` official docs / source code / peer-reviewed papers / local benchmarks) via a machine-checked evidence ledger (`cite_check.py`).
  16. 3. **Route to Minimum Capability** — Offloads mechanical work to **Tier 0 zero-token Python scripts**, routes routine work to small/fast models (`T1`), standard work to mid-tier (`T2`), and gates frontier models (`T3`) strictly for architecture tradeoffs, security audits, or bugs after 2 logged dead ends.
  17. 4. **Stop Context Poisoning** — Replaces raw repo dumps, noisy 300-test logs, and sprawling chat histories with symbol maps, error-only test reducers, and `<350`-token handoff ledgers.
  18. ---
  19. ## Reproducible Token Benchmarks (`-93.9%` Combined)
  20. <p align="center">
  21. <img src="assets/benchmark-chart.png" alt="Occam-Kit Reproducible Token Reduction Benchmark Chart" width="100%" />
  22. </p>
  23. Run `python3 benchmarks/run_benchmarks.py` locally (<1 second, $0 API cost) to verify every number below (full report in [`benchmarks/results.md`](benchmarks/results.md)):
  24. | Scenario | Tier 0 Tool | Raw Context | With `occam-kit` | Saved | Integrity Check |
  25. | :--- | :--- | ---: | ---: | ---: | :--- |
  26. | Codebase Discovery (24 files, 4 languages) | `occam.py map` | 9,065 tok | 950 tok | **-89.5%** | All 24/24 files mapped |
  27. | Verbose Passing Test Suite (300 tests) | `occam.py run` | 7,633 tok | 54 tok | **-99.3%** | Exit status + `300 passed` preserved |
  28. | Verbose Failing Test Suite (298 pass / 2 fail) | `occam.py run` | 7,845 tok | 547 tok | **-93.0%** | 100% of failing tests + errors preserved |
  29. | 15-Turn Session Resume vs. Ledger Handoff | `occam.py ledger handoff` | 4,293 tok | 150 tok | **-96.5%** | Goal, decisions, dead ends, next tier kept |
  30. | Skill Startup Context Tax (Progressive Disclosure) | `occam.py audit` | 3,090 tok | 262 tok | **-91.5%** | All 4 skills pass `agentskills.io` spec |
  31. | **Combined Across All 5 Scenarios** | **All Tier 0** | **31,926 tok** | **1,963 tok** | **-93.9%** | **Zero diagnostic evidence lost** |
  32. > **Transparency note:** Counts use a deterministic offline BPE heuristic (`ceil(chars / 4)`) so anyone can reproduce exact results with zero API keys. Full raw command logs are always preserved on disk at `.occam/last_run.log`.
  33. ---
  34. ## Live CLI Preview
  35. <p align="center">
  36. <img src="assets/terminal-demo.png" alt="Occam-Kit Live CLI Terminal Preview" width="100%" />
  37. </p>
  38. ---
  39. ## Five-Phase Scientific Engineering Loop
  40. <p align="center">
  41. <img src="assets/workflow-overview.png" alt="Occam-Kit Five-Phase Scientific Engineering Loop" width="100%" />
  42. </p>
  43. ## Minimum-Capability Routing Ladder
  44. <p align="center">
  45. <img src="assets/routing-ladder.png" alt="Occam-Kit Minimum-Capability Routing Ladder" width="100%" />
  46. </p>
  47. ---
  48. ## Why Another Agent Harness?
  49. | Category | What They Do Well | Where They Fail |
  50. | :--- | :--- | :--- |
  51. | **Heavy Workflow Kits** *(spec kits, multi-agent packs)* | Structured planning & TDD | Huge startup context tax; burn frontier tokens on `grep`, full-file reads, and raw logs |
  52. | **Prompt Compressors** *(terse-output rules)* | Shorter assistant replies | Don't fix root token waste: bad specs, hallucinated APIs, or retry loops |
  53. | **`occam-kit`** | **Brainstorming + Primary-Source Gate + Tier 0 Local Scripts + Model Routing** | **262-token total startup tax; real Python stdlib tools; reproducible benchmarks** |
  54. ---
  55. ## 30-Second Install
  56. ### Option A — One-line install (auto-detects project vs. `~` global scope)
  57. ```bash
  58. curl -fsSL https://raw.githubusercontent.com/Moeraafatz/occam-kit/main/install.sh | bash -s -- --target all
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 83 on GitHub
  59. ```
  60. ### Option B — Clone & install selectively
  61. ```bash
  62. git clone https://github.com/Moeraafatz/occam-kit.git
  63. cd occam-kit
  64. # Project install for specific agents
  65. ./install.sh --target claude,codex,cursor --scope project --dir /path/to/your-project
  66. # Global user install (~/.claude/skills, ~/.agents/skills, ~/.gemini/skills, ~/.gemini/antigravity/skills)
  67. ./install.sh --target all --scope global
  68. # Preview without modifying files
  69. ./install.sh --target all --dry-run
  70. # Clean uninstall (never touches your own rules or code)
  71. ./install.sh --target all --scope project --dir /path/to/your-project --uninstall
  72. ```
  73. ### Supported Agents & Install Locations
  74. | Agent | Format Installed | Project Path | Global Path |
  75. | :--- | :--- | :--- | :--- |
  76. | **Claude Code** | `SKILL.md` (`agentskills.io`) + `AGENTS.md` | `.claude/skills/occam-*` | `~/.claude/skills/occam-*` |
  77. | **OpenAI Codex CLI** | `SKILL.md` (`agentskills.io`) + `AGENTS.md` | `.agents/skills/occam-*` | `~/.agents/skills/occam-*` |
  78. | **Cursor** | `.cursor/rules/*.mdc` + `.agents/skills/` | `.cursor/rules/occam-*.mdc` | `~/.agents/skills/occam-*` |
  79. | **Gemini CLI** | `SKILL.md` (`agentskills.io`) | `.gemini/skills/occam-*` | `~/.gemini/skills/occam-*` |
  80. | **Antigravity** | `SKILL.md` (`agentskills.io`) | `.agents/skills/occam-*` | `~/.gemini/antigravity/skills/occam-*` |
  81. | **GitHub Copilot** | Copilot instructions adapter | `.github/copilot-instructions.md` | — |
  82. | **Tier 0 Scripts** | Zero-dep Python 3.9+ CLI | `.occam/scripts/*.py` | `~/.occam/scripts/*.py` |
  83. ---
  84. ## Tier 0 CLI Reference (Zero LLM Tokens)
  85. Every script uses **Python 3.9+ stdlib only** — zero `pip install`, zero API keys, instant execution.
  86. ```bash
  87. # 1. Generate a compact multi-language symbol map (Python AST + JS/TS/Swift/Go/Rust/Java/C++/Shell/MD)
  88. python3 scripts/occam.py map --root . --max-tokens 1800 --stats
  89. # 2. Wrap noisy tests or builds — keeps failures + summary, saves raw output to .occam/last_run.log
  90. python3 scripts/occam.py run -- pytest -vv
  91. # 3. Persist state, locked decisions, dead ends (never retry broken fixes), and emit a <350-tok handoff
  92. python3 scripts/occam.py ledger init --goal "Ship offline PDF tool" --constraint "$0 runtime" --non-goal "Cloud sync"
  93. python3 scripts/occam.py ledger decide --id D1 --decision "Use Apple PDFKit" --reason "Native & offline"
  94. python3 scripts/occam.py ledger step add --title "Implement merge pipeline" --tier T2
  95. python3 scripts/occam.py ledger deadend --tried "Shell out to Ghostscript" --why "Not preinstalled on macOS"
  96. python3 scripts/occam.py ledger checkpoint --summary "Spec locked" --next "Build PDFMerger.swift" --tier T2
  97. python3 scripts/occam.py ledger handoff --stats
  98. # 4. Enforce primary-source citations before locking architecture
  99. python3 scripts/occam.py cite .occam/research.md --strict
  100. # 5. Audit SKILL.md compliance & startup discovery context tax (supports YAML lists & --prefix filter)
  101. python3 scripts/occam.py audit skills --max-startup-tokens 350
  102. # 6. Full workspace health check (separates occam-* health from third-party skill context tax)
  103. python3 scripts/occam.py doctor
  104. ```
  105. ---
  106. ## Honest Scope & Limitations
  107. - **Automatic vs. Guided Model Switching:** Markdown skills cannot override the active model inside single-model IDE panes like Cursor Composer or Codex CLI. In multi-agent harnesses (**Claude Code, Antigravity, OpenCode**), `occam-frugal-router` explicitly delegates `T1` subagents to fast/small models. In single-model tools (**Cursor, Codex**), it enforces Tier 0 local scripts, context caps, and prints an explicit `[OCCAM ROUTE]` banner whenever it is safe to drop down to a cheaper model and resume from `ledger handoff`.
  108. - **Token Estimator Precision:** `token_budget.py` uses `ceil(len(text) / 4)` to keep the toolkit 100% dependency-free and offline. Treat absolute numbers as close estimates (~5–10% variance across tokenizers); relative reduction percentages remain consistent.
  109. ---
  110. ## Scientific & Empirical Foundations
  111. `occam-kit` is grounded in established software engineering and LLM systems literature rather than prompt folklore. See [`skills/occam-harness/references/research-foundations.md`](skills/occam-harness/references/research-foundations.md) for full references, including:
  112. - **Progressive Disclosure** (`agentskills.io` specification) & **Lost in the Middle** (Liu et al., TACL 2024)
  113. - **Executable Agent Harnesses & Externalized State** (Anthropic *Building Effective Agents* / *Effective Harnesses for Long-Running Agents*; Ning et al., *Code as Agent Harness*, 2026)
  114. - **Evidence-Preserving Context Compaction** (*SoL-Pi*, 2026)
  115. - **Model Cascading & Step-Level Routing** (Chen et al., *FrugalGPT*, 2023; *Agentic Routing*, 2026)
  116. - **Early Requirements Clarification & Evidence-Based SE** (Boehm *Software Engineering Economics*; Kitchenham et al., ICSE 2004)
  117. ---
  118. ## Repository Structure
  119. ```text
  120. occam-kit/
  121. ├── AGENTS.md # Universal lean operating rules (~430 tokens)
  122. ├── CLAUDE.md # Claude Code entry shim
  123. ├── CONTRIBUTING.md # Open-source contribution guide & CI rules
  124. ├── install.sh # Cross-agent installer (--target, --scope, --dry-run, --uninstall)
  125. ├── assets/ # Dark-mode SVG + Retina 2x PNG charts, diagrams & CLI preview
  126. ├── skills/ # Official agentskills.io portable skills (262 tokens combined startup)
  127. │ ├── occam-harness/ # Master 5-phase orchestrator + scientific foundations reference
  128. │ ├── occam-brainstorm/ # Socratic questioner + contradiction analyzer + 1-page spec template
  129. │ ├── occam-research-gate/ # Primary-source hierarchy + evidence ledger template
  130. │ └── occam-frugal-router/ # T0–T3 routing ladder + cross-vendor model tier table
  131. ├── adapters/
  132. │ ├── cursor/rules/ # Modular .mdc rules (1 tiny alwaysApply + 3 agent-requested)
  133. │ └── copilot/ # GitHub Copilot instructions adapter
  134. ├── scripts/ # Tier 0 stdlib Python CLI (occam, repo_map, trim_run, ledger, cite_check, token_budget)
  135. ├── benchmarks/ # Reproducible offline benchmark suite + results.md + SVG chart generator
  136. ├── tests/ # unittest suite (11 tests: scripts, YAML parser, installer E2E)
  137. └── .github/workflows/ci.yml # Automated CI across Python 3.9 and 3.12
  138. ```
  139. ---
  140. ## Open Source & Contributing
  141. `occam-kit` is **100% free and open source under the [MIT License](LICENSE)** — fork it, customize it, bundle it into teams, or contribute new language extractors and adapters. See [CONTRIBUTING.md](CONTRIBUTING.md).
  142. ```bash
  143. python3 scripts/occam.py audit skills --max-startup-tokens 350
  144. python3 -m unittest discover -s tests -v
  145. python3 benchmarks/run_benchmarks.py --write
  146. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.