crux-utils

name	crux-utils
description	Multi-purpose utility for CRUX compression workflows. Provides token estimation and checksum calculation. Use when estimating tokens for compression, comparing file sizes, or getting checksums for sourceChecksum tracking.

CRUX Utils

Multi-purpose utility for CRUX compression workflows. Provides deterministic tools for token estimation and checksum calculation.

Quick Start

# Token count estimation
python3 .cursor/skills/crux-utils/scripts/crux-utils.py --token-count <file>

# Compare source vs CRUX (ratio mode, default target 25%)
python3 .cursor/skills/crux-utils/scripts/crux-utils.py --token-count --ratio <source> <crux>

# Compare with custom target (e.g. 40%)
python3 .cursor/skills/crux-utils/scripts/crux-utils.py --token-count --ratio <source> <crux> --target 40

# Get checksum for sourceChecksum frontmatter
python3 .cursor/skills/crux-utils/scripts/crux-utils.py --cksum <file>

Modes

--token-count <file>

Estimate token count for a single file.

Output:

=== Token Estimate: example.md ===
Prose tokens:      397
Code tokens:       0
Special tokens:    0
---
TOTAL TOKENS:      397

--token-count --ratio <source> <crux> [--target <n>]

Compare source file vs CRUX file and calculate compression ratio.

The --target option sets the compression target percentage (1-100). Defaults to 25 if omitted, matching the CRUX spec's recommended target for text/code content.

Output:

=== Compression Ratio Analysis ===

=== Token Estimate: source.md ===
...
=== Token Estimate: source.crux.md ===
...

=== Compression Summary ===
Source tokens:     397
CRUX tokens:       140
Ratio:             35.2% of original
Reduction:         64.8%
Target (≤25%):     NO

--cksum <file>

Get checksum of a file, formatted for CRUX frontmatter sourceChecksum field.

Output:

=== Checksum: example.md ===
Checksum:          1234567890
---
FRONTMATTER:       "1234567890"

Token Estimation Method

Content Type	Chars/Token	Notes
Prose (markdown)	4.0	English text, headers, lists
Code blocks	3.5	More symbols, shorter identifiers
Special chars	1.0	CRUX Unicode symbols

Special Characters (1 token each)

CRUX delimiters and symbols that count as 1 token each:

• Delimiters: « » ⟨ ⟩
• Arrows/flow: → ← ≻ ≺
• Logic: ⊤ ⊥ ∀ ∃ ¬ ∋
• Relations: ⊳ ⊲
• Comparison: ≥ ≤ ≠
• Blocks: Δ Ρ Λ Π Κ Γ Φ Ω
• Other: ⊛ ◊ θ

Determinism Guarantee

Both modes produce identical output for identical input:

• No random elements
• No timestamp dependencies
• Pure character/pattern counting
• Consistent across runs

Usage in CRUX Workflow

For compression tasks:

1. Get source checksum: --cksum <source> → use FRONTMATTER value for sourceChecksum
2. Estimate source tokens: --token-count <source> → use for beforeTokens
3. After compression: --token-count <crux> → use for afterTokens
4. Verify ratio: --token-count --ratio <source> <crux> → check Target (≤25%)
   • For custom targets: --token-count --ratio <source> <crux> --target 40