Metadata-Version: 2.4
Name: sigil-py
Version: 1.3.0
Summary: An autonomous AI coding agent that codes while you don't.
Project-URL: Homepage, https://github.com/dylan-murray/sigil
Project-URL: Repository, https://github.com/dylan-murray/sigil.git
Project-URL: Issues, https://github.com/dylan-murray/sigil/issues
Author: Dylan Murray
License: Apache-2.0
License-File: LICENSE
Keywords: agent,ai,automation,code-quality,llm,refactoring
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: litellm>=1.83.14
Requires-Dist: mcp>=1.26.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pygithub>=2.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: tenacity>=9.1.4
Requires-Dist: typer>=0.15
Description-Content-Type: text/markdown

<p align="center">
  <img alt="Sigil" src="assets/logo.svg" width="320">
</p>

<p align="center">
  <strong>Your codebase gets better every night. Automatically.</strong>
</p>

<p align="center">
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-3776ab?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+"></a>
  <a href="https://github.com/astral-sh/uv"><img src="https://img.shields.io/badge/uv-package%20manager-de5fe9?style=flat-square&logo=astral&logoColor=white" alt="uv"></a>
  <a href="https://docs.litellm.ai/"><img src="https://img.shields.io/badge/LLM-100%2B%20models-ff6b6b?style=flat-square" alt="100+ LLM models"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-green?style=flat-square" alt="Apache 2.0 License"></a>
  <a href="https://github.com/dylan-murray/sigil/actions/workflows/tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/dylan-murray/sigil/tests.yml?branch=main&style=flat-square&label=build" alt="Build"></a>
  <a href="https://github.com/dylan-murray/sigil/actions/workflows/codeql.yml"><img src="https://img.shields.io/github/actions/workflow/status/dylan-murray/sigil/codeql.yml?branch=main&style=flat-square&label=CodeQL" alt="CodeQL"></a>
  <a href="https://github.com/dylan-murray/sigil/actions/workflows/semgrep.yml"><img src="https://img.shields.io/github/actions/workflow/status/dylan-murray/sigil/semgrep.yml?branch=main&style=flat-square&label=Semgrep" alt="Semgrep"></a>
</p>

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](examples/sigil.yml), and push. Bring any model — OpenAI, Anthropic, Gemini, DeepSeek, or [100+ more](https://docs.litellm.ai/).

## 🤔 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](https://github.com/astral-sh/uv), and an API key for your model provider.

```bash
# 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`](examples/sigil.yml) for a copy-paste ready workflow.

```yaml
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](https://docs.litellm.ai/) — pass whichever API key your model provider needs via `env:`.

<details>
<summary>Action inputs</summary>

| Input | Default | Description |
|---|---|---|
| `github-token` | `github.token` | Token for git and PR operations. Pass a [PAT](https://github.com/settings/tokens) to trigger CI on Sigil PRs |
| `dry-run` | `false` | Passed as `--dry-run` |
| `sigil-version` | `sigil-py` | Package spec for `uv tool install` |

</details>

<details>
<summary>Required repo settings</summary>

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

</details>

## 🔬 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.

```text
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`.

<details>
<summary>Full config reference</summary>

```yaml
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"
```

</details>

### 🎚️ 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

```text
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

```bash
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
