codexsaver-cost-router

# CodexSaver Cost Router > Skill by [ara.so](https://ara.so) — Codex Skills collection. CodexSaver is an MCP tool that makes Codex cost-aware by routing low-risk development work (tests, docs, search, explanation) to cheaper worker LLMs while keeping Codex responsible for architecture, security, and final review. It supports DeepSeek by default with presets for OpenAI, Anthropic, Gemini, Qwen, Ollama, and LM Studio. ## Core Concepts CodexSaver operates in three modes: - **Preview Mode**: Shows routing decision without executing - **V2 Bounded Work Packets**: Single-task delegation with sandboxed patch application and verification - **V3 Orchestrated Specialists**: Parallel readonly specialists (explainer, perf_reviewer) and mixed graphs for docs/tests/impl **Key principle**: Codex handles judgment and risk, worker models handle volume and repetition. ## Installation ### Global MCP Tool Setup ```bash # Clone repository git clone https://github.com/fendouai/CodexSaver.git cd CodexSaver # Install globally pip install -e . # Initialize config codexsaver init # Add to Codex MCP config (~/.config/codex/mcp.json or workspace .codex/mcp.json) ``` Add to `mcp.json`: ```json { "mcpServers": { "codexsaver": { "command": "python", "args": ["-m", "codexsaver.mcp_server"], "env": {} } } } ``` ### Configuration Edit `~/.codexsaver/config.json`: ```json { "provider": "deepseek", "deepseek": { "api_key_env": "DEEPSEEK_API_KEY", "model": "deepseek-chat", "base_url": "https://api.deepseek.com" }, "openai": { "api_key_env": "OPENAI_API_KEY", "model": "gpt-4o-mini" }, "worker_compression": { "enabled": true, "level": "medium" }, "routing": { "protected_paths": ["src/auth/", "payment/", ".env"], "risk_threshold": "medium" } } ``` Set environment variable: ```bash export DEEPSEEK_API_KEY="your-key-here" ``` ## MCP Tools Reference ### 1. `codexsaver.delegate_task` Route a task to the worker model with automatic risk assessment. **Parameters**: - `task_description` (required): Task to delegate - `files` (optional): List of file paths for context - `mode` (optional): `preview` or `execute` (default: `execute`) **Example call from Codex**: ```python # Codex calls this internally via MCP { "tool": "codexsaver.delegate_task", "arguments": { "task_description": "Write docstrings for all public functions", "files": ["src/utils.py"], "mode": "execute" } } ``` **Response structure**: ```json { "interaction": { "tool": "codexsaver.delegate_task", "mode": "delegated_execution", "headline": "CodexSaver delegated this task to DeepSeek", "route_label": "[CodexSaver] route=deepseek task_type=write_docs risk=low", "next_step": "Review the worker result and apply if safe" }, "result": "Delegated task output...", "cost_savings": "45%", "provider": "deepseek" } ``` ### 2. `codexsaver.delegate_work_packet` V2: Execute bounded work with sandbox verification. **Parameters**: - `goal` (required): Clear task goal - `files` (optional): Context files - `allowed_files` (required): Globs for writable files - `forbidden_paths` (optional): Protected paths - `acceptance_criteria` (required): Success conditions - `allowed_commands` (required): Verification commands - `max_iterations` (optional): Default 3 - `max_diff_lines` (optional): Default 500 **Example**: ```python { "tool": "codexsaver.delegate_work_packet", "arguments": { "goal": "Add type hints to config loader", "files": ["codexsaver/config.py"], "allowed_files": ["codexsaver/config.py"], "forbidden_paths": ["codexsaver/auth/"], "acceptance_criteria": "All public functions have type hints", "allowed_commands": ["mypy codexsaver/config.py"], "max_iterations": 3, "max_diff_lines": 200 } } ``` ### 3. `codexsaver.orchestrate` V3: Orchestrate specialists for complex tasks. **Parameters**: - `task_description` (required): High-level task - `files` (optional): Context files - `mode` (optional): `preview` or `execute` **Example**: ```python { "tool": "codexsaver.orchestrate", "arguments": { "task_description": "Explain config module and review performance", "files": ["codexsaver/config.py"], "mode": "execute" } } ``` **Response for readonly_swarm**: ```json { "status": "success", "graph_type": "readonly_swarm", "findings": 10, "quality_score": 0.75, "latency_seconds": 6.45, "cost_savings": "52%", "results": { "explainer": "Config module loads from ~/.codexsaver/config.json...", "perf_reviewer": "No blocking I/O, caching recommended..." } } ``` ## CLI Commands ### Initialize Configuration ```bash codexsaver init ``` Creates `~/.codexsaver/config.json` with DeepSeek defaults. ### Preview Routing Decision ```bash codexsaver preview "Write unit tests for auth module" --files src/auth.py ``` Shows routing decision without executing. ### Execute Work Packet ```bash codexsaver work-packet \ "Add docstrings to public functions" \ --files src/utils.py \ --allowed-file src/utils.py \ --acceptance "All functions have docstrings" \ --allowed-command "python -m pydoc src.utils" \ --workspace . ``` ### Orchestrate Specialists ```bash # Readonly specialists (fastest, most reliable) codexsaver orchestrate "Explain installer flow and review performance" \ --files codexsaver/install.py # Mixed graph (docs + explain) codexsaver orchestrate "Document API and explain usage patterns" \ --files codexsaver/api.py # Dry run codexsaver orchestrate "Implement login and add tests" \ --files src/auth.py \ --dry-run ``` ### Run Single Specialist ```bash # Explainer codexsaver specialist explainer "Explain this module" \ --files codexsaver/router.py # Performance Reviewer codexsaver specialist perf_reviewer "Review performance" \ --files codexsaver/delegate.py ``` ### Install Project Guidance ```bash # Basic: AGENTS.md guidance only codexsaver superpower install --profile basic --workspace . # Full: AGENTS.md + hooks + local config codexsaver superpower install --profile full --workspace . ``` ## Python API ### Direct Delegation ```python from codexsaver.delegate import delegate_task result = delegate_task( task_description="Write docstrings for utils module", files=["src/utils.py"], mode="execute" ) print(result["interaction"]["route_label"]) print(result["result"]) ``` ### Work Packet Execution ```python from codexsaver.work_packet import execute_work_packet result = execute_work_packet( goal="Add type hints to config loader", files=["codexsaver/config.py"], allowed_files=["codexsaver/config.py"], acceptance_criteria="All functions have type hints", allowed_commands=["mypy codexsaver/config.py"], workspace_root="." ) if result["status"] == "success": print(f"Patch applied: {result['changed_files']}") elif result["preflight_satisfied"]: print("Task already satisfied, no work needed") ``` ### Specialist Orchestration ```python from codexsaver.orchestrate import orchestrate_task result = orchestrate_task( task_description="Explain config module and review performance", files=["codexsaver/config.py"], mode="execute" ) if result["status"] == "success": print(f"Graph type: {result['graph_type']}") print(f"Findings: {result['findings']}") print(f"Quality score: {result['quality_score']}") for specialist, output in result["results"].items(): print(f"\n{specialist}:\n{output}") ``` ### Router Configuration ```python from codexsaver.router import Router router = Router() # Check if task is safe to delegate decision = router.should_delegate( task_description="Write unit tests", files=["src/utils.py"] ) print(f"Route: {decision['route']}") # 'deepseek' or 'codex' print(f"Risk: {decision['risk_level']}") # 'low', 'medium', 'high' print(f"Task type: {decision['task_type']}") # 'write_tests', 'explain', etc. ``` ## Common Patterns ### Pattern 1: Low-Risk Documentation Work **When to use**: Adding or updating docs, docstrings, README sections ```python # Via MCP tool { "tool": "codexsaver.delegate_task", "arguments": { "task_description": "Add docstrings to all public functions in utils", "files": ["src/utils.py"], "mode": "execute" } } ``` **Expected route**: `deepseek` (low risk, high volume) ### Pattern 2: Bounded Test Generation **When to use**: Creating tests for well-defined modules ```bash codexsaver work-packet \ "Write pytest tests for config loader" \ --files codexsaver/config.py \ --allowed-file tests/test_config.py \ --acceptance "tests/test_config.py exists and pytest passes" \ --allowed-command "pytest tests/test_config.py -v" \ --workspace . ``` **Expected route**: `deepseek` with sandbox verification ### Pattern 3: Readonly Analysis **When to use**: Code explanation, performance hints, security scan (no patches) ```bash codexsaver orchestrate "Explain auth flow and review performance" \ --files src/auth.py ``` **Expected route**: `readonly_swarm` (parallel explainer + perf_reviewer) ### Pattern 4: Codex Takeover for High-Risk Work **When to use**: Auth, payment, destructive migrations, ambiguous architecture ```python { "tool": "codexsaver.delegate_task", "arguments": { "task_description": "Refactor authentication middleware", "files": ["src/auth/middleware.py"], "mode": "execute" } } ``` **Expected route**: `codex` (protected path detected) Response includes: ```json { "interaction": { "mode": "codex_takeover", "headline": "CodexSaver kept this task with Codex", "route_label": "[CodexSaver] route=codex reason=protected_path" } } ``` ### Pattern 5: Mixed Graph Orchestration **When to use**: Docs + explanation + small impl changes ```bash codexsaver orchestrate "Document API, explain usage, and add examples" \