Skylos: Python SAST, Dead Code Detection & Security Auditor

The hybrid static analysis tool for Python. Finds dead code, security leaks, quality rot with agentic AI options and MCP integration.

⭐ If Skylos saves you time (or has helped you in any way), please star the repo — it helps a lot.

💬 Join the Discord (support + contributors): https://discord.gg/Ftn9t9tErf

Skylos is a privacy-first SAST tool for Python, TypeScript, and Go that bridges the gap between traditional static analysis and AI agents. It detects dead code, security vulnerabilities (SQLi, SSRF, Secrets), and code quality issues with high precision.

Unlike standard linters (like Vulture or Bandit) that struggle with dynamic Python patterns, Skylos uses a hybrid engine (AST + optional Local/Cloud LLM). This allows it to:

1. Eliminate False Positives: Distinguishes between truly dead code and framework magic (e.g., pytest.fixture, FastAPI routes).
2. Verify via Runtime: Optional --trace mode validates findings against actual runtime execution.
3. Find Logic Bugs: Goes beyond linting to find deep logic errors that regex-based tools miss.

# Generate a GitHub Actions workflow in 30 seconds
skylos cicd init

# Commit and push to activate
git add .github/workflows/skylos.yml && git push

What you get:

• Automatic dead code detection on every PR
• Security vulnerability scanning (SQLi, secrets, dangerous patterns)
• Quality gate that fails builds on critical issues
• Inline PR review comments with file:line links
• GitHub Annotations visible in the "Files Changed" tab

No configuration needed - works out of the box with sensible defaults. See CI/CD section for customization.

• Quick Start
• Features
• Installation
• Skylos vs Vulture
• Projects Using Skylos
• How It Works
• Agent Analysis
• CI/CD
• MCP Server
• Baseline Tracking
• Gating
• VS Code Extension
• Integration and Ecosystem
• Auditing and Precision
• Coverage Integration
• Filtering
• CLI Options
• FAQ
• Limitations and Troubleshooting
• Contributing
• Roadmap
• License
• Contact

Backup (GitHub): https://github.com/duriantaco/skylos/discussions/82

• Taint Analysis: Traces untrusted input from API endpoints to databases to prevent SQL Injection and XSS.
• Secrets Detection: Hunts down hardcoded API keys (AWS, Stripe, OpenAI) and private credentials before commit.
• Vulnerability Checks: Flags dangerous patterns like eval(), unsafe pickle, and weak cryptography.

• Find Unused Code: Identifies unreachable functions, orphan classes, and unused imports with confidence scoring.
• Smart Tracing: Distinguishes between truly dead code and dynamic frameworks (Flask/Django routes, Pytest fixtures).
• Safe Pruning: Uses LibCST to safely remove dead code without breaking syntax.

• Context-Aware Audits: Combines static analysis speed with LLM reasoning to validate findings and filter noise.
• Automated Fixes: skylos agent fix autonomously patches security flaws and removes dead code.
• End-to-End Remediation: skylos agent remediate scans, fixes, tests, and opens PRs — fully autonomous DevOps agent.
• 100% Local Privacy: Supports Ollama and Local LLMs so your code never leaves your machine.

• CST-safe removals: Uses LibCST to remove selected imports or functions (handles multiline imports, aliases, decorators, async etc..)
• Logic Awareness: Deep integration for Python frameworks (Django, Flask, FastAPI) and TypeScript (Tree-sitter) to identify active routes and dependencies.
• Granular Filtering: Skip lines tagged with # pragma: no skylos, # pragma: no cover, or # noqa

• Coverage Integration: Auto-detects .skylos-trace files to verify dead code with runtime data
• Quality Gates: Enforces hard thresholds for complexity, nesting, and security risk via pyproject.toml to block non-compliant PRs
• Interactive CLI: Manually verify and remove/comment-out findings through an inquirer-based terminal interface
• Security-Audit Mode: Leverages an independent reasoning loop to identify security vulnerabilities

• Unused Fixture Detection: Finds unused @pytest.fixture definitions in test_*.py and conftest.py
• Cross-file Resolution: Tracks fixtures used across modules, not just within the same file

No Node.js required — TypeScript parser is built-in via Tree-sitter. Languages are auto-detected by file extension. Mixed-language repos (e.g. Python + TypeScript) work out of the box.

TypeScript dead code detection tracks: callbacks, type annotations, generics, decorators, inheritance (extends), object shorthand, spread, re-exports, and typeof references. Benchmarked at 95% recall with 0 false positives on alive code.

## from pypi
pip install skylos

## or from source
git clone https://github.com/duriantaco/skylos.git
cd skylos

pip install .

After installation, we recommend:

1. Set up CI/CD (30 seconds):

   skylos cicd init
   git add .github/workflows/skylos.yml && git push

   This will automatically scan every PR for dead code and security issues.

2. Run your first scan:

   skylos .                              # Dead code only
   skylos . --danger --secrets           # Include security checks

3. Try AI-powered analysis:

   skylos agent analyze . --model gpt-4.1

4. Add a badge to your README:

   [![Analyzed with Skylos](https://img.shields.io/badge/Analyzed%20with-Skylos-2f80ed?style=flat&logo=python&logoColor=white)](https://github.com/duriantaco/skylos)

   Shows others you maintain clean, secure code!

See all commands in the Quick Start table

We benchmarked Skylos against Vulture (the standard for dead code detection) on a realistic FastAPI application containing dynamic patterns, framework wiring, and hidden dependencies.

The Results (Confidence Level 20 / Aggressive Mode):

Key Takeaway: Skylos provides significantly higher coverage (Recall) with far less noise (Precision) than traditional tools.

See the full methodology and breakdown in BENCHMARK.md.

Show you're maintaining clean, secure code! Add your project:

Featured Projects:

Project	Description	Badge
Skylos	Python SAST & dead code detection
Your project here	Add yours!

Why share?

• Show commitment to code quality
• Get a backlink to your project
• Join the community of quality-focused developers

Add your project →

Skylos builds a reference graph of your entire codebase - who defines what, who calls what, across all files.

Parse all files -> Build definition map -> Track references -> Find orphans (zero refs = dead)

Static analysis often struggles with Python's dynamic nature (e.g., getattr, pytest.fixture). Skylos minimizes false positives through:

1. Confidence Scoring: Grades findings (High/Medium/Low) so you only see what matters.
2. Hybrid Verification: Uses LLM reasoning to double-check static findings before reporting.
3. Runtime Tracing: Optional --trace mode validates "dead" code against actual runtime execution.

skylos . -c 60  # Default: high-confidence findings only
skylos . -c 30  # Include framework helpers  
skylos . -c 0  # Everything

When Skylos sees Flask, Django, or FastAPI imports, it adjusts scoring automatically:

Tests call code in weird ways that look like dead code. By default, Skylos excludes:

# These are auto-excluded (confidence set to 0)
/project/tests/test_user.py
/project/test/helper.py  

# These are analyzed normally
/project/user.py
/project/test_data.py  # Doesn't end with _test.py

Want test files included? Use --include-folder tests.

When ambiguous, we'd rather miss dead code than flag live code as dead.

Framework endpoints are called externally (HTTP, signals). Name resolution handles aliases. When things get unclear, we err on the side of caution.

Skylos can detect pytest fixtures that are defined but never used.

skylos . --pytest-fixtures

This includes fixtures inside conftest.py, since conftest.py is the standard place to store shared test fixtures.

Skylos uses a hybrid architecture that combines static analysis with LLM reasoning:

Research shows LLMs find vulnerabilities that static analysis misses, while static analysis validates LLM suggestions. However, LLM is extremely prone to false positives in dead code because it doesn't actually do real symbol resolution.

Note: Take dead code output from LLM solely with caution

Skylos supports cloud and local LLM providers:

# Cloud - OpenAI (auto-detected from model name)
skylos agent analyze . --model gpt-4.1

# Cloud - Anthropic (auto-detected from model name)
skylos agent analyze . --model claude-sonnet-4-20250514

# Local - Ollama
skylos agent analyze . \
  --provider openai \
  --base-url http://localhost:11434/v1 \
  --model qwen2.5-coder:7b

Note: You can use the --model flag to specify the model that you want. We support Gemini, Groq, Anthropic, ChatGPT and Mistral.

Skylos can use API keys from (1) skylos key, or (2) environment variables.

skylos key
# opens a menu:
# - list keys
# - add key (openai / anthropic / google / groq / mistral / ...)
# - remove key

Set defaults to avoid repeating flags:

# API Keys
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

# Default to local Ollama
export SKYLOS_LLM_PROVIDER=openai
export SKYLOS_LLM_BASE_URL=http://localhost:11434/v1

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull a code model
ollama pull qwen2.5-coder:7b

# Use with Skylos
skylos agent analyze ./src \
  --provider openai \
  --base-url http://localhost:11434/v1 \
  --model qwen2.5-coder:7b

The remediation agent automates the full fix lifecycle. It scans your project, prioritizes findings, generates fixes via the LLM, validates each fix by running your test suite, and optionally opens a PR.

# Preview what would be fixed (safe, no changes)
skylos agent remediate . --dry-run

# Fix up to 5 critical/high issues, validate with tests
skylos agent remediate . --max-fixes 5 --severity high

# Full auto: fix, test, create PR
skylos agent remediate . --auto-pr --model gpt-4.1

# Use a custom test command
skylos agent remediate . --test-cmd "pytest test/ -x"

Safety guardrails:

• Dry run by default — use --dry-run to preview without touching files
• Fixes that break tests are automatically reverted
• Low-confidence fixes are skipped
• After applying a fix, Skylos re-scans to confirm the finding is actually gone
• --auto-pr always works on a new branch, never touches main
• --max-fixes prevents runaway changes (default 10)

Run Skylos in your CI pipeline with quality gates, GitHub annotations, and PR review comments.

# Auto-generate a GitHub Actions workflow
skylos cicd init

# Commit and activate
git add .github/workflows/skylos.yml && git push

That's it! Your next PR will have:

• Dead code detection
• Security scanning (SQLi, SSRF, secrets)
• Quality checks
• Inline PR comments with clickable file:line links
• Quality gate that fails builds on critical issues

Generates a ready-to-use GitHub Actions workflow.

skylos cicd init
skylos cicd init --triggers pull_request schedule
skylos cicd init --analysis security quality
skylos cicd init --python-version 3.11
skylos cicd init --llm --model gpt-4.1 
skylos cicd init --no-baseline
skylos cicd init -o .github/workflows/security.yml

Checks findings against your quality gate. Exits 0 (pass) or 1 (fail). Uses the same check_gate() as skylos . --gate.

skylos . --danger --quality --secrets --json > results.json 2>/dev/null
skylos cicd gate --input results.json
skylos cicd gate --input results.json --strict
skylos cicd gate --input results.json --summary

You can also use the main CLI directly:

skylos . --gate --summary

Configure thresholds in pyproject.toml:

[tool.skylos.gate]
fail_on_critical = true
max_critical = 0
max_high = 5
max_security = 10
max_quality = 10

Emits GitHub Actions annotations (::error, ::warning, ::notice). Uses the same _emit_github_annotations() as skylos . --github, with sorting and a 50-annotation cap.

skylos cicd annotate --input results.json
skylos cicd annotate --input results.json --severity high
skylos cicd annotate --input results.json --max 30

skylos . --github

Posts inline PR review comments and a summary via gh CLI. Only comments on lines changed in the PR.

skylos cicd review --input results.json
skylos cicd review --input results.json --pr 20
skylos cicd review --input results.json --summary-only
skylos cicd review --input results.json --max-comments 10
skylos cicd review --input results.json --diff-base origin/develop

In GitHub Actions, PR number and repo are auto-detected. Requires GH_TOKEN.

The gate and annotation logic lives in the core Skylos modules (gatekeeper.py and cli.py). The cicd commands are convenience wrappers that read from a JSON file and call the same functions:

• Run analysis once, consume many times — use --json > results.json 2>/dev/null then pass --input results.json to each subcommand.
• Baseline — run skylos baseline . to snapshot existing findings, then --baseline in CI to only flag new issues.
• Local testing — all commands work locally. gate and annotate print to stdout. review requires gh CLI.

Skylos exposes its analysis capabilities as an MCP (Model Context Protocol) server, allowing AI assistants like Claude Desktop to scan your codebase directly.

pip install skylos

Add to your Claude Desktop config (~/.config/claude/claude_desktop_config.json on Linux, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "skylos": {
      "command": "python",
      "args": ["-m", "skylos_mcp.server"]
    }
  }
}

Once configured, you can ask Claude:

• "Scan my project for security issues" → calls security_scan
• "Check code quality in src/" → calls quality_check
• "Find hardcoded secrets" → calls secrets_scan
• "Fix security issues in my project" → calls remediate

Baseline tracking lets you snapshot existing findings so CI only flags new issues introduced by a PR.

# Create baseline from current state
skylos baseline .

# Run analysis, only show findings NOT in the baseline
skylos . --danger --secrets --quality --baseline

# In CI: compare against baseline
skylos . --danger --baseline --gate

The baseline is stored in .skylos/baseline.json. Commit this file to your repo so CI can use it.

Real-time AI-powered code analysis directly in your editor.

1. Search "Skylos" in VS Code marketplace or run:

   ext install oha.skylos-vscode-extension

2. Make sure the CLI is installed:

   pip install skylos

3. (Optional) Add your API key for AI features in VS Code Settings → skylos.openaiApiKey or skylos.anthropicApiKey

• Real-time Analysis: Detects bugs as you type — no save required
• CodeLens Buttons: "Fix with AI" and "Dismiss" appear inline on error lines
• Streaming Fixes: See fix progress in real-time
• Smart Caching: Only re-analyzes functions that actually changed
• Multi-Provider: Choose between OpenAI and Anthropic

• MCP Server Support: Connect Skylos directly to Claude Desktop or any MCP client to chat with your codebase.
• CI/CD Agents: Autonomous bots that scan, fix, test, and open PRs automatically in your pipeline.
• Hybrid Verification: Eliminates false positives by verifying static findings with LLM reasoning.

• Static analysis runs 100% locally
• AI features send only changed function code to your configured provider
• We DO NOT collect any telemetry or data

Install from VS Code Marketplace

Block bad code before it merges. Configure thresholds, run locally, then automate in CI.

skylos init

Creates [tool.skylos] in your pyproject.toml:

[tool.skylos]
# Quality thresholds
complexity = 10
nesting = 3
max_args = 5
max_lines = 50
ignore = [] 
model = "gpt-4.1"

# Language overrides (optional)
[tool.skylos.languages.typescript]
complexity = 15
nesting = 4

# Gate policy
[tool.skylos.gate]
fail_on_critical = true
max_security = 0      # Zero tolerance
max_quality = 10      # Allow up to 10 warnings
strict = false

Run scans locally with exit codes:

skylos . --danger --gate

• Exit code 0 = passed
• Exit code 1 = failed

Use in any CI system:

name: Skylos Quality Gate

on:
  pull_request:
    branches: [main, master]

jobs:
  skylos:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install skylos
      - run: skylos . --danger --gate

Limitation: Anyone with repo access can delete or modify this workflow.

Server-controlled GitHub checks that cannot be bypassed by developers.

pip install skylos
skylos sync setup

1. Developer opens PR → GitHub App creates required check ("Queued")
2. Scan runs → Results upload to Skylos server
3. Server updates check → Pass ✅ or Fail ❌
4. Developer cannot merge until check passes

1. Dashboard -> Settings -> Install GitHub App
2. Select your repository
3. In GitHub repo settings:
   • Settings -> Branches -> Add rule -> main
   • Require status checks
   • Select "Skylos Quality Gate"

Repo Settings → Secrets → Actions → New secret

• Name: SKYLOS_TOKEN
• Value: (from Dashboard → Settings)

Skylos is designed to live everywhere your code does—from your IDE to your deployment pipeline.

Control how you consume the watchdog's findings.

By default, Skylos finds dead code. Enable additional scans with flags.

Tracks tainted data from user input to dangerous sinks.

skylos . --danger

Full list in DANGEROUS_CODE.md.

Detects hardcoded credentials.

skylos . --secrets

Providers: GitHub, GitLab, AWS, Stripe, Slack, Google, SendGrid, Twilio, private keys.

Flags functions that are hard to maintain.

skylos . --quality

To ignore a specific rule:

# pyproject.toml
[tool.skylos]
ignore = ["SKY-P403"]  # Allow nested loops

Tune thresholds and disable rules in pyproject.toml:

[tool.skylos]
# Adjust thresholds
complexity = 15        # Default: 10
nesting = 4            # Default: 3
max_args = 7           # Default: 5
max_lines = 80  

These flags work on the main skylos command for quick operations:

# LLM-powered audit (single file)
skylos . --audit

# Auto-fix with LLM
skylos . --fix

# Specify model
skylos . --audit --model claude-haiku-4-5-20251001

Note: For full project context and better results, use skylos agent analyze instead.

skylos . --danger --secrets --quality  # All static scans
skylos agent analyze . --fix           # Full AI-assisted cleanup

Static analysis can't see everything. Python's dynamic nature means patterns like getattr(), plugin registries, and string-based dispatch look like dead code—but they're not.

Smart tracing solves this. By running your tests with sys.settrace(), Skylos records every function that actually gets called.

# Run tests with call tracing, then analyze
skylos . --trace

# Trace data is saved to .skylos_trace
skylos .

# Static analysis will think this is dead because there's no direct call visible
def handle_login():
    return "Login handler"

# But it is actually called dynamically at runtime
action = request.args.get("action")  
func = getattr(module, f"handle_{action}")
func()  # here  

These patterns are invisible to static analysis but caught with --trace:

# 1. Dynamic dispatch
func = getattr(module, f"handle_{action}")
func()

# 2. Plugin or registry patterns  
PLUGINS = []
def register(f): 
  PLUGINS.append(f)
return f

@register
def my_plugin(): ...  

# 3. Visitor patterns
class MyVisitor(ast.NodeVisitor):
    def visit_FunctionDef(self, node): ...  # Called via getattr

# 4. String-based access
globals()["my_" + "func"]()
locals()[func_name]()

• Tracing only adds information. Low test coverage won't create false positives. It just means some dynamic patterns may still be flagged.
• Commit .skylos_trace to reuse trace data in CI without re-running tests.
• Tests don't need to pass. Tracing records what executes, regardless of pass/fail status.

Control what Skylos analyzes and what it ignores.

Silence specific findings with comments:

# Ignore dead code detection on this line
def internal_hook():  # pragma: no skylos
    pass

# this also works
def another():  # pragma: no cover
    pass

def yet_another():  # noqa
    pass

By default, Skylos excludes: __pycache__, .git, .pytest_cache, .mypy_cache, .tox, htmlcov, .coverage, build, dist, *.egg-info, venv, .venv

# See what's excluded by default
skylos --list-default-excludes

# Add more exclusions
skylos . --exclude-folder vendor --exclude-folder generated

# Force include an excluded folder
skylos . --include-folder venv

# Scan everything (no exclusions)
skylos . --no-default-excludes

Disable rules globally in pyproject.toml:

[tool.skylos]
ignore = [
    "SKY-P403",   # Allow nested loops
    "SKY-L003",   # Allow == None
    "SKY-S101",   # Allow hardcoded secrets (not recommended)
]

Suppress false positives permanently without inline comments cluttering your code.

# Add a pattern
skylos whitelist 'handle_*'

# Add with reason
skylos whitelist dark_logic --reason "Called via globals() in dispatcher"

# View current whitelist
skylos whitelist --show

# Single line
def dynamic_handler():  # skylos: ignore
    pass

# Also works
def another():  # noqa: skylos
    pass

# Block ignore
# skylos: ignore-start
def block_one():
    pass
def block_two():
    pass
# skylos: ignore-end

[tool.skylos.whitelist]
# Glob patterns
names = [
    "handle_*",
    "visit_*",
    "*Plugin",
]

# With reasons (shows in --show output)
[tool.skylos.whitelist.documented]
"dark_logic" = "Called via globals() string manipulation"
"BasePlugin" = "Discovered via __subclasses__()"

# Temporary (warns when expired)
[tool.skylos.whitelist.temporary]
"legacy_handler" = { reason = "Migration - JIRA-123", expires = "2026-03-01" }

# Per-path overrides
[tool.skylos.overrides."src/plugins/*"]
whitelist = ["*Plugin", "*Handler"]

Usage: skylos [OPTIONS] PATH

Arguments:
  PATH  Path to the Python project to analyze

Options:
  -h, --help                   Show this help message and exit
  --json                       Output raw JSON instead of formatted text  
  --tree                       Output results in tree format
  --table                      Rich table output instead of TUI
  --sarif                      Output SARIF format for GitHub/IDE integration
  -c, --confidence LEVEL       Confidence threshold 0-100 (default: 60)
  --comment-out                Comment out code instead of deleting
  -o, --output FILE            Write output to file instead of stdout
  -v, --verbose                Enable verbose output
  --version                    Checks version
  -i, --interactive            Interactively select items to remove
  --dry-run                    Show what would be removed without modifying files
  --exclude-folder FOLDER      Exclude a folder from analysis (can be used multiple times)
  --include-folder FOLDER      Force include a folder that would otherwise be excluded
  --no-default-excludes        Don't exclude default folders (__pycache__, .git, venv, etc.)
  --list-default-excludes      List the default excluded folders
  --secrets                    Scan for api keys/secrets
  --danger                     Scan for dangerous code
  --quality                    Code complexity and maintainability
  --trace                      Run tests with coverage first
  --audit                      LLM-powered logic review (legacy-will be deprecated)
  --fix                        LLM auto-repair (legacy-will be deprecated)
  --model MODEL                LLM model (default: gpt-4.1)
  --gate                       Fail on threshold breach (for CI)
  --force                      Bypass quality gate (emergency override)

Usage: skylos agent <command> [OPTIONS] PATH

Commands:
  analyze             Hybrid static + LLM analysis with project context
  security-audit      Deep LLM security audit
  fix                 Generate fix for specific issue
  review              Analyze only git-changed files

Options (all agent commands):
  --model MODEL                LLM model to use (default: gpt-4.1)
  --provider PROVIDER          Force provider: openai or anthropic
  --base-url URL               Custom endpoint for local LLMs
  --format FORMAT              Output: table, tree, json, sarif
  -o, --output FILE            Write output to file

Agent analyze options:
  --min-confidence LEVEL       Filter: high, medium, low
  --fix                        Generate fix proposals
  --apply                      Apply fixes to files
  --yes                        Auto-approve prompts

Agent fix options:
  --line, -l LINE              Line number of issue (required)
  --message, -m MSG            Description of issue (required)

Agent remediate options:
  --dry-run                    Show plan without applying fixes (safe preview)
  --max-fixes N                Max findings to fix per run (default: 10)
  --auto-pr                    Create branch, commit, push, and open PR
  --branch-prefix PREFIX       Git branch prefix (default: skylos/fix)
  --test-cmd CMD               Custom test command (default: auto-detect)
  --severity LEVEL             Min severity filter: critical, high, medium, low

Commands:
  skylos PATH                  Analyze a project (static analysis)
  skylos agent analyze PATH    Hybrid static + LLM analysis
  skylos agent security-audit PATH  Deep LLM audit with file selection
  skylos agent fix PATH        Fix specific issue
  skylos agent review          Review git-changed files only
  skylos agent remediate PATH  End-to-end scan, fix, test, and PR
  skylos baseline PATH         Snapshot current findings for CI baselining
  skylos cicd init             Generate GitHub Actions workflow
  skylos cicd gate             Check findings against quality gate
  skylos cicd annotate         Emit GitHub Actions annotations
  skylos cicd review           Post inline PR review comments
  skylos init                  Initialize pyproject.toml config
  skylos key                   Manage API keys (add/remove/list)
  skylos whitelist PATTERN     Add pattern to whitelist
  skylos whitelist --show      Display current whitelist
  skylos run                   Start web UI at localhost:5090

Whitelist Options:
  skylos whitelist PATTERN           Add glob pattern (e.g., 'handle_*')
  skylos whitelist NAME --reason X   Add with documentation
  skylos whitelist --show            Display all whitelist entries

Skylos displays confidence for each finding:

────────────────── Unused Functions ──────────────────
#   Name              Location        Conf
1   handle_secret     app.py:16       70%
2   totally_dead      app.py:50       90%

Higher confidence = more certain it's dead code.

The interactive mode lets you select specific functions and imports to remove:

1. Select items: Use arrow keys and spacebar to select/unselect
2. Confirm changes: Review selected items before applying
3. Auto-cleanup: Files are automatically updated

Q: Why doesn't Skylos find 100% of dead code? A: Python's dynamic features (getattr, globals, etc.) can't be perfectly analyzed statically. No tool can achieve 100% accuracy. If they say they can, they're lying.

Q: Are these benchmarks realistic? A: They test common scenarios but can't cover every edge case. Use them as a guide, not gospel.

Q: Why doesn't Skylos detect my unused Flask routes? A: Web framework routes are given low confidence (20) because they might be called by external HTTP requests. Use --confidence 20 to see them. We acknowledge there are current limitations to this approach so use it sparingly.

Q: What confidence level should I use? A: Start with 60 (default) for safe cleanup. Use 30 for framework applications. Use 20 for more comprehensive auditing.

Q: What does --trace do? A: It runs pytest (or unittest) with coverage tracking before analysis. Functions that actually executed are marked as used with 100% confidence, eliminating false positives from dynamic dispatch patterns.

Q: Do I need 100% test coverage for --trace to be useful? A: No. However, we STRONGLY encourage you to have tests. Any coverage helps. If you have 30% test coverage, that's 30% of your code verified. The other 70% still uses static analysis. Coverage only removes false positives, it never adds them.

Q: Why are fixtures in conftest.py showing up as unused? A: conftest.py is the standard place for shared fixtures. If a fixture is defined there but never referenced by any test, Skylos will report it as unused. This is normal and safe to review.

Q: My tests are failing. Can I still use --trace? A: Yes. Coverage tracks execution, not pass/fail. Even failing tests provide coverage data.

Q: What's the difference between skylos . --audit and skylos agent audit? A: skylos agent audit uses the new hybrid architecture with full project context (defs_map), enabling detection of hallucinations and cross-file issues. The --audit flag is legacy and lacks project context.

Q: Can I use local LLMs instead of OpenAI/Anthropic? A: Yes! Use --base-url to point to Ollama, LM Studio, or any OpenAI-compatible endpoint. No API key needed for localhost.

• Dynamic code: getattr(), globals(), runtime imports are hard to detect
• Frameworks: Django models, Flask, FastAPI routes may appear unused but aren't
• Test data: Limited scenarios, your mileage may vary
• False positives: Always manually review before deleting code
• Secrets PoC: May emit both a provider hit and a generic high-entropy hit for the same token. Supported file types: .py, .pyi, .pyw, .env, .yaml, .yml, .json, .toml, .ini, .cfg, .conf, .ts, .tsx, .js, .jsx, .go
• Quality limitations: The current --quality flag does not allow you to configure the cyclomatic complexity.
• Coverage requires execution: The --trace flag only helps if you have tests or can run your application. Pure static analysis is still available without it.
• LLM limitations: AI analysis requires API access (cloud) or local setup (Ollama). Results depend on model quality.

1. Permission Errors

   Error: Permission denied when removing function
   

   Check file permissions before running in interactive mode.

2. Missing Dependencies

   Interactive mode requires 'inquirer' package
   

   Install with: pip install skylos[interactive]

3. No API Key Found

   # For cloud providers
   export OPENAI_API_KEY="sk-..."
   export ANTHROPIC_API_KEY="sk-ant-..."
   
   # For local LLMs (no key needed)
   skylos agent analyze . --base-url http://localhost:11434/v1 --model codellama

4. Local LLM Connection Refused

   # Verify Ollama is running
   curl http://localhost:11434/v1/models
   
   # Check LM Studio
   curl http://localhost:1234/v1/models

We welcome contributions! Please read our Contributing Guidelines before submitting pull requests.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

• [x] Expand our test cases
• [x] Configuration file support
• [x] Git hooks integration
• [x] CI/CD integration examples
• [x] Deployment Gatekeeper
• [ ] Further optimization
• [ ] Add new rules
• [ ] Expanding on the dangerous.py list
• [x] Porting to uv
• [x] Small integration with typescript
• [x] Expanded TypeScript dead code detection (interfaces, enums, type aliases, 95% recall)
• [ ] Expand and improve on capabilities of Skylos in various other languages
• [x] Expand the providers for LLMs (OpenAI, Anthropic, Ollama, LM Studio, vLLM)
• [x] Expand the LLM portion for detecting dead/dangerous code (hybrid architecture)
• [x] Coverage integration for runtime verification
• [x] Implicit reference detection (f-string patterns, framework decorators)

More stuff coming soon!

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

• Author: oha
• Email: [email protected]
• GitHub: @duriantaco
• Discord: https://discord.gg/Ftn9t9tErf