>_
Marketplace

cache-metrics

Analyzes the codex cache and generates comprehensive statistics about cache performance, storage usage, and health status. Delegates to fractary CLI for cache analysis operations.

model: claude-haiku-4-5

$ Installer

git clone https://github.com/fractary/claude-plugins /tmp/claude-plugins && cp -r /tmp/claude-plugins/plugins/codex/skills/cache-metrics ~/.claude/skills/claude-plugins

// tip: Run this command in your terminal to install the skill

SKILL.md
View on GitHub →

name: cache-metrics model: claude-haiku-4-5 description: | Analyzes the codex cache and generates comprehensive statistics about cache performance, storage usage, and health status. Delegates to fractary CLI for cache analysis operations. tools: Bash, Skill version: 4.0.0

Your responsibility is to analyze the codex cache and generate comprehensive statistics by delegating to the cli-helper skill which invokes the fractary codex cache stats CLI command.

Architecture (v4.0):

cache-metrics skill
  ↓ (delegates to)
cli-helper skill
  ↓ (invokes)
fractary codex cache stats
  ↓ (uses)
@fractary/codex SDK (CacheManager)

This provides comprehensive cache metrics including performance, storage usage, and health status via the TypeScript SDK.

<CRITICAL_RULES>

  1. ALWAYS delegate to cli-helper - Never execute operations directly
  2. NEVER invoke bash scripts - The CLI handles all operations
  3. ALWAYS preserve CLI error messages - Pass through verbatim
  4. NEVER bypass the CLI - Don't implement custom metrics calculation logic
  5. READ-ONLY operation - Never modify cache or index
  6. Format for readability - CLI provides data, skill formats display </CRITICAL_RULES>

Step 1: Build CLI Arguments

Construct arguments array from inputs:

args = ["cache", "stats"]

// Add category filter if specified
if (category && category !== "all") {
  args.push("--category", category)
}

// Add history flag if requested
if (include_history) {
  args.push("--include-history")
}

Step 2: Delegate to CLI Helper

USE SKILL: cli-helper Operation: invoke-cli Parameters:

{
  "command": "cache",
  "args": ["stats", ...category_filter, ...history_flag],
  "parse_output": true
}

The cli-helper will:

  1. Validate CLI installation
  2. Execute: fractary codex cache stats [--category <c>] [--include-history] --json
  3. Parse JSON output
  4. Return results

Step 3: Process CLI Response

The CLI returns JSON like:

{
  "status": "success",
  "operation": "cache-stats",
  "cache": {
    "total_documents": 156,
    "total_size_bytes": 47411200,
    "total_size_mb": 45.2,
    "fresh_documents": 142,
    "expired_documents": 14,
    "fresh_percentage": 91.0,
    "last_cleanup": "2025-01-07T14:30:00Z",
    "cache_path": ".fractary/codex/cache"
  },
  "performance": {
    "cache_hit_rate": 94.5,
    "avg_cache_hit_ms": 12,
    "avg_fetch_ms": 847,
    "total_fetches": 1247,
    "cache_hits": 1178,
    "cache_misses": 69,
    "failed_fetches": 3,
    "failure_rate": 0.2
  },
  "sources": [
    {
      "name": "fractary-codex",
      "documents": 120,
      "size_bytes": 40265318,
      "size_mb": 38.4,
      "ttl_days": 7,
      "fresh": 112,
      "expired": 8
    }
  ],
  "storage": {
    "disk_used_bytes": 47411200,
    "disk_used_mb": 45.2,
    "compression_enabled": false,
    "largest_documents": [
      {
        "uri": "codex://fractary/arch/architecture.md",
        "size_bytes": 2516582,
        "size_mb": 2.4
      }
    ],
    "growth_rate_mb_per_week": 5.0
  },
  "health": {
    "status": "healthy",
    "cache_accessible": true,
    "index_valid": true,
    "corrupted_entries": 0,
    "disk_free_percent": 87
  },
  "recommendations": [
    "Consider enabling compression to save disk space",
    "Clear 14 expired documents: /fractary-codex:cache-clear --expired"
  ]
}

IF status == "success":

  • Extract metrics from CLI response
  • Proceed to formatting
  • CONTINUE

IF status == "failure":

  • Extract error message from CLI
  • Return error to caller
  • DONE (with error)

Step 4: Format Output

IF format == "json":

  • Return raw CLI output
  • DONE ✅

IF format == "formatted" (default):

  • Create human-readable display (see OUTPUTS section)
  • Apply category filtering
  • Include recommendations
  • CONTINUE

Step 5: Return Results

Display formatted output to user.

COMPLETION: Operation complete when metrics are shown.

<COMPLETION_CRITERIA> Operation is complete when:

✅ For successful metrics:

  • CLI invoked successfully
  • Metrics retrieved and calculated
  • Output formatted (if requested)
  • Recommendations included
  • Results displayed to user

✅ For failed metrics:

  • Error captured from CLI
  • Error message clear and actionable
  • Results returned to caller

✅ In all cases:

  • No direct script execution
  • CLI handles all operations
  • Structured response provided </COMPLETION_CRITERIA>

Formatted Output (Default)

📊 Codex Knowledge Retrieval Metrics
═══════════════════════════════════════════════════════════

CACHE STATISTICS
───────────────────────────────────────
Total Documents:     156
Total Size:          45.2 MB
Fresh Documents:     142 (91.0%)
Expired Documents:   14 (9.0%)
Last Cleanup:        2025-01-07 14:30 UTC
Cache Path:          .fractary/codex/cache

PERFORMANCE METRICS
───────────────────────────────────────
Cache Hit Rate:      94.5%
Avg Hit Time:        12 ms
Avg Fetch Time:      847 ms
Total Fetches:       1,247
  - Cache Hits:      1,178
  - Cache Misses:    69
Failed Fetches:      3 (0.2%)

SOURCE BREAKDOWN
───────────────────────────────────────
fractary-codex:
  Documents:         120
  Size:              38.4 MB
  TTL:               7 days
  Fresh:             112 (93.3%)
  Expired:           8 (6.7%)

STORAGE USAGE
───────────────────────────────────────
Disk Used:           45.2 MB
Compression:         Disabled
Growth Rate:         ~5.0 MB/week
Largest Documents:
  1. codex://fractary/arch/architecture.md (2.4 MB)

HEALTH STATUS
───────────────────────────────────────
Status:              ✓ Healthy
Cache Accessible:    Yes
Index Valid:         Yes
Corrupted Entries:   0
Disk Free:           87%

═══════════════════════════════════════════════════════════
Recommendations:
  • Consider enabling compression to save disk space
  • Clear 14 expired documents: /fractary-codex:cache-clear --expired
═══════════════════════════════════════════════════════════

Filtered Output (category: "cache")

📊 Cache Statistics
───────────────────────────────────────
Total Documents:     156
Total Size:          45.2 MB
Fresh Documents:     142 (91.0%)
Expired Documents:   14 (9.0%)
Last Cleanup:        2025-01-07 14:30 UTC

JSON Output (format: "json")

Returns raw CLI JSON response (see Step 3 for structure).

Empty Cache

📊 Codex Knowledge Retrieval Metrics
═══════════════════════════════════════════════════════════

CACHE STATISTICS
───────────────────────────────────────
Cache is empty (0 documents)
───────────────────────────────────────
Use /fractary-codex:fetch to retrieve documents

Failure Response: CLI Error

{
  "status": "failure",
  "operation": "cache-stats",
  "error": "Cache index corrupted",
  "cli_error": {
    "message": "Failed to parse cache index",
    "suggested_fixes": [
      "Run: fractary codex cache clear --all",
      "Cache will be rebuilt on next fetch"
    ]
  }
}

Failure Response: CLI Not Available

{
  "status": "failure",
  "operation": "cache-stats",
  "error": "CLI not available",
  "suggested_fixes": [
    "Install globally: npm install -g @fractary/cli",
    "Or ensure npx is available"
  ]
}

<ERROR_HANDLING>

Cache Not Found

When CLI reports cache doesn't exist:

  1. Show "Cache not initialized yet" message
  2. NOT an error condition
  3. Suggest fetching documents to populate

Index Invalid

When CLI reports corrupted index:

  1. Show CLI's error message
  2. Suggest: fractary codex cache clear --all
  3. Explain cache is regeneratable
  4. Return error to caller

Calculation Errors

When CLI encounters calculation issues:

  1. Show partial metrics if available
  2. Note which metrics couldn't be calculated
  3. Suggest checking cache health

CLI Not Available

When cli-helper reports CLI unavailable:

  1. Pass through installation instructions
  2. Don't attempt workarounds
  3. Return clear error to caller

CLI Command Failed

When CLI returns error:

  1. Preserve exact error message from CLI
  2. Include suggested fixes if CLI provides them
  3. Add context about what was being analyzed
  4. Return structured error

</ERROR_HANDLING>

Success (Formatted):

🎯 STARTING: cache-metrics
Category: {category}
Format: formatted
───────────────────────────────────────

[Formatted metrics display]

✅ COMPLETED: cache-metrics
Analyzed {count} cache entries
Total size: {size}
Source: CLI (via cli-helper)
───────────────────────────────────────

Success (JSON):

🎯 STARTING: cache-metrics
Category: {category}
Format: json
───────────────────────────────────────

[JSON metrics]

✅ COMPLETED: cache-metrics
Source: CLI (via cli-helper)
───────────────────────────────────────

Failure:

🎯 STARTING: cache-metrics
───────────────────────────────────────

❌ FAILED: cache-metrics
Error: {error_message}
Suggested fixes:
- {fix 1}
- {fix 2}
───────────────────────────────────────

Migration from v3.0

v3.0 (bash scripts):

cache-metrics
  └─ scripts/calculate-metrics.sh
      ├─ reads cache index
      ├─ calculates statistics
      ├─ analyzes performance
      └─ generates recommendations

v4.0 (CLI delegation):

cache-metrics
  └─ delegates to cli-helper
      └─ invokes: fractary codex cache stats

Benefits:

  • ~95% code reduction in this skill
  • TypeScript type safety from SDK
  • More accurate calculations
  • Better performance tracking
  • Built-in recommendations
  • Automatic health checks

CLI Command Used

This skill delegates to:

fractary codex cache stats [--category <category>] [--include-history] --json

SDK Features Leveraged

Via the CLI, this skill benefits from:

  • CacheManager.getStats() - Statistics calculation
  • Automatic freshness calculation
  • Performance tracking (if enabled)
  • Storage analysis
  • Health assessment
  • Recommendation engine

Metric Categories

Cache Statistics:

  • Total documents
  • Size breakdown
  • Freshness status
  • Last cleanup time

Performance Metrics:

  • Cache hit rate
  • Average hit/fetch times
  • Total operations
  • Failure rate

Source Breakdown:

  • Documents per source
  • Size per source
  • Freshness per source
  • TTL settings

Storage Usage:

  • Disk space used
  • Compression status
  • Largest documents
  • Growth trends

Health Status:

  • Accessibility
  • Index validity
  • Corruption detection
  • Disk space warnings

Recommendations

The CLI automatically generates recommendations based on:

  • Poor hit rate (< 80%): Adjust TTL, prefetch common docs
  • High storage (> 500 MB): Enable compression, clear expired
  • Many expired (> 20%): Clear expired docs, review TTL
  • Health issues: Specific resolution steps

Testing

To test this skill:

# Ensure CLI installed
npm install -g @fractary/cli

# Populate cache first
fractary codex fetch codex://fractary/codex/README.md

# Test all metrics
USE SKILL: cache-metrics
Parameters: {
  "category": "all",
  "format": "formatted"
}

# Test specific category
USE SKILL: cache-metrics
Parameters: {
  "category": "performance",
  "format": "json"
}

Troubleshooting

If metrics fail:

  1. Check CLI installation: fractary --version
  2. Check cache exists: fractary codex cache list
  3. Test CLI directly: fractary codex cache stats
  4. Run health check: fractary codex health
  5. Check index: .fractary/codex/cache/.cache-index.json

Repository

fractary
fractary
Author
fractary/claude-plugins/plugins/codex/skills/cache-metrics
1
Stars
0
Forks
Updated1d ago
Added1w ago

Actions

View on GitHubDownload ZIPReport Issue

Related Skills

skill-writer
pytorch/pytorch
95.4k
docstring
pytorch/pytorch
95.4k
at-dispatch-v2
pytorch/pytorch
95.4k
add-uint-support
pytorch/pytorch
95.4k
skill-creator
openai/codex
54.7k