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 skylosskylos .                  # find dead codeskylos . -a               # add security, secrets, quality, dependency and AI-code checksskylos 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.

[MCP Toplist] [License: Apache 2.0] [codecov] [PyPI - Python Version] [PyPI version] [VS Code Marketplace]

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 11 languages: Python, TypeScript/JavaScript, Java, Go, PHP, Rust, 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 (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 (there are no Kotlin security rules), C++ is limited to unused file-local functions, and Shell gets security checks only. Skylos also checks CI/CD and deployment config. 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, valid Git, URL, path and private-index 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 <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 skylosskylos .            # find problems; your code and findings stay on your machineskylos cloud        # optional: track results per branch on Skylos Cloudskylos cicd init    # add a Skylos check to every pull request

That is the whole path. When skylos . finds issues, it ends by naming the next command.

skylos cloud runs every check, shows the findings, uploads them and prints this branch's quality gate with one link to it:

✗ Quality gate on feat/login: FAILED (was PASSED on 24 Oct 15:38 UTC, 1ba9895) · 1 critical security issue  Open: https://skylos.dev/dashboard/projects/<project>?branch=feat%2Flogin  Next: fix the issues behind the failed gate, then run skylos cloud again.

The first run opens your browser to log in and pick the project for this repo. It sends findings with file paths and code snippets of up to 7 lines (none for secrets), the branch, the commit, the git author email of each flagged line, and a map of your functions and classes (names, files, lines, sizes, which calls which). Not your repository. It exits 0 even when the Skylos Cloud gate fails; add --gate to exit 1 (use that in CI). You never need a key to pass the gate: fix the issues that fail it. See Skylos Cloud for the other Cloud commands.

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, advises on code the branch left without callers (including in files it did not touch), then writes a receipt to .skylos/receipts/. When tests fail, it reruns them on the merge base and labels each failure "introduced" or "already failing"; every failure still blocks by default. 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, C++, 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 initskylos contract inspectskylos verify .

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

skylos agent initskylos agent test --allow-contract-endpoint

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

skylos init

Create a starter local rule pack:

skylos rules initskylos rules validate .skylos/rules/local.ymlskylos rules list --jsonskylos rules list cross --jsonskylos rules list --packs --jsonskylos cache stats

Scans with --quality or -a apply every .yml/.yaml pack in a .skylos/rules/ folder from the scanned file up to the repository root (the nearest pack wins for a rule ID). In PR CI, as with [tool.skylos], the packs come from the base branch, so a pull request cannot drop or edit the rules its own gate runs. A pack that cannot be read is skipped with a warning naming it.

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

git checkout -b add-skylos-gateskylos cicd init --no-uploadgit add .github/workflows/skylos.ymlgit commit -m "Add Skylos pull request gate"git push -u origin add-skylos-gategh pr create --fill

The generated workflow reviews changed lines on pull requests and adds a skylos done job when it finds your tests. With --upload (the default once this machine is logged in with skylos login), it also uploads to Skylos Cloud with GitHub OIDC: pushes to your default branch, and pull requests to it, which Cloud then lists with their check and comment. A pull request is scanned as untrusted data in a job with no credentials and uploaded by a job that never checks out its files. Uploads fail 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.

On GitLab CI, Jenkins, Bitbucket Pipelines, Azure Pipelines or CircleCI, the same skylos cicd init sets up a pull request gate for that CI instead; see Skylos on any CI.

The gate (skylos . --gate, skylos cicd gate, and the generated workflow) fails on any critical security issue, any secret, and any critical AI-code issue, such as an import of a package that does not exist on PyPI (SKY-D222) or a call to a function that is never defined or imported (SKY-L012). Other findings fail it only above count limits. Change the limits under [tool.skylos.gate] in pyproject.toml:

[tool.skylos.gate]max_high = 5          # high-severity security issues allowedmax_quality = 10      # quality issues allowedmax_ai_defects = 10   # AI-code issues allowed (defaults to max_quality)# AI-code issues at these severities fail the gate whatever max_ai_defects# allows. Add "HIGH" to block more; [] turns the rule off.block_ai_defect_severities = ["CRITICAL"]

max_ai_defects and block_ai_defect_severities are separate checks; the gate fails if either one fails. In a pull request, skylos cicd gate --diff-base reads this policy from the base branch, so a pull request cannot turn the rule off for itself. A gate policy synced from Skylos Cloud replaces the repository's [tool.skylos.gate] section, and the gate then checks what the Cloud gate checks: its mode (zero new issues, limits per category, per severity, or both) and its limits, which the verdict line prints. Skylos Cloud counts only new issues, so check a branch with skylos . -a --gate --diff origin/main; a full scan prints a line saying so. The .skylos/config.yaml that skylos sync pull writes applies to --diff gates while it is not committed; a copy committed only on the branch does not. A Cloud gate that is turned off leaves the built-in limits. max_critical, max_secrets and fail_on_critical = false cannot loosen the critical-issue and secret rule; a gate run prints a warning when they try, and for a rules entry that is not a rule ID.

Every gate run ends with one verdict line and the reasons behind it: Quality Gate: PASSED, Quality Gate: FAILED (exit 1), or Quality Gate: INCOMPLETE — could not decide (exit 2) when required analysis did not finish, for example a lockfile the dependency scan could not resolve. Each reason names the check that stopped, how many files or dependencies it missed, and what to change. A file that does not parse is a coverage warning under the verdict, not a reason to stop: the limits are evaluated on everything else (set require_complete = true under [tool.skylos.gate.coverage] to fail instead). --format json carries the same verdict in a top-level gate object; concise, LLM, GitHub, and GitLab output print it on stderr. See Exit Codes And Incomplete Analysis.

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 or one-shot run (pip, uvx, npx, pnpm dlx, bunx, go run pkg@v, ...): blocks hallucinated or typosquatted packages, and asks before installs it cannot verify (git and URL sources, unknown registries, failed lookups).
• Before a git command: blocks --no-verify, HUSKY=0 and other ways around the repository's git hooks.
• 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

What Skylos Catches

See the full Rules Reference.

Dependency licenses

skylos sbom . writes declared dependency licenses into CycloneDX, and skylos sbom . --format spdx-json writes an SPDX 2.3 SBOM. Licenses come from lockfiles and installed package metadata, offline. Unknown or ambiguous values (such as BSD) stay NOASSERTION rather than being guessed. --license-lookup opts in to a deps.dev query. To block licenses in -a scans, set a policy:

[tool.skylos]license_deny = ["GPL-*", "AGPL-3.0-only"]license_severity = "HIGH"

Violations are reported as SKY-SCA-LIC001. See License compliance.

Give Coding Agents Project Standards

Create .skylos/standards.md with the guidance you want agents to follow:

# Coding standards
- Keep functions focused and handle exceptions explicitly.- Add a focused test when changing behavior.

Then install the project skill and choose any Skylos quality rules to enforce:

skylos agent install-standards --enforce SKY-L002skylos agent install-hooks --codex   # use --cursor for Cursor, or omit for Claude Codeskylos agent check-standards .       # run this project-wide check in CI

The installer writes SKILL.md files for Codex, Cursor, and Claude Code. Agent skills provide guidance; the hooks and project-wide check enforce the selected built-in quality rules. See project standards for the generated files, rule selection, and coverage limits.

Verify AI Agents Before They Ship

Runtime guardrails are the WAF; Skylos is the SAST. skylos discover scans Python and TypeScript/JavaScript for recognized LLM integrations (provider SDKs, agent frameworks including the OpenAI Agents SDK, Claude Agent SDK, and Google ADK, MCP servers and their tools, direct HTTP calls to LLM APIs or OpenAI-compatible gateways, plus agent tools, prompt sites, and input sources). skylos defend checks the guardrails around those detected integrations deterministically, in the local process, with no model in the loop. It emits evidence by default and becomes a CI gate only when a threshold flag or policy supplies gate criteria.

skylos discover .                               # inventory LLM integrations and agent toolsskylos defend .                                 # score guardrails (13 weighted checks)skylos defend . --format md -o evidence.md      # auditor evidence report + attestationskylos defend . --format sarif -o defend.sarif  # GitHub code scanning uploadskylos defend . --fail-on critical              # CI gate: exit 1 on critical gapsskylos defend . --owasp-framework agentic       # report against OWASP Agentic ASI Top 10

These commands do not inspect integrations in other languages. If discovery finds no supported integration, defend returns an empty inventory; do not treat the resulting score by itself as proof that an unsupported or unrecognized agent implementation has guardrails.

Per integration it verifies: dangerous output sinks (eval/exec/subprocess), agent tool scope and typed schemas, prompt-injection exposure (delimiters, untrusted input paths, RAG context isolation), output validation, PII filtering, and model pinning — plus ops checks (logging, cost controls, rate limiting) scored separately so they never inflate the security score.

• OWASP mapping: LLM Top 10 (2024/2025) and Agentic ASI Top 10 (2026).
• Evidence report (--format md): integration inventory, per-check results, OWASP coverage, regulatory framework evidence (EU AI Act, NIST AI RMF, ISO/IEC 42001 — "evidence toward" mappings, never compliance claims), and a remediation appendix.
• Attestation: JSON/md/SARIF reports carry a reproducible SHA-256 digest over file contents, policy, plugin set, integration inventory, scores, and full check evidence — re-run on the same tree with the same flags and Skylos version, and the digest must match.
• CI-native: skylos cicd init --defend generates the GitHub Actions workflow step, the skylos-defend pre-commit hook gates locally, and $GITHUB_STEP_SUMMARY gets a score summary automatically in Actions.
• Policy as code: skylos-defend.yaml pins gate thresholds and severity overrides (--policy).
• Agent-native: the verify_agent MCP tool lets coding agents verify the agents they build — deterministic verification, not AI checking AI.

Static pre-deployment verification complements runtime controls (gateways, policy engines, human approval flows); it does not replace them. Full guide: docs/agent-verification.md.

Test Running Agent Behavior

Skylos separates generated-code truth, static agent guardrails, and observed runtime behavior:

Create .skylos/agent-test.yml, then test a live OpenAI-compatible endpoint:

skylos agent initskylos agent test --allow-contract-endpoint

Or evaluate captured evidence without a network call:

skylos agent test --observations agent-observations.jsonskylos agent test --observations agent-observations.json \  --format json --output agent-results.json

Version 1 deterministically checks exact response substrings, required, allowed, and forbidden tool calls, tool arguments and sequence, maximum call count, explicit refusals, and explicit source IDs. Missing typed evidence is incomplete, never pass; exit codes are 0 pass, 1 violation, and 2 incomplete/invalid. Tool selection and final-answer source-ID checks are separate one-turn scenarios: Skylos records local replayable evidence but never executes tools returned by the target agent. Offline observations are marked as unverified fixtures rather than runtime proof.

For an authenticated remote endpoint, keep the destination and secret choice in the trusted CLI invocation:

skylos agent test --endpoint https://agent.example.com/v1/chat/completions \  --allow-remote --auth-env MY_AGENT_API_KEY

Full guide: docs/agent-behavior-testing.md.

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 (App/Pages Router files and metadata routes), React, Laravel (auto-discovered commands, listeners, components, factories, seeders), Drupal (classes named in an extension's YAML, discovered plugins, OOP hooks, procedural hooks in .module/.install/.inc/.theme files, post-update functions), tool config files, package entrypoints, and common plugin patterns.
• PR-focused output: diff scanning, CI thresholds, GitHub annotations, and baselines for existing findings.
• Local-first operation: core analysis executes locally and does not upload source or call an LLM. Dependency/CVE checks can query OSV or package registries, and direct container scanning contacts a registry through Trivy. See What Leaves Your Machine.
• 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 use a versioned result schema for AI-code trust, security, and secret findings, so coding agents can self-correct before a human sees the change. The CLI renders a human report on a terminal and JSON when redirected or written with -o.
• Evidence-backed AI defects: --ai-defects and full scans put strict AI-code failure checks under ai_defects, including phantom references, fake package APIs, nonexistent packages, impossible dependency versions, and weakened test assertions. The category/tag is ai_defect; several rules intentionally keep historical SKY-L or SKY-D IDs for suppression and baseline compatibility, while new AI-defect-only checks use SKY-A.
• 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 pre-deployment agent verification commands share the same CLI.

What Leaves Your Machine

Skylos sends nothing to Skylos Cloud unless the command or flag you ran says it talks to Skylos Cloud: skylos cloud, --upload, skylos login, whoami, project, sync, credits, upload, ingest claude-security, verify-verdict, feedback, or the --verify scan option. A token on its own (SKYLOS_TOKEN, a saved skylos login, a CI OIDC token) never makes a command upload a scan, findings or a run summary. There is no update check and no analytics.

• --ai-review and --verify-security never send anything to Skylos Cloud by themselves. They send the flagged file (comments removed) and the rule's message to your own model provider with your key. With TYPESAFE_API_KEY set, --ai-review also sends the unused-code candidates and a bounded copy of your first-party source (at most 64 KB) to Jev (api.typesafe.ai). The verdicts reach Skylos Cloud only with --upload or skylos cloud.
• skylos agent verify, agent remediate and agent remediate --standards send a run summary only with --upload, and skylos agent scan --upload sends the same summary plus its findings: one POST /api/agent-runs with command, per-command counts, model, provider, duration_seconds, commit_hash, branch, actor and status. actor is SKYLOS_ACTOR, the CI-reported user, or the HEAD commit's author, else null; never your operating-system user name. No source, paths, finding text, prompts or model output.
• Three things reach Skylos Cloud without such a command, and none sends code or findings: a scan downloads your Cloud custom rules when a token can be found (SKYLOS_CUSTOM_RULES='[]' skips it); skylos doctor checks your credit balance (--format json skips it); and the MCP server started with SKYLOS_API_KEY checks the key every 15 minutes and asks Skylos Cloud to charge each scan or remediate call. Only remediate costs credits (10 a call), and only when it calls a model; dry runs send no charge request.
• skylos feedback makes no request itself: it opens a form on skylos.dev (or, with --github, GitHub's issue form) in your browser. The page address carries the Skylos version, OS, Python version and the last failed command with paths and secrets masked; your message is sent only when you press Send.
• Package lookups on other hosts send package names and versions, never source: OSV for dependency checks, and PyPI, npm, the Go proxy and JSR for packages that don't exist (on by default in skylos done, skylos verify, agent scan, agent pre-commit and the agent hooks). Dependency checks can also fetch GitHub fix commits, with GITHUB_TOKEN if it is set. LLM commands send code excerpts to the model provider you configure, and skylos cicd review posts PR comments through gh.

Every request, its trigger and its off switch: docs/privacy-and-network.md.

Agent Harness Artifacts

skylos agent verify . and skylos agent test record replayable artifacts under .skylos/runs/<run-id> and print 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. Replay checks internal consistency and corruption; artifacts are not signed and are not proof against an actor that can rewrite the entire run directory.

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.
• behavior-results.json: normalized runtime assertions, provenance, coverage, and a digest-bound evidence report for skylos agent test runs.

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 analysispip install skylos
# LLM-powered agent workflowspip install "skylos[llm]"
# Ruff Python linting through `skylos lint`pip install "skylos[lint]"
# Ed25519 verification for `skylos verify-verdict`pip install "skylos[verdict]"
# Dart analysis, 4.47.2 and later (builds the Dart parser from source; needs a C compiler)pip install "skylos[dart]"
# All published optional extraspip install "skylos[all]"

Container image:

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

The unqualified image uses Python 3.14. Runtime-specific tags are also published for Python 3.11 through 3.15, so container scans can match a local or CI parser exactly:

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

If a Python file cannot be parsed, Skylos names it as not analysed, marks coverage incomplete, and reports every other finding; the file is never treated as clean. The exit code is decided on the code that was analysed; --strict exits 2 instead, and so does a scan where most of the code could not be analysed. See Exit Codes And Incomplete Analysis.

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

Configure Vibe Checks And Entrypoints

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

[tool.skylos]exclude = ["node_modules", "dist"]
[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 = falsecontribute_public_corpus = falsestructural_signatures_only = trueinclude_source = false

LLM prompt templates are not read from the repository: pass a trusted file with --prompt-template KIND=PATH to skylos agent scan, agent audit, agent security-quick or agent security-deep (KIND is security, quality, security_audit or review). A template extends Skylos' built-in prompt; it does 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.

Where settings come from. Skylos walks up from the scan path to the repository root (the folder with .git) and reads, in each folder, the first of these that exists:

1. .skylos.toml
2. skylos.toml
3. pyproject.toml with a [tool.skylos] table (a pyproject.toml without one is skipped, so it no longer hides the settings above it)

skylos.toml takes the same keys as [tool.skylos], at the top level, so TypeScript, Go and Java repositories need no pyproject.toml:

# skylos.tomlexclude = ["generated", "dist"]
[gate]max_security = 0
[done]test_command = "npm test"

In a monorepo every file found on the way up applies: the repository root is the base and the file nearest the scanned folder wins per key. A key set in a package replaces the root's value (lists are replaced, not concatenated); tables such as [gate] merge key by key. Set root = true in a package's file to ignore everything above it. skylos doctor lists the files in use, nearest first, and the ones it ignored. In PR CI, settings come from the base commit only, with the same rules, and skylos done reports an added or edited skylos.toml as a change to Skylos settings (SKY-A114). [done] and [approval] settings are read from the repository root's file.

To use one file instead of discovery, pass --config-file PATH or set SKYLOS_CONFIG_FILE; it may use [tool.skylos], [skylos], or (when named skylos.toml) top-level keys. 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.

A full scan skips generated and vendored files (Django migrations, static/**/lib/**, *.min.js, *.min.css, vendored-library banners) and says how many in one line of output. Set include_generated = true under [tool.skylos] (or pass --include-generated) to scan them; see What a full scan leaves out.

Language Support

¹ 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 official GitHub Action builds it. Elsewhere, skylos doctor prints the command that builds it. Without it only Go quality checks run and the Go files are reported as not analysed; see the Go engine note below.

² Kotlin dead code reports only private types and functions and unused imports; every non-private declaration is treated as used. No built-in Kotlin security rules; secret scanning still covers .kt and .kts files.

³ From 4.47.2, Dart checks need the optional skylos[dart] extra (pip install "skylos[dart]"); earlier releases install the Dart parser by default. The parser has no prebuilt wheels, so installing it needs a C compiler. Without it, a scan that includes .dart files reports them as not analysed (SKY-ANALYSIS-INCOMPLETE, incomplete coverage) instead of skipping them silently; skylos doctor shows whether Dart support is installed.

⁴ Rust dead code is experimental: trait-method calls, pub items used across crates, re-exports, macros and #[bench] functions are not resolved, and a previous hand-checked sample on ripgrep found no true positives. Rust candidates are capped at confidence 40, below the default threshold, so they are not listed unless you pass --confidence 40; the scan says so in one line. rustc's own unused_imports and dead_code lints cover private items.

Rust quality checks cover statements after a direct return, break or continue, and duplicate multi-statement if/else bodies with a plain boolean condition. They do not expand macros or infer complete control flow.

"No" means Skylos has no built-in rules of that kind for the language.

C# dead-code findings are conservative: in a complete executable or web application scan, unreferenced public types and methods are low-confidence candidates; library APIs, protected members, and known framework or configured entry points remain externally reachable. C# source-file reachability is not implemented. Quality scanning detects statements after unconditional return, throw, break, or continue in a direct block; it is not full control-flow analysis. Security coverage includes selected tainted-input sinks and generic secret scanning of .cs files when --secrets or -a is enabled. Interpolated raw-string expressions are not yet followed by C# taint analysis. SCA inventories direct NuGet PackageReference entries in .csproj files. Only unconditional exact Version pins ([version]) without local Update/Remove mutations, not VersionOverride or centrally managed versions, can be checked against advisories. Ordinary NuGet version values are minimum bounds, so without a resolved lockfile their installed versions and vulnerability status remain unknown. Transitive packages are not inventoried.

Java security analysis follows directly implemented request-data helpers in same-package files or source files identified by exact imports or fully qualified names under a verified local source root. Helper reads are bounded and reject symlinks; no Java code or build scripts are executed. This is not full classpath or recursive helper analysis. Unknown helpers are not assumed to be request sources or sanitizers.

C++ analysis covers .cpp, .cc, .cxx, .hpp, .hh, and .hxx. The first release reports only apparently unused file-local free functions. Without a build configuration, it cannot fully resolve templates, overloads, macros, or external usage; these findings are a conservative heuristic, not a proof of C++ deadness. Ambiguous .h files and C files are not analyzed as C++.

Java weak-hash checks also follow local algorithm variables and values loaded through java.util.Properties from literal classloader resources. Resource lookup stays within the matching src/main/resources or src/test/resources directory. Missing resources, unsupported loaders/layouts, conflicting branch values, and unresolved mutations remain unknown. Properties are used only as crypto evidence, never to prove a security guard or choose a safe branch. This does not resolve arbitrary runtime classpaths, JAR resources, or environment overrides.

TypeScript and JavaScript dead code analysis recognizes package.json entry fields, including bin. For targets under dist/ or out/, it checks the matching src/ location first, then the package root, before the declared output. This also covers dist/bin/palee.js mapping to bin/palee.ts and dist/src/index.js mapping to src/index.ts. If both source locations exist, the src/ mapping keeps priority; unrelated files are not treated as entries.

For ESM build scripts invoked by package scripts, Skylos also follows top-level esbuild calls using unchanged constants, spreads, templates, Node path helpers, and simple literal-array maps. Build scripts are never executed. Nested build calls and filesystem-generated entry lists remain unsupported and may still produce unused-file findings.

VitePress configs at .vitepress/config.* and .vitepress/config/index.* are recognised as development entrypoints for .js, .ts, .mjs and .mts. Other files in .vitepress still need a reference or another entrypoint rule. Existing directory conventions such as scripts/ work with native Windows separators too; this does not add general discovery of commands in CI workflows.

Vue single file components (.vue) are skipped by source analysis, including when passed explicitly. Skylos does not yet parse their <script> or <script setup> blocks; separate JavaScript, TypeScript and backend source files are still analyzed. Existing browser script and event references in templates are unaffected.

Go dead-code and security checks require the native skylos-go engine. If Skylos discovers Go files but cannot run that engine, it names them as not analysed, marks coverage incomplete and never reports them as clean. A few stray .go files are a coverage warning; when most of the code is Go the scan exits 2. Run skylos doctor to verify engine availability: it prints the version-matched build command, and SKYLOS_GO_BIN points Skylos at a separately built engine. The container image includes the engine and the official GitHub Action builds it automatically.

See Rules Reference for rule families and scanner scope.

Config And Deployment Support

With --danger or -a, a directory scan inside a Git worktree also checks that worktree's root .github/workflows/*.yml / *.yaml and .gitlab-ci.yml. For example, skylos src --danger checks the CI configuration that applies to src while keeping source, container and deployment analysis in src. Unrelated staged or unstaged edits do not narrow a full scan. Explicit diff filters still select changed configuration files; a single-file scan stays limited to that file. See scan scope.

Other Workflows

These workflows cover narrower jobs: container images, Kubernetes deployment exposure, and GPU release artifacts.

Check an Exact GPU Release Artifact

skylos preflight checks the built artifact itself against the repository's declared GPU fleet. This is separate from the SKY-GPU* source scan, which checks Dockerfiles, CUDA build settings, and TensorRT packaging intent before the artifact exists.

Declare every machine that receives the same release:

# .skylos/gpu-targets.ymlversion: 1targets:  - name: inference-t4    vendor: nvidia    driver: "535.104.05"    compute_capability: "7.5"    platform: "linux/amd64"

The canonical filename is .skylos/gpu-targets.yml; the same schema is also accepted as .skylos/gpu-targets.yaml.

Then inspect a local build. Skylos uses a trusted system cuobjdump, takes a private snapshot, and never loads or executes the artifact:

skylos preflight build/app

To make the command argument-free in CI, bind it to a project-relative artifact with a strict release receipt:

{"version": 1, "artifact": "build/app"}

Save that file as .skylos/release.json, then run skylos preflight. For requests that reach report generation, terminal output is concise and redirected output is schema-versioned JSON. Argument or adapter errors can be plain text and exit 2.

cuobjdump can report several code-object groups, identified by the producer label in its selected executable fatbin. Skylos requires a compatible route for every reported group. A PTX-only route stays UNKNOWN because static inspection cannot prove that the deployment driver will JIT it successfully. The overall result is FAIL if any target or required check fails; otherwise it is UNKNOWN if any result is unknown, and PASS only when all results pass.

Version 1 proves the local artifact identity, Linux ELF platform, selected executable-fatbin architecture routes, a static packaged $ORIGIN CUDA runtime route, and documented CUDA driver-family compatibility. It does not prove runtime execution, workload correctness, memory demand, performance, nonselected or relocatable fatbins, or per-kernel symbol parity. Windows PE runtime import proof is not implemented. Digest-pinned OCI references are accepted as identities but are never pulled or started, so the CLI always reports UNKNOWN for them; trusted callers can supply digest-bound inspection facts through skylos.preflight.run_preflight(...).

Benchmark Snapshot

Skylos has checked-in regression suites for dead code, security, quality, agent review and AI-code defects. They are regression gates, not independent benchmarks: we wrote the cases, so we don't quote their scores as accuracy. Case counts change as the suites grow; the manifests are the current source.

For methodology, dated results, competitor baselines and caveats, including the frozen golden-v0.2 suites, see BENCHMARK.md. The done-gate benchmark replays published agent runs and reports what the gate missed.

An experimental Jev runner can blindly score the pinned jev-1.13.0 typed decision model against the checked-in dead-code labels or the frozen skylos-benchmarks corpus. It withholds labels and review reasons from the request, retains golden label IDs locally for exact classifier comparison, and repeats the test with answer-signaling identifiers neutralized when that can be done without changing fixture semantics. An offline comparator now reports label-by-label corrections, regressions, abstentions, and unsafe removals against a frozen Skylos result. Live mode sends fixture source to TypeSafe, requires an explicit flag and a separate TYPESAFE_API_KEY; it supports bounded, resumable runs and records request versus local contract-validation latency. Normal Skylos scans need no Jev key. The paid Jev runs so far are small development runs on synthetic suites, not an independent holdout, and on some suites Jev did not improve classification. The dead-code benchmark guide and the same-run comparison report those results with their caveats.

Dead-code review is opt-in. A normal skylos . scan stays local and uses no model. skylos agent verify . uses the LLM verifier by default; choose Jev explicitly when you want it:

skylos agent verify . --format json                         # LLM onlyskylos agent verify . --dead-code-review jev --format json  # Jev onlyskylos agent verify . --dead-code-review jev-llm --format json  # Jev, then LLM if uncertain

Jev-only needs TYPESAFE_API_KEY, not an LLM key. Confident Jev "unused" decisions retain a static finding and confident "used" decisions suppress it; uncertain or unavailable decisions leave the finding visible as unverified. Jev-plus-LLM also needs a configured LLM provider and sends uncertain decisions to the LLM. Jev alone never authorizes --fix. If you select either Jev mode without TYPESAFE_API_KEY, Skylos stops with setup instructions instead of silently switching review modes. Get a key by signing in at the official TypeSafe console (access may require an invitation), then set TYPESAFE_API_KEY in your environment; do not put it in source control or a command-line argument.

Jev sends a bounded project source snapshot to TypeSafe (currently at most 64 KB). Check it for embedded secrets and confirm sharing is authorized; the local file guard is not a secret scanner. Oversized or unsafe snapshots cannot be judged by Jev. The older --jev-judge and --jev-precheck flags remain available for compatibility; use --dead-code-review for new workflows. See the dead-code review guide for key setup, fallback behavior, and limitations.

Real-project regression testing

liveness_primer, created and maintained by Matthew Digman, is Skylos's official real-project regression testing tool. On every PR, it compares the base and proposed merge result against the same pinned Python projects and reports which findings were added, removed, or changed.

Read the Analyzer Blast Radius check for the comparison and downloadable reports. These results complement the labeled benchmarks above; a change in finding counts alone does not establish accuracy. See the liveness_primer guide for scope, review steps, and reproduction commands.

Project Evidence

10 Skylos-assisted dead-code cleanup PRs have been merged into the default branch in 9 open-source projects, including Black, NetworkX, Optuna, mitmproxy, pypdf and pdm. Of the other 16 PRs we recorded, one was merged into a maintainer's staging branch but did not reach main (Flagsmith), one was a merged quality fix rather than dead code, one was merged and then reverted, four were closed by maintainers, seven were closed by us and two are still open. These are accepted cleanup PRs, not endorsements or adoption.

Candidates came from Skylos static analysis, were often triaged with the LLM-based skylos agent verify, and were checked by hand before each PR. Real-World Results lists the 26 recorded cleanup and quality-fix PRs with their outcomes and the maintainers' reasons.

Integrations

Set up a pull request gate from the CLI. skylos cicd init finds your CI (GitHub Actions, GitLab CI, Jenkins, Bitbucket Pipelines, Azure Pipelines, CircleCI) and writes its file, or prints the block to add when the file already exists. Other CIs get the commands to add; see Skylos on any CI.

skylos cicd init --no-upload                       # without Skylos Cloudskylos cicd init --no-upload --scan-path apps/api  # a monorepo subprojectskylos cicd init --upload                          # with Skylos Cloud uploadsskylos cicd init --no-upload --risk-review         # plus the "Skylos risk review" checkskylos cicd init --ci jenkins                      # a Jenkinsfile pull request stage

On GitHub Actions, the generated workflow reviews changed lines on pull requests and adds a skylos done job when it finds your tests. With --upload (the default when this machine is logged in to Skylos Cloud; without a login it prints how to add it) it also uploads full scans to Skylos Cloud using GitHub OIDC, from default-branch pushes and from pull requests to the default branch (pull_request_target: the pull request is scanned as data without credentials, then a job that never checks out its files uploads it). Uploads fail until the Skylos GitHub App is installed on the repository. It supports monorepo subprojects through --scan-path. See Your first Skylos-gated pull request.

To scan a built image with the composite Action, install a pinned Trivy version in the caller's job and set image to a trusted repository@sha256:<digest> build output plus image-platform. This runs an image-only scan; mode: gate uses image-fail-on (default high), while mode: scan only reports findings. See container-image scanning.

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, quality, and AI-defect checks.

Does Skylos require an LLM?

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

Is Skylos free?

The Skylos CLI is free and open source (Apache-2.0). Skylos Cloud has a Free plan for one project and a Workspace plan. Your first workspace gets a 14-day Workspace trial with 50 credits, no card needed. Any credit pack (from $9 for 50 credits) turns on Workspace for 12 months for up to 3 people. The Workspace pass ($990 once) has unlimited members. Prices are in USD, plus sales tax or VAT. Payments are one-time: nothing renews, and there are no seats or subscriptions. Credits never expire.

Does the MCP server need an account?

Without SKYLOS_API_KEY the MCP server only exposes analyze (dead code, five calls per rolling 24 hours). Every other MCP tool (verify_change, verify_agent, security_scan, secrets_scan, and so on) returns an authentication error until the server is started with SKYLOS_API_KEY set; create a free key in the Skylos Cloud dashboard settings. MCP scans (analyze, security, quality, secrets, provenance) cost no credits. remediate costs 10 credits per real run, charged when it starts generating fixes; dry runs (the default), refused calls and runs with nothing to fix are free. The CLI equivalents (skylos verify, skylos defend, skylos . -a) and skylos agent install-hooks run on your machine with no account or key; their dependency and package checks still query public registries (see What Leaves Your Machine).

Can the MCP server run in Docker or over the network?

Yes. skylos mcp --transport sse (or streamable-http) serves MCP over HTTP on MCP_BIND (default 127.0.0.1) and PORT (default 8080), and refuses to start without SKYLOS_MCP_TOKEN (at least 16 characters), the bearer token every client must send. The image built from skylos_mcp/Dockerfile sets MCP_BIND=0.0.0.0 so a published port reaches it:

export SKYLOS_MCP_TOKEN="$(openssl rand -hex 24)"docker build -f skylos_mcp/Dockerfile -t skylos-mcp .docker run --rm -p 8080:8080 -e SKYLOS_MCP_TOKEN skylos-mcp

Clients connect to http://localhost:8080/sse with Authorization: Bearer <token>. Behind a proxy, set SKYLOS_MCP_PUBLIC_URL to the address clients use.

Does Skylos replace Ruff?

No. skylos lint is an optional convenience entry point that delegates to Ruff. Install it with pip install "skylos[lint]"; normal Skylos scans do not run Ruff or merge Ruff violations into SKY-* findings.

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. A removed security control, such as a deleted auth decorator (SKY-L021), is still reported with --diff, including when the change only deletes the decorator line.

Does skylos done catch every way to fake a finished change?

No. It compares test functions (pytest, unittest, JavaScript/TypeScript), so rewriting a custom test-runner script or deleting cases from a test data file is not caught, and a test can still be weakened in ways its static assertion count cannot see. See the done gate's limits and its benchmark.

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.
• Report a problem privately with skylos feedback, which opens a prefilled form at skylos.dev/feedback. The page address carries the Skylos version, OS, Python version and the last failed command (paths and secrets masked); your message is sent only when you press Send. No account needed.
• Open public bugs and false-positive reports with minimal repros (skylos feedback --github prefills the issue form).
• 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.