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#, 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

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.

Start In 60 Seconds

pip install skylos
skylos .

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

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 API key secret is needed:

git checkout -b add-skylos-gate
skylos cicd init
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

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 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.yml
version: 1
targets:
  - name: inference-t4
    vendor: nvidia
    driver: "535.104.05"
    compute_capability: "7.5"