CLI Scripts Framework
Relevant source files
The following files were used as context for generating this wiki page:
The CLI Scripts Framework provides a library of agent-agnostic, reusable Python workflows designed to orchestrate Model Context Protocol (MCP) tools. These scripts are optimized for performance and token efficiency, particularly when used with Claude Code. By utilizing command-line arguments instead of hardcoded values, the framework achieves a 99.6% token reduction compared to writing custom scripts from scratch for every task.
Sources: scripts/README.md:3-8, scripts/SCRIPTS.md:14-25, CLAUDE.md:32-41
Framework Philosophy and Architecture
The framework operates on the principle of "Progressive Disclosure." Instead of loading entire schemas into the AI's context, the agent discovers available capabilities via the filesystem, reads the specific script documentation, and executes it with precise CLI arguments.
Key Principles
- Parameter Immutability: Parameters are changed via CLI arguments, never by editing the script files.
- Logic Mutability: Developers are encouraged to edit script logic freely to improve workflows or fix bugs.
- Agent Agnosticism: While optimized for Claude Code, the scripts function with any AI agent capable of executing shell commands.
Sources: scripts/SCRIPTS.md:33-40, scripts/SCRIPTS.md:104-110
Operational Intelligence Flow
The following diagram illustrates how an AI agent interacts with the CLI Scripts Framework to perform complex tasks.
The diagram shows the standard 3-step loop: Discovery, Inspection, and Execution with arguments.
Sources: scripts/SCRIPTS.md:43-52, CLAUDE.md:43-52
Core Components and Workflow Execution
The framework relies on a combination of Python's argparse for parameter handling and an asyncio runtime for managing MCP tool calls.
Script Structure
All scripts within the framework follow a standardized template:
- Docstrings: Detailed
SKILL,DESCRIPTION, andUSAGEsections. - Argument Parsing: An
argparseimplementation that filters out the script path added by the harness. - Tool Chaining: Asynchronous functions that call one or more MCP tools via a client manager.
Sources: scripts/SCRIPTS.md:65-101, scripts/multi_tool_pipeline.py:27-37
Argument Parsing Implementation
To ensure compatibility with the runtime.harness execution wrapper, scripts must filter sys.argv to remove the script filename itself.
def parse_args():
parser = argparse.ArgumentParser()
# Define arguments here
parser.add_argument("--repo-path", default=".")
# Filter out script path from sys.argv
args_to_parse = [arg for arg in sys.argv[1:] if not arg.endswith(".py")]
return parser.parse_args(args_to_parse)
Sources: scripts/README.md:69-72, scripts/multi_tool_pipeline.py:35-36
Comparison: Scripts vs. Skills
The project distinguishes between "Scripts" (universal CLI workflows) and "Skills" (Claude Code-native metadata).
| Feature | Scripts (./scripts/) | Skills (.claude/skills/) |
|---|---|---|
| Format | Python with argparse | YAML + Markdown (SKILL.md) |
| Discovery | Manual (ls, cat) | Auto-scanned by Claude Code |
| Target | Any AI Agent | Claude Code Only |
| Efficiency | 99.6% token reduction | Native progressive disclosure |
| Relationship | The underlying logic | The wrapper referencing scripts |
Sources: scripts/README.md:42-60, CLAUDE.md:6-10
Current Scripts Library
The framework includes several pre-built scripts for common developer workflows.
| Category | Script | Key CLI Arguments | Description |
|---|---|---|---|
| Web | firecrawl_scrape.py | --url | Web scraping via Firecrawl API. |
| Local Web | web_scrape_local.py | <url>, --format | Local scraping via trafilatura. |
| Git | multi_tool_pipeline.py | --repo-path, --max-commits | Orchestrates multiple git tool calls. |
| Editing | morph_apply.py | --file, --instruction, --code_edit | AI-assisted targeted code changes. |
| Search | perplexity_search.py | --query | Web research via Perplexity API. |
Sources: scripts/README.md:19-38, scripts/SCRIPTS.md:102, scripts/morph_apply.py:34-42
Multi-Tool Chaining Logic
Scripts can chain multiple MCP tools to create complex pipelines. For example, multi_tool_pipeline.py executes three distinct steps sequentially to gather repository intelligence.
This sequence shows how the script acts as an orchestrator for multiple atomic MCP tool calls.
Sources: scripts/multi_tool_pipeline.py:40-77
Efficiency and Performance Metrics
The framework is designed to minimize the token footprint of AI interactions. By using CLI arguments instead of re-writing or editing script files, the token consumption for a single tool interaction is reduced from ~5,000 tokens to approximately 110 tokens.
| Action | Token Cost | Time Cost |
|---|---|---|
| Writing script from scratch | ~5,000 tokens | ~120 seconds |
| Editing file to change params | ~800 tokens | ~30 seconds |
| CLI execution with arguments | ~110 tokens | ~5 seconds |
Sources: scripts/SCRIPTS.md:27-38
Conclusion
The CLI Scripts Framework serves as the high-efficiency backbone of Continuous Claude's MCP orchestration. By standardizing on Python-based CLI templates, the project enables agents to perform complex multi-step operations—such as repository analysis and targeted code editing—with minimal context overhead and high reliability.
Sources: scripts/README.md:84-85, CLAUDE_ONBOARDING.md:143-149