sigil-py 1.3.0

An autonomous AI coding agent that codes while you don't.

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:.

Action inputs

Input	Default	Description
github-token	github.token	Token for git and PR operations. Pass a PAT to trigger CI on Sigil PRs
dry-run	false	Passed as --dry-run
sigil-version	sigil-py	Package spec for uv tool install

Required repo settings

1. Settings → Actions → General → Workflow permissions → select "Read and write permissions"
2. Settings → Actions → General → Workflow permissions → check "Allow GitHub Actions to create and approve pull requests"

🔬 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

Stage	What happens
Discover	Scan repo structure, source files, and git history
Learn	Build or refresh .sigil/memory/ knowledge files
Connect MCP	Load configured MCP servers and expose their tools to agents
Analyze + Ideate	Find fixable problems and generate improvement ideas (in parallel)
Validate	Triage candidates — reject weak or risky ones, assign dispositions
Execute	Apply approved work in isolated git worktrees, run pre/post hooks
Publish	Open pull requests and create GitHub issues
Remember	Update working memory so future runs have context

🎛️ Configuration

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

Full config reference

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

	Level	What it does
🐢	conservative	Only the obvious stuff — typos, unused imports, dead code
⚖️	balanced	Safe refactors, missing tests, simple improvements
🔥	bold	New tests, doc rewrites, pattern fixes
🚀	experimental	Feature ideas, architectural suggestions, creative leaps

🛡️ 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:

Agent	What it does
compactor	Distills the raw repo scan into focused .sigil/memory/*.md knowledge files. Runs when knowledge is stale.
selector	Picks which memory files to load into the next stage's context. Runs at the start of every LLM stage.
auditor	Surveys the repo for concrete, fixable problems — bugs, dead code, gaps in tests, doc rot.
ideator	Proposes feature ideas and improvement directions. Runs N instances in parallel across different models for diverse perspectives.
triager	Ranks candidates from the auditor and ideator, assigns each a disposition (PR, issue, or skip), and prioritizes them.
architect	Plans the implementation approach for an approved work item before any code is written.
engineer	Writes code in an isolated git worktree and runs pre/post hooks. Retries on hook failure.
memory	Updates rolling working memory at the end of each run so future runs know what happened.

📁 The .sigil/ Directory

Path	Committed	Purpose
config.yml	Yes	User-controlled configuration
memory/	Yes	Persistent repo knowledge maintained by Sigil
ideas/	Yes	Overflow ideas saved for later runs
attempts.jsonl	Yes	Execution history for learning from past runs
worktrees/	No	Temporary isolated execution sandboxes
traces/	No	LLM call traces (when --trace is used)

📖 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