io.github.duriantaco/skylos

Website | Docs | Repo Map | Quick Start | GitHub Action | VS Code Extension | Real-World Results | Benchmarks | Roadmap | Contributing

English | Deutsch | 简体中文 | Translations

What Is Skylos?

Skylos is an open-source static analysis CLI for Python, TypeScript, JavaScript, Java, Go, Kotlin, PHP, Rust, Dart, C#, Shell, and deployment config. It runs locally by default and can also be used as a CI/CD PR gate.

Use Skylos when you want one command to check a repo or pull request for:

• dead code and unused files
• security flaws and dangerous data flows
• secrets and dependency CVEs
• CI/CD and edge-device deployment misconfigurations
• quality regressions such as complexity, duplicate branches, and deep nesting
• common AI-generated code mistakes, including missing guards, fake helpers, invented package APIs, and impossible dependency versions
• LLM app risks such as unsafe tool use and missing output validation

Start In 60 Seconds

pip install skylos
skylos .

The default scan focuses on dead code. Add security, secrets, quality, and dependency checks with -a:

skylos . -a

Verify a changed file or range before an agent hands it to review:

skylos verify . --file src/app.py --range 40:75 --project-context

Create a project config with thresholds, ignores, template hooks, and vibe dictionary extensions:

skylos init

Create a starter local rule pack:

skylos rules init
skylos rules validate .skylos/rules/local.yml
skylos rules list --json
skylos rules list cross --json
skylos rules list --packs --json
skylos cache stats

Generate a GitHub Actions PR gate:

skylos cicd init
git add .github/workflows/skylos.yml
git commit -m "Add Skylos CI gate"
git push

Need more commands? Read the CLI Reference.

Common Workflows

What Skylos Catches

See the full Rules Reference.

How Skylos Fits

Skylos is not a replacement for every specialized scanner. It is a local-first repo and PR checker that puts several common review checks behind one CLI.

• Framework-aware dead code detection: FastAPI, Django, Flask, pytest, SQLAlchemy, Next.js, React, package entrypoints, and common plugin patterns.
• PR-focused output: diff scanning, CI thresholds, GitHub annotations, and baselines for existing findings.
• Local-first operation: core static analysis does not require cloud upload or LLM calls.
• AI-assisted change review: checks for removed validation, auth, logging, CSRF, rate limiting, timeouts, real-package API hallucinations, and other guardrails in generated or edited code.
• Agent-loop verification: skylos verify and MCP verify_change return versioned JSON for only AI-code trust findings, so coding agents can self-correct before a human sees the change.
• Verification-backed remediation: security fixes are checked by re-running analysis, and supported findings can include targeted regression-test proof metadata.
• Project-specific rules: add local YAML rules and extend prompt, credential, sensitive-file, and timeout dictionaries from config.
• One command surface: dead code, security, secrets, dependency, quality, technical debt, agent review, and AI defense commands share the same CLI.

Agent Harness Artifacts

skylos agent verify . records replayable verification artifacts under .skylos/runs/<run-id> and prints the run directory in table output. JSON output includes the same harness summary under the harness key.

Use skylos agent replay .skylos/runs/<run-id> to validate and inspect a saved run without making LLM calls. Add --format json when another agent or CI job needs machine-readable status. A valid replay exits 0; an invalid or corrupt artifact set exits 1 with issue codes. Replay output includes schema_version so CI and agents can detect artifact-contract changes.

Each run directory contains:

• events.jsonl: chronological run, phase, and tool-call events.
• state.json: full observable state, including phases, tool calls, decisions, and budget usage.
• summary.json: compact status, counts, budget, and artifact paths.

The current harness state is observable and replay-validated. It is not yet a resume mechanism for continuing interrupted verification runs.

Install Options

# Core static analysis
pip install skylos

# LLM-powered agent workflows
pip install "skylos[llm]"

# All published optional extras
pip install "skylos[all]"

Container image:

docker pull ghcr.io/duriantaco/skylos:latest
docker run --rm -v "$PWD":/work -w /work ghcr.io/duriantaco/skylos:latest . --json --no-provenance

See Installation for source installs, container usage, and optional dependencies.

Configure Templates And Vibe Checks

Run skylos init to add these sections to pyproject.toml:

[tool.skylos]
exclude = ["node_modules", "dist"]

[tool.skylos.templates]
# security = ".skylos/templates/security.md"
# quality = ".skylos/templates/quality.md"
# security_audit = ".skylos/templates/security_audit.md"
# review = ".skylos/templates/review.md"

[tool.skylos.vibe]
extra_phantom_names = ["verify_enterprise_auth"]
extra_phantom_decorators = ["tenant_admin_required"]
extra_credential_names = ["tenant_signing_secret"]
extra_network_timeout_calls = ["vendor_sdk.fetch"]

[tool.skylos.dead_code]
entrypoints = []

[[tool.skylos.dead_code.entrypoints]]
type = "method"
name = ["create", "pre_hook", "post_hook"]
parent = { name = "Main", base_classes = ["Application"] }
path = "src/**"
reason = "project framework lifecycle hook"

[tool.skylos.contribution]
collect_local_signals = false
contribute_public_corpus = false
structural_signatures_only = true
include_source = false

Template files extend Skylos' built-in prompts; they do not replace the JSON-only output contract or untrusted-code safety rules. Vibe dictionary extensions let teams teach Skylos about local fake-auth helpers, project credential names, sensitive files, and network calls that must set timeouts. Dead-code entrypoints let teams mark proprietary framework classes, lifecycle methods, and decorator-registered functions as live using precise rules for type, name, path, decorators, base classes, and parent classes. Rules must include a symbol selector such as name, decorators, base_classes, or parent; path and module only narrow the match. Contribution signals are off by default; when enabled, Skylos records local structural accept/dismiss/learn events under .skylos/contribution/ without raw source.

By default Skylos discovers [tool.skylos] in pyproject.toml by walking up from the scan path. To use a dedicated TOML config, pass --config-file PATH or set SKYLOS_CONFIG_FILE; standalone files may use either [tool.skylos] or top-level [skylos]. Synced Skylos Cloud policy keeps its protected precedence over repository-controlled config. The top-level [tool.skylos].exclude list applies to the main scan and commands such as skylos debt and skylos clean; pass --exclude for command-local additions or --include-folder to override an excluded folder.

Language Support

See Rules Reference for rule families and scanner scope.

Config And Deployment Support

Benchmark Snapshot

Skylos has checked-in regression benchmarks for dead code, security, quality, and agent review. These are strict regression gates, not broad proof that any tool is universally state of the art.

Frozen golden-v0.2 highlights:

For methodology, commands, competitor rows, and caveats, see BENCHMARK.md.

Project Evidence

Skylos-assisted dead-code cleanup PRs have been merged in Black, NetworkX, Optuna, mitmproxy, pypdf, beets, and Flagsmith. These are accepted cleanup PRs, not project endorsements. See Real-World Results.

<a id="star-authenticity-audit"></a>

A local Astronomer scan on April 26, 2026 computed 420 stargazers and returned overall trust: A. StarGuard also reported low fake-star risk.

Integrations

Generate a GitHub Actions workflow from the CLI:

skylos cicd init --upload
skylos cicd init --upload --scan-path apps/api

The generated upload workflow uses GitHub OIDC, sends PR head commit/branch metadata, and supports monorepo subprojects through --scan-path.

Documentation Map

Common Questions

Does Skylos replace Bandit, Semgrep, CodeQL, or Vulture?

No. Skylos can run alongside them. It focuses on framework-aware dead-code signal, PR gating, AI-era regression checks, and a combined workflow across dead code, security, secrets, and quality.

Does Skylos require an LLM?

No. Core static analysis runs locally without API keys. LLM features are optional through skylos[llm] and agent commands.

Can I use it only on changed code?

Yes. Use skylos . -a --diff origin/main locally or configure CI gates to focus on new findings.

How should I handle intentional dynamic code?

Use baselines, whitelists, inline suppressions, or runtime tracing. See the configuration docs and smart tracing docs.

Contributing And Support

• Report security issues through SECURITY.md.
• Open bugs and false-positive reports with minimal repros.
• Check ROADMAP.md for useful contribution areas.
• Read CONTRIBUTING.md before sending a pull request.
• See QUALITY.md for project quality and gate expectations.
• Join the Discord for community support.

License

Skylos is licensed under the Apache License 2.0.