Skylos

Skylos Code checks that show their work.

What Is Skylos?

Skylos is an open-source (Apache-2.0) CLI and pull-request gate for Python projects that runs without an account. skylos . finds dead code: unused functions, classes, imports and empty files. Add -a to check security bugs, hard-coded secrets, vulnerable dependencies, code quality and AI-code mistakes. Findings include source locations and supporting analysis; skylos done checks whether a branch, often a coding agent's, is ready to merge.

It is built for:

• Teams merging pull requests from AI coding agents such as Claude Code, Codex and Cursor. skylos done runs your tests and flags deleted or skipped tests, loosened CI test steps, silenced lint or type checks, and test-only special cases.
• Python maintainers who want framework-aware dead-code, security and secrets checks. Python has the deepest coverage; other languages are listed under Language Support.

pip install skylos

skylos . # find dead code skylos . -a # add security, secrets, quality, dependency and AI-code checks skylos done --base main # is this branch finished? runs your tests, compares with main

Working with a coding agent? Two commands:

skylos setup   # once per repo: connects Claude Code and Codex, writes the PR check, maps the code

skylos open # every day: diagram of your code, what changed in plain English, every check run

Your agent runs the checks itself. The tutorial walks through a real session: the agent describes the code, makes a change, gets blocked and fixes it from Skylos's fix brief.

Proof, including the misses: 10 Skylos-assisted dead-code cleanup PRs have been merged into the default branch in 9 open-source projects, including Black, NetworkX, Optuna, mitmproxy and pypdf. Real-World Results lists the 26 cleanup and quality-fix PRs in this ledger, including the ones that were closed, reverted or never reached the default branch. These are accepted cleanup PRs, not endorsements.

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

English | Deutsch | 简体中文 | Translations

Skylos runs locally by default and can also gate pull requests in CI. Use it 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

Skylos supports 12 languages: Python, TypeScript/JavaScript, Java, Go, PHP, Rust, Ruby, Dart, C#, C++, Kotlin and Shell. Python has the deepest coverage. TypeScript/JavaScript and Java also get dead-code, security and quality checks; PHP and Dart get dead-code and security checks (PHP security follows request data within a function or file into command and code execution, file inclusion, HTML output, SQL, SSRF, deserialization and file paths; Dart security covers command injection, path traversal and SSRF); Rust gets command-injection and path-traversal checks and experimental dead code (hidden below the default confidence threshold; --confidence 40 lists it). Go dead-code and security checks need the native skylos-go engine: from 4.50 the PyPI wheels for Linux, macOS and Windows (x86_64 and arm64) include it, the container image includes it and the GitHub Action builds it. On other platforms skylos doctor prints the command that builds it from source, and SKYLOS_GO_BIN points Skylos at a separately built engine. C# support is partial, Kotlin dead code covers only private declarations and imports (Kotlin security covers Spring, Ktor, servlet and Android WebView basics), C++ is limited to unused file-local functions, and Shell gets security checks only. Ruby adds bounded private-method liveness, literal Rails controller callbacks and explicit Kernel command checks. Skylos also checks CI/CD, deployment config and two Terraform/AWS declaration policies. See Language Support.

Read The Results

Remember Risk, Maintainability, Dead code, Gate:

Finding Type is separate from severity: Defect is a concrete correctness pattern, Review needs context, and Advice concerns maintainability or tooling. A Review finding can still be critical. Advice stays visible in rule groups; --expand-advice shows every location and JSON keeps complete records. Grouping cannot improve the assessment or bypass a gate.

Security findings show recorded source-to-sink evidence when available, with partial static analysis labeled. Dependency coverage names unresolved versions and the supported inputs needed to check them. Neither view claims runtime exploitability or a complete installed environment; JSON keeps the full evidence.

For uv.lock, Cargo.lock, composer.lock, Gemfile.lock and pubspec.lock, valid Git, URL, path and private-registry dependencies are shown as not checked. Skylos still queries supported public packages; the coverage gap alone does not cause exit 2. It cannot establish a clean dependency assessment. See uv source coverage.

New source scans replace the blended A–F grade with these readouts. Disabled checks are not assessed; failed checks are incomplete. Maintainability percentages use only the relevant units actually measured, with no guessed denominators or uncalibrated grades. The independent debt and defend scores keep their meanings. See the output guide.

Choose the Right Command

Each command answers a different question. The source scan requires PATH. Bracketed paths on verify, suite, defend, and clean default to the current directory. suite and defend require a directory; verify and clean also accept a file.

Run skylos --help for this chooser, skylos --help for one command, and skylos commands for the command-family map.

The report commands have different gate and network behavior:

• image scan requires Trivy on trusted PATH and uses Trivy's remote image source, so registry network access and any required registry credentials must already be available. Without --fail-on, a completed scan exits 0 even when it reports vulnerabilities.
• suite runs in the local process and does not upload unless --upload is set, but its dependency scan can query OSV. Findings are report-only: the command exits 0 regardless of their count. Operational and output failures are nonzero; --upload can also fail for an upload error or Cloud quality gate.
• defend reports guardrail findings by default. It becomes a gate with --fail-on, --min-score, or gate settings in an explicit policy.
• clean without --dry-run or --apply is interactive and can write after the final confirmation. Its current codemods support Python imports and functions. An apply pass still exits 0 if an individual edit prints a failure, so review the completion output.
• done exits 0 on pass, 1 when a blocking check fails or does not finish, and 2 when Skylos could not run (for example, the base is not fetched). It reads its settings from the base commit, so a