Skip to content

README.md

Latest commit

 

History

History
325 lines (239 loc) · 8.76 KB

README.md

File metadata and controls

325 lines (239 loc) · 8.76 KB

Claude Code - Execution Runtime

Python package for Claude Code implementing the Anthropic code execution pattern for 90%+ token savings.

Overview

The Execution Runtime provides pre-built Python APIs for bulk code operations with massive token savings. Instead of loading all code and data through the context window, you write Python scripts that execute locally and return only results—achieving up to 99% token reduction for complex operations.

What Claude Code already provides: Sandboxing, resource limits, timeouts, directory restrictions

What this package adds: Pre-built APIs for bulk operations, PII/secret masking, metadata-only code analysis

Key Benefits

✅ 90-99% Token Savings - Process 100 files using 1,000 tokens instead of 100,000 ✅ Faster Operations - Local execution vs multiple API round-trips ✅ Stateful Workflows - Resume multi-step refactoring across sessions ✅ Automatic PII Masking - Secret detection before results return to context ✅ Reusable Skills - Save transformation functions for future use

Quick Start

1. Install the package:

cd ~/.claude/plugins/marketplaces/mhattingpete-claude-skills/execution-runtime
pip install -e .

2. Use in your prompts:

from execution_runtime import fs, code, transform, git

# Example: Find all functions
functions = code.find_functions('app.py')
print(f"Found {len(functions)} functions")

# Example: Rename identifier across codebase
result = transform.rename_identifier('.', 'old_name', 'new_name', '**/*.py')
print(f"Modified {result['files_modified']} files")

# Example: Copy lines between files
code_block = fs.copy_lines('source.py', 10, 20)
fs.paste_code('target.py', 50, code_block)

# Example: PII masking when needed
from execution_runtime import mask_secrets
result = {'api_key': 'sk_live_abc123'}
safe_output = mask_secrets(str(result))  # Masks secrets automatically

That's it! Claude Code's built-in sandbox handles security, you get the pre-built APIs and token savings.

Usage

Example 1: Bulk File Refactoring

Traditional approach (high token usage):

User: "Rename getUserData to fetchUserData in all 50 Python files"

Claude:
→ Grep to find files (2K tokens)
→ Read 50 files (50K tokens)
→ Edit 50 files × multiple rounds (50K+ tokens)
Total: ~102K tokens ❌

With execution runtime (low token usage):

User: "Rename getUserData to fetchUserData in all 50 Python files"

Claude writes Python script:
```python
from execution_runtime import transform

result = transform.rename_identifier(
    pattern='.',
    old_name='getUserData',
    new_name='fetchUserData',
    file_pattern='**/*.py'
)

Executes locally, returns:

{
  "files_modified": 50,
  "total_replacements": 127
}

Total: ~600 tokens ✅ (99.4% savings)


### Example 2: Extract Functions to New File

```python
from execution_runtime import code, fs

# Find all utility functions (metadata only, no source in context)
functions = code.find_functions('app.py', pattern='.*_util$')

# Copy each function to utils.py
for func in functions:
    code_block = fs.copy_lines('app.py', func['start_line'], func['end_line'])
    fs.paste_code('utils.py', -1, code_block)  # Append to end

result = {
    "functions_extracted": len(functions),
    "details": [f['name'] for f in functions]
}

Example 3: Code Audit Across 100 Files

from execution_runtime import code
from pathlib import Path

files = list(Path('.').glob('**/*.py'))

audit_results = []
for file in files:
    deps = code.analyze_dependencies(str(file))
    unused = code.find_unused_imports(str(file))

    if unused or deps['complexity'] > 10:
        audit_results.append({
            'file': str(file),
            'complexity': deps['complexity'],
            'unused_imports': unused
        })

result = {
    "files_audited": len(files),
    "issues_found": len(audit_results),
    "high_complexity": [r for r in audit_results if r['complexity'] > 15]
}

Available APIs

1. Filesystem Operations (fs)

from execution_runtime import fs

# Copy specific lines
code = fs.copy_lines('source.py', start_line=10, end_line=20)

# Paste at line number
fs.paste_code('target.py', line_number=50, code=code, create_backup=True)

# Search and replace across files
fs.search_replace(
    file_pattern='**/*.py',
    search='old_function',
    replace='new_function',
    regex=False
)

# Batch operations (process many files at once)
operations = [
    {'source_file': 'a.py', 'start_line': 10, 'end_line': 20,
     'target_file': 'b.py', 'target_line': 5},
    # ... more operations
]
fs.batch_copy(operations)

2. Code Analysis (code)

Returns metadata only, not source code → massive token savings

from execution_runtime import code

# Find functions (returns line numbers, not code)
functions = code.find_functions('app.py', pattern='handle_.*')
# Returns: [{'name': 'handle_request', 'start_line': 45, 'end_line': 60, ...}]

# Find classes with methods
classes = code.find_classes('models.py')
# Returns: [{'name': 'User', 'methods': ['__init__', 'save'], ...}]

# Analyze complexity
deps = code.analyze_dependencies('complex_file.py')
# Returns: {'functions': 25, 'complexity': 87, 'lines': 450}

3. Code Transformation (transform)

from execution_runtime import transform

# Rename across entire codebase
transform.rename_identifier(
    pattern='.',
    old_name='oldName',
    new_name='newName',
    file_pattern='**/*.py'
)

# Remove debug prints
transform.remove_debug_statements('app.py')

# Add docstrings to functions missing them
transform.add_docstrings('module.py', style='google')

4. Git Operations (git)

from execution_runtime import git

# Check status
status = git.git_status()
# Returns: {'files': {'modified': [...], 'untracked': [...]}}

# Stage and commit
git.git_add(['.'])
git.git_commit('feat: refactor authentication module')

# Create branch and push
git.create_branch('feature/new-auth', checkout=True)
git.git_push('origin', 'feature/new-auth')

5. Sessions and Skills

from execution_runtime import Session, save_skill, load_skill

# Create stateful session for complex work
session = Session("modernize-codebase", "Update to Python 3.11+ syntax")

# Save progress periodically
session.save_state({
    'processed': files[:10],
    'remaining': files[10:],
    'errors': []
})

# Resume later
state = session.load_state()
print(f"Processed: {state['processed']}")

# Save reusable transformation skill
save_skill(
    name="remove_debug_logs",
    code="""
def transform(code):
    import re
    code = re.sub(r'^\\s*print\\(.*\\)\\n?', '', code, flags=re.MULTILINE)
    return code
""",
    description="Remove debug print statements"
)

Security

Claude Code handles: Sandboxing, resource limits, timeouts, directory restrictions

This package adds:

Automatic PII/Secret Masking

from execution_runtime import mask_secrets

# Mask sensitive data before returning to context
result = {'api_key': 'sk_live_abc123xyz', 'status': 'success'}
safe_output = mask_secrets(str(result))
# Returns: {'api_key': '[REDACTED_API_KEY]', 'status': 'success'}

Automatically detects and masks:

  • API keys, tokens, passwords
  • AWS/GCP/GitHub credentials
  • Private keys, JWT tokens
  • Database URLs with credentials

Performance Benchmarks

Operation Traditional Execution Savings
Copy 1 function 100 tokens 50 tokens 50%
Refactor 10 files 5,000 tokens 500 tokens 90%
Refactor 50 files 25,000 tokens 600 tokens 97.6%
Analyze 100 files 150,000 tokens 1,000 tokens 99.3%
Full codebase audit 500,000+ tokens 2,000 tokens 99.6%

Troubleshooting

"Module 'execution_runtime' not found"

Install the package:

cd ~/.claude/plugins/marketplaces/mhattingpete-claude-skills/execution-runtime
pip install -e .

"Permission denied" errors

Claude Code's sandbox controls file access. Ensure files are in an allowed directory.

Import errors

The package uses from execution_runtime import fs, code, transform, git. If you see import errors, verify the package is installed correctly.

Resources

License

Apache 2.0

Support