Skylos

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

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

Python has the deepest coverage. TypeScript/JavaScript and Java also get dead-code, security and quality checks; PHP, Rust and Dart get dead-code and security checks. Go dead-code and security checks need the separately built skylos-go engine, which the container image and GitHub Action include but the PyPI package does not. C# support is partial, Kotlin is dead code only, C++ is limited to unused file-local functions, and Shell is security only. Skylos also checks CI/CD and deployment config. See Language Support.

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.

Question	Command	Input checked
What problems are in this source tree?	skylos PATH	Source files and project configuration; dead code by default, every main source analyzer with -a
Did the agent really finish this branch?	skylos done --base main	The branch's changes since its merge base with main: Skylos runs your tests (pytest automatically; other runners need test_command in [tool.skylos.done]) and compares the tests, test settings and CI steps with the base; writes a receipt to .skylos/receipts/
Does this code contain AI-code mistakes?	skylos verify [PATH]	AI-defect checks over the selected file or tree, plus a separate Git HEAD behavior comparison for supported Python working changes
Should a model review static dead-code findings?	skylos agent verify [PATH]	LLM by default; optional Jev-only or Jev-plus-LLM review
What does the combined repo suite report?	skylos suite [DIRECTORY]	Static analysis, technical debt, AI defense, and provenance; local findings are report-only by default
Does an agent implementation have deployment guardrails?	skylos defend [DIRECTORY]	Recognized Python and TypeScript/JavaScript LLM integrations; gating requires a threshold flag or policy
Which Python dead code can Skylos remove?	skylos clean [PATH] --dry-run	Python import/function cleanup candidates; --dry-run never writes
Will this exact local GPU build fit the machines we ship to?	skylos preflight [ARTIFACT]	A local built file or directory and .skylos/gpu-targets.yml; an OCI reference is identity-only and returns UNKNOWN in the CLI
What vulnerabilities are in this container image?	skylos image scan IMAGE@sha256:<digest> --platform os/arch	A remote registry image scanned by a separately installed Trivy; --fail-on turns findings into a gate

Run skylos --help for this chooser, skylos <command> --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 change cannot loosen its own gate.

Start In 60 Seconds

pip install skylos
skylos .

Before 4.47.2, pip install skylos also installs a Dart parser that builds from source and needs a C compiler. From 4.47.2, Dart support is the optional skylos[dart] extra. If the install fails for lack of a compiler, use the container image.

Optional Rust acceleration can be built from source. The standard installation uses Python fallbacks. See the build guide for accelerated operations and possible differences in findings.

The default scan focuses on dead code. Run every main source analyzer, including security, secrets, quality, dependency, and AI-defect checks, with -a:

skylos . -a

Check whether a branch, often an AI agent's, is really finished:

skylos done --base main

skylos done compares the branch with its merge base on main and runs your tests. It flags deleted or skipped tests, loosened test settings and CI test steps, silenced lint or type checks, and code that special-cases the tests, then writes a receipt to .skylos/receipts/. It runs pytest automatically; other test runners need one test_command line in [tool.skylos.done]. See the done gate guide for every check and its limits.

Run only evidence-backed AI defect checks with:

skylos . --ai-defects

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

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

For a directory such as ., the AI-defect scan covers the selected tree. The separate behavior result models supported Python working-tree changes against Git HEAD; it is not the scope selector for the AI-defect scan. Dependency hallucination checks are enabled for path targets and can query package registries; use --no-dependency-hallucinations to disable those lookups. High/critical security findings (category: "security") and hard-coded secrets (category: "secret", value redacted) in the selected file/range also fail verification; use --no-security for the AI-code-only verdict. Interactive terminals get a human report. Redirected stdout and -o produce the versioned JSON result.

skylos verify schema version 2 returns pass, fail, or incomplete. incomplete means a requested proof could not be established, such as a missing local TS/JS import, computed namespace member, unsupported language-local API check, or parser surface that Skylos could not prove; it exits 2 unless --no-fail is set. The coverage object lists detected languages, expected checks, language support, missing checks, completed/skipped checks, checked references, and deterministic skip reasons. Declared third-party dependencies and recognized Node built-ins are outside the local TS/JS API proof; their references are counted in out_of_scope_references and do not make a clean verification incomplete. Unknown bare imports still require review.

Deterministic local/workspace API verification currently covers Python, TypeScript/JavaScript, Go, and Java without executing target code. PHP, Rust, Dart, C#, Kotlin, and Shell retain their existing static-analysis coverage, but their local API proof is reported as unsupported and therefore incomplete. See AI Code Verification Coverage.

Create a local AI hallucination contract for repo-specific generated-code truth. skylos verify auto-discovers .skylos/ai-contract.yml:

skylos contract init
skylos contract inspect
skylos verify .

Test a running agent against deterministic response and tool-use scenarios:

skylos agent init
skylos agent test --allow-contract-endpoint

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

Gate pull requests with GitHub Actions. No Skylos account or API key is needed:

git checkout -b add-skylos-gate
skylos cicd init --no-upload
git add .github/workflows/skylos.yml
git commit -m "Add Skylos pull request gate"
git push -u origin add-skylos-gate
gh pr create --fill

The generated workflow reviews changed lines on pull requests and adds a skylos done job when it finds your tests. Without --no-upload, it also adds a Skylos Cloud upload job for pushes to your default branch, which fails until the Skylos GitHub App is installed on the repository. Your first Skylos-gated pull request walks through it in about 8 minutes, including making the checks required.

Need more commands? Read the CLI Reference.

Check Every Agent Edit (Claude Code, Codex, Cursor)

Install local hooks so the agent is checked while it works, not after:

skylos agent install-hooks            # Claude Code (.claude/settings.json)
skylos agent install-hooks --codex    # Codex (.codex/hooks.json)
skylos agent install-hooks --cursor   # Cursor (.cursor/hooks.json)

• After each edit: verifies only the changed lines (security, secrets, AI-code mistakes) and tells the agent what to fix.
• Before a file read: blocks files that contain hard-coded secrets.
• Before a package install: blocks hallucinated or typosquatted packages.
• At stop: blocks "done" while issues the agent added are still open.

Hooks fail open, but never silently: if Skylos errors, the agent and you are told the action was allowed without a check, and stop reports how many went unchecked. They log to .skylos/hook.log and merge with your existing hooks. --uninstall removes only the Skylos entries. See Agent-loop hooks for the contract, latency, and limits.

In Cursor, findings arrive at stop rather than after each edit. The hooks are not a sandbox: they check edits, file reads and package installs, not every command. See what they don't do.

Common Workflows

Goal	Command	What You Get	More Detail
First dead-code scan	skylos .	Finds unused functions, classes, imports, files, and framework entrypoint mistakes	Dead code docs
Deterministic cleanup preview	skylos clean . --dry-run --types import,function --confidence 80	Shows planned Python import/function removals without writing; add --apply to edit files	Dead code docs
Security and quality audit	skylos . -a	Adds dangerous flow, secrets, dependency, config, quality, and AI-defect checks	Security docs
Combined repo report	skylos suite .	Reports static findings, technical debt, AI defense, and provenance; SCA can query OSV, and findings alone exit 0	CLI Reference
Optional Python linting	pip install "skylos[lint]" && skylos lint .	Runs Ruff with its native configuration, output, fixes, and exit codes through the Skylos CLI	Python linting
Agent branch done check	skylos done --base origin/main	Runs your tests and flags deleted, skipped or weakened tests, loosened test settings and CI test steps, silenced checks, and test-only special cases; writes a receipt	Done gate
PR gate	skylos cicd init --no-upload	Generates a GitHub Actions workflow that gates pull requests and runs skylos done when your tests can run. Drop --no-upload to also upload default-branch scans to Skylos Cloud with GitHub OIDC; that job fails until the Skylos GitHub App is installed on the repository	First gated PR
GitLab merge request report	skylos . --format gitlab -o gl-code-quality-report.json	Exports a native Code Quality report for GitLab CI artifacts	GitLab Code Quality
Offline dependency SBOM	skylos sbom . -o sbom.cdx.json	Lists supported recorded dependencies as CycloneDX 1.6 JSON without network requests	Dependency scanning
SPDX SBOM + license policy	skylos sbom . --format spdx-json / license_deny = ["GPL-*"]	SPDX 2.3 JSON with declared licenses; SKY-SCA-LIC001 flags denied licenses in -a scans	License compliance
Signed verdict deploy gate	skylos verify-verdict verdict.json --commit "$SHA" --repository github.com/org/repo --require-repository-verified --require-trusted-upload --max-age 7d --require-passed	Verifies a Skylos Cloud check verdict offline (Ed25519 DSSE, in-toto/SLSA) and fails unless it is a recent policy pass for that commit and repository; needs skylos[verdict]	Verify a signed verdict
Readable terminal report	skylos . --format pretty	Groups findings by file with severity badges, snippets, and copyable file:line locations	CLI output modes
Single-rule review	skylos . --select SKY-L012 --format concise	Enables the matching analyzer family and reports only that exact rule with its full message	CLI output modes
Selectable terminal triage	skylos . --tui	Opens a keyboard-driven category list, finding list, and detail pane	CLI output modes
IDE/test-script output	skylos --format concise src/test.py	Prints untruncated file:line RULE_ID message findings and exits non-zero when findings exist	CLI Reference
In-loop AI-code verification	skylos verify . --file src/app.py --range 40:75	Reports a narrow set of hallucinated helpers, unfinished code, stale references, disabled controls, and API/dependency hallucinations; JSON is used for redirected or -o output	AI features
AI hallucination contracts	skylos contract init && skylos verify .	Auto-discovers .skylos/ai-contract.yml and verifies generated code against repo-specific symbols, dependencies, APIs, route guards, and test requirements	AI Hallucination Contracts
Changed-lines review	skylos . -a --diff origin/main	Keeps findings focused on active work instead of legacy debt. In this release --diff can drop removed-control findings (SKY-L021, such as a deleted auth decorator); run skylos . -a --diff-base origin/main without --diff to see them	Quality gate docs
Incumbent scanner comparison	skylos compare . --against incumbent.sarif	Runs Skylos beside the current scanner and produces a revision-aware scorecard: active overlap, raw unique findings by category, and eligible findings inside evidence-backed unused symbols, without replacing the current gate	Scanner comparison
Runtime-assisted dead-code check	skylos . --trace	Uses runtime traces to reduce dynamic-code false positives	Smart tracing
Local rule pack	skylos rules init	Scaffolds YAML rules for project-specific security and quality checks	Custom rules
Security agent quick scan	skylos agent security-quick .	One-shot LLM security audit; compatibility alias for skylos agent scan . --security	AI features
Security agent deep scan	skylos agent security-deep .	Three-stage security workflow with threat-model context, static threat traces, discovery/validation, and remediation handoff	AI features
AI-assisted review	skylos agent scan .	Static analysis plus optional LLM review and fix suggestions	AI features
Agent harness replay	skylos agent replay .skylos/runs/<run-id>	Validates and summarizes saved agent verification phases, tool calls, decisions, and budgets	Agent harness artifacts
Runtime agent behavior test	skylos agent init && skylos agent test --allow-contract-endpoint	Checks final responses, tool selection, explicit refusals, and source IDs against a versioned contract	Agent Behavior Testing
Verification-backed remediation	skylos agent remediate .	Scans and fixes supported findings, then re-scans them and records proof-test metadata when available	AI features
Agent-loop hooks	skylos agent install-hooks [--codex|--cursor]	Verifies every agent edit, blocks secret reads and hallucinated package installs, and holds "done" while new issues are open	Agent-loop hooks
Project standards for agents	skylos agent install-standards --enforce SKY-L002	Gives Codex, Claude Code, and Cursor a project skill and selects measurable quality rules for hook and CI checks	Project standards
MCP agent verification	verify_change MCP tool	Lets Claude, Cursor, and other MCP clients verify an edited file/range with the same schema as skylos verify. Requires a free Skylos API key (SKYLOS_API_KEY). skylos verify and agent-loop hooks need no key	MCP server
LLM integration inventory	skylos discover .	Maps recognized LLM calls, agent tools, prompt sites, and input sources in Python and TypeScript/JavaScript	Agent verification
Pre-deployment agent verification	skylos defend . --format md -o evidence.md	Verifies agent guardrails, scores OWASP LLM/Agentic coverage, and emits an attested evidence report	Agent verification
Agent verification CI gate	skylos defend . --fail-on critical	Blocks deploys with unguarded LLM integrations; SARIF for code scanning via --format sarif	Agent verification
MCP agent pre-flight	verify_agent MCP tool	Lets coding agents statically verify the agents they build — scores, failed checks, attestation digest. Requires a free Skylos API key (SKYLOS_API_KEY). skylos defend needs no key	MCP server
Technical debt triage	skylos debt .	Ranks hotspots and debt trends	Technical debt

What Skylos Catches