# 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)

{
  "mcpServers": {
    "codexsaver": {
      "command": "python",
      "args": ["-m", "codexsaver.mcp_server"],
      "env": {}
    }
  }
}

{
  "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"
  }
}

export DEEPSEEK_API_KEY="your-key-here"

# 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"
  }
}

{
  "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"
}

{
  "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
  }
}

{
  "tool": "codexsaver.orchestrate",
  "arguments": {
    "task_description": "Explain config module and review performance",
    "files": ["codexsaver/config.py"],
    "mode": "execute"
  }
}

{
  "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..."
  }
}

codexsaver init

codexsaver preview "Write unit tests for auth module" --files src/auth.py

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 .

# 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

# Explainer
codexsaver specialist explainer "Explain this module" \
  --files codexsaver/router.py

# Performance Reviewer
codexsaver specialist perf_reviewer "Review performance" \
  --files codexsaver/delegate.py

# Basic: AGENTS.md guidance only
codexsaver superpower install --profile basic --workspace .

# Full: AGENTS.md + hooks + local config
codexsaver superpower install --profile full --workspace .

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"])

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")

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}")

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.

# Via MCP tool
{
  "tool": "codexsaver.delegate_task",
  "arguments": {
    "task_description": "Add docstrings to all public functions in utils",
    "files": ["src/utils.py"],
    "mode": "execute"
  }
}

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 .

codexsaver orchestrate "Explain auth flow and review performance" \
  --files src/auth.py

{
  "tool": "codexsaver.delegate_task",
  "arguments": {
    "task_description": "Refactor authentication middleware",
    "files": ["src/auth/middleware.py"],
    "mode": "execute"
  }
}

{
  "interaction": {
    "mode": "codex_takeover",
    "headline": "CodexSaver kept this task with Codex",
    "route_label": "[CodexSaver] route=codex reason=protected_path"
  }
}

codexsaver orchestrate "Document API, explain usage, and add examples" \
  --files codexsaver/api.py

{
  "routing": {
    "protected_paths": ["src/auth/", "billing/", "*.key"],
    "risk_threshold": "medium",
    "force_codex_patterns": ["payment", "security", "migrate"]
  }
}

{
  "worker_compression": {
    "enabled": true,
    "level": "medium"
  }
}

{
  "interaction": {
    "compression": {
      "active": true,
      "level": "medium",
      "notice": "Worker output compressed to medium level"
    }
  }
}

# Verify MCP server config
cat ~/.config/codex/mcp.json

# Test MCP server manually
python -m codexsaver.mcp_server

# Restart Codex after config changes

# Set environment variable
export DEEPSEEK_API_KEY="sk-..."

# Verify config
cat ~/.codexsaver/config.json

# Test provider directly
codexsaver preview "test task" --files README.md

# Check allowed commands are valid
codexsaver work-packet \
  "test task" \
  --allowed-command "python -c 'import sys; sys.exit(0)'" \
  --acceptance "passes basic check" \
  --workspace . \
  --verbose

# Increase max iterations
codexsaver work-packet \
  "complex task" \
  --max-iterations 5 \
  --workspace .

{
  "routing": {
    "risk_threshold": "low",
    "protected_paths": []
  }
}

# Required for DeepSeek (default provider)
export DEEPSEEK_API_KEY="sk-..."

# Optional alternative providers
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="..."
export QWEN_API_KEY="..."

# Optional: override config path
export CODEXSAVER_CONFIG_PATH="/custom/path/config.json"

{
  "provider": "openai",
  "openai": {
    "api_key_env": "OPENAI_API_KEY",
    "model": "gpt-4o-mini"
  }
}