sigil-py 1.4.0

Your codebase gets better every night. Automatically.

Sigil is an autonomous agent that watches your repo, finds improvements, and ships pull requests — while you sleep. Point it at a codebase, run it on a schedule, and wake up to small, safe PRs for bug fixes, refactors, and new features. It can optionally create GitHub issues for findings that need human review.

Get started in 5 minutes: sigil init, drop the workflow file, and push. Bring any model — OpenAI, Anthropic, Gemini, DeepSeek, or 100+ more.

🤔 Why Sigil?

Every dev tool today is reactive — it waits for you to ask. Sigil is proactive.

While you're focused on feature work, Sigil is in the background catching the stuff that slips through the cracks: dead code nobody noticed, missing test coverage, type safety gaps, inconsistent patterns, and security issues. It doesn't just report problems — it fixes them and opens a PR.

What you get after a run:

• Pull requests for safe, low-risk improvements (bug fixes, dead code removal, type annotations, test gaps)
• Issues (optional) for higher-risk findings that need human review
• Ideas saved to .sigil/ideas/ for future runs to pick up
• Updated knowledge so each run is smarter than the last

⚡ Quickstart

Requirements: Python 3.11+, uv, and an API key for your model provider.

# install
uv tool install sigil-py

# set your provider's API key
export ANTHROPIC_API_KEY=...   # or OPENAI_API_KEY, OPENROUTER_API_KEY, GEMINI_API_KEY, etc.

# initialize and run
cd your-repo
sigil init                     # creates .sigil/config.yml with all options documented
sigil run                      # or --dry-run to analyze without opening PRs

🔄 GitHub Action

Add Sigil to any repo with a single workflow file. It runs on a schedule and opens PRs automatically. See examples/sigil.yml for a copy-paste ready workflow.

name: Sigil

on:
  schedule:
    - cron: '0 2 * * *'    # every night at 2am
  workflow_dispatch:

jobs:
  sigil:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: dylan-murray/sigil@main
        # with:
        #   github-token: ${{ secrets.GITHUB_PAT_TOKEN }}  # optional: use a PAT so Sigil PRs trigger CI
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Sigil uses LiteLLM — pass whichever API key your model provider needs via env:.

🔬 How It Works

Sigil runs an 8-stage async pipeline. Each stage can use a different model, so you can spend more on the hard steps and less on cheap ones.

Discover → Learn → Connect MCP → Analyze + Ideate → Validate → Execute → Publish → Remember

🎛️ Configuration

sigil init creates .sigil/config.yml. All fields are optional except model.

model: anthropic/claude-sonnet-4-6       # default model for all agents

boldness: bold                            # conservative | balanced | bold | experimental
focus:                                    # what to look for
  - tests
  - dead_code
  - security
  - docs
  - types
  - features
  - refactoring

ignore:                                   # glob patterns to skip
  - "vendor/**"
  - "*.generated.*"

max_prs_per_run: 3                        # max PRs opened per run
max_github_issues: 5                      # max issues opened per run
max_ideas_per_run: 15                     # max ideas generated per run
idea_ttl_days: 180                        # auto-prune stale ideas
max_retries: 2                            # retries after post-hook failure
max_parallel_tasks: 3                     # max parallel worktrees
max_spend_usd: 20.0                       # hard cost cap per run
llm_timeout: 300                          # per-call LLM timeout (seconds)

pre_hooks: []                             # run before code generation (failure aborts)
post_hooks: []                            # run after code generation (failure retries)

agents:                                   # per-agent overrides — each value is a list of one or more instances
  architect:
    - model: google/gemini-2.5-pro        # plan quality matters — use a strong model
      # reasoning_effort: high            # low | medium | high — reasoning models only (e.g. openai/o3)
  engineer:
    - model: anthropic/claude-opus-4-6
      max_iterations: 50
  auditor:
    - model: google/gemini-2.5-flash
      max_iterations: 15
  ideator:                                # multi-instance: each entry is a parallel ideator with diverse perspectives
    - model: anthropic/claude-opus-4-7
    - model: openai/gpt-5
    - model: google/gemini-2.5-pro
  compactor:
    - model: anthropic/claude-haiku-4-5-20251001

model_overrides:                          # override context/output limits when litellm's metadata is wrong
  "ollama_chat/gemma4:31b-cloud":
    max_input_tokens: 262144
    max_output_tokens: 262144

mcp_servers:                              # external MCP tool servers
  - name: notion
    command: npx
    args: ["-y", "@notionhq/mcp-server"]
    env:
      NOTION_API_KEY: "${NOTION_API_KEY}"
    purpose: "product requirements and design docs"
  - name: snowflake
    url: "http://localhost:3001/sse"
    purpose: "data warehouse schemas and query results"

🎚️ Boldness — pick your comfort zone

🛡️ Safety

• Isolated execution — code changes happen in git worktrees, never the main working tree
• Pre/post hooks — lint and test gates before and after code generation
• Structured editing — agents use structured tools, not freeform shell commands
• Deduplication — existing PRs and issues are checked before publishing
• Convention-aware — detects and follows AGENTS.md, .cursorrules, CLAUDE.md, and similar repo instructions
• Rate-limited — caps on PRs, issues, and ideas per run prevent spam
• Budget cap — hard limit on total spend per run (max_spend_usd)
• Learns from mistakes — previous attempts inform future runs

🧩 Agents

Each LLM-driven pipeline stage is powered by a specialized agent. Mix and match models per agent — use a strong model where plan quality matters, a cheap one for high-volume bookkeeping. Listed in pipeline order:

📁 The .sigil/ Directory

📖 CLI Reference

sigil init [OPTIONS]       Initialize a new Sigil project
sigil run [OPTIONS]        Run the full pipeline

Options:
  --repo, -r PATH          Repository path (default: .)
  --dry-run                Analyze only; no PRs or issues
  --trace                  Write LLM trace to .sigil/traces/last-run.json
  --refresh                Force a full knowledge rebuild
  --version, -v            Print version and exit

🛠️ Development

git clone https://github.com/dylan-murray/sigil.git
cd sigil
uv sync

uv run pytest tests/ -x -q
uv run ruff check .
uv run ruff format .

License

Apache 2.0