Skip to content
duriantacoPublic

About

Open source local-first PR scanner that finds dead code, security bugs, secrets, quality regressions, and AI-code mistakes before merge. For first timers refer to https://duriantaco.github.io/skylos/repo-map/

Topics

Resources

Code of conduct

Contributing

Security policy

Accessibility

Stars

947 stars

Watchers

4 watching

Forks

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Latest commit

 

History

1,525 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
Skylos

Skylos

Code checks that show their work.

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

Docs · Quick start · Website · VS Code · Discord

English | Deutsch | 简体中文

What is Skylos?

Skylos is a free, open-source (Apache-2.0) checker for the code you and your coding agents write. It runs on your machine, inside your agent's loop and as a pull-request gate. No account, no API key and no LLM needed.

Coding agents such as Claude Code, Codex and Cursor write code faster than anyone can review it, and they repeat the same mistakes. They say "done" after deleting or skipping a failing test. They install packages that don't exist and import functions nobody wrote. They leave injection bugs and hard-coded keys behind. Linters and security scanners each catch a slice of this, after the fact. Skylos checks all of it in one tool, at the points where it can still be stopped.

It is built for:

  • Developers who let agents write code, and want the agent checked while it works, not after.
  • Maintainers who want one free check on every pull request.
  • Existing codebases that need security, secrets, dependency, quality and dead-code findings from one scan, in Python, TypeScript, Java, Go and more.

How it works

Skylos steps in at four points:

When Command What it stops
While the agent works skylos agent install-hooks Made-up package installs, reads of files holding secrets, git-hook bypasses; checks every edit
When the agent says "done" skylos done --base main Deleted or skipped tests, loosened CI steps, silenced lint or type checks, test-only special cases; runs your tests
On every pull request skylos cicd init Critical security issues, secrets and critical AI-code mistakes, plus anything over your limits
Any time, on the whole repo skylos . -a Security flaws, secrets, vulnerable dependencies, quality regressions, AI-code mistakes, dead code

See it work

A 20-line Flask app, scanned with every check (excerpt):

$ skylos . -a --format concise
app.py:15  SKY-D211  Possible SQL injection: tainted or string-built query.
app.py:5  SKY-L012  Import from local module 'billing' requests 'issue_refund', but that name is not defined or re-exported there.
app.py:8  SKY-S101  Potential stripe secret detected
requirements.txt:1  SKY-SCA-GHSA-68rp-wp8r-4726  [email protected]: Flask session does not add `Vary: Cookie` header when accessed in some ways
billing.py:1  SKY-U001  unused function: charge_card

Every finding names the file, line and rule. Security findings show the source-to-sink path when one was recorded; --format json keeps the full evidence.

Quick start

pip install skylos
skylos . -a               # run every check on this repo
skylos done --base main   # did the agent really finish? runs your tests, compares with main
skylos cicd init          # add a Skylos check to every pull request

Working with a coding agent? Two commands:

skylos setup   # once per repo: connects Claude Code and Codex, installs their hooks, lets Done run your tests, writes the PR check
skylos open    # every day: diagram of your code, what changed in plain English, every check run

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

skylos . on its own runs the fast dead-code scan. skylos cloud uploads results to track each branch on Skylos Cloud; it is optional.

Check every agent edit

Install hooks so the agent is checked while it works:

skylos agent install-hooks            # Claude Code
skylos agent install-hooks --codex    # Codex
skylos agent install-hooks --cursor   # Cursor
  • After each edit: checks the changed lines for security issues, secrets and 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 (pip, uv, npm, pnpm, bun, go, ...): blocks made-up or typosquatted packages, and asks before installs it cannot verify.
  • Before a git command: blocks --no-verify and other ways around your git hooks.
  • At stop: blocks "done" while issues the agent added are still open.

If Skylos itself errors, the action is allowed and both you and the agent are told it went unchecked. See agent hooks.

Is the agent really done?

skylos done --base main

skylos done compares the branch with main and runs your tests. It flags:

  • deleted, skipped or weakened tests
  • loosened test settings and CI test steps
  • silenced lint or type checks
  • code that special-cases the tests
  • code the branch left with no callers (advice, not a block)

When a test fails, it reruns it on main and labels the failure "introduced" or "already failing". It writes a receipt to .skylos/receipts/. pytest runs automatically; other runners need one line:

[tool.skylos.done]
test_command = "npm test"

It reads its settings from main, so a branch cannot loosen its own check. Exit codes: 0 pass, 1 blocked, 2 could not run. See the done gate and what it misses.

Gate pull requests

No account or token 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

The workflow reviews the changed lines of each pull request and runs skylos done when it finds your tests. skylos cicd init also sets up GitLab CI, Jenkins, Bitbucket Pipelines, Azure Pipelines and CircleCI (any CI).

The gate always fails on a critical security issue, a secret, or a critical AI-code issue such as an import of a package that doesn't exist. Everything else fails only above your limits:

[tool.skylos.gate]
max_high = 5          # high-severity security issues allowed
max_quality = 10      # quality issues allowed
max_ai_defects = 10   # AI-code issues allowed

The policy is read from the base branch, so a pull request cannot loosen its own gate. Each run ends with Quality Gate: PASSED, FAILED (exit 1) or INCOMPLETE (exit 2) and the reasons. Walkthrough: your first gated pull request.

Need a person to sign off on risky changes? skylos cicd init --risk-review adds a check that waits for a human approval when a pull request deletes tests, removes auth checks, changes dependencies or weakens CI. See risk review.

Scan a repository

skylos .                         # dead code (fast, default)
skylos . -a                      # every check
skylos . -a --diff origin/main   # only findings on changed lines
skylos . --format pretty         # grouped report with code snippets
skylos . --tui                   # keyboard-driven triage
skylos . -a --format json        # full evidence for scripts and agents
skylos . --format sarif          # GitHub code scanning
skylos cleanup . --top 5         # a prioritized fix list

Python dead code can be removed for you: skylos clean . --dry-run shows the plan, --apply edits files. Output modes and exit codes: CLI output.

What Skylos catches

Category Examples
AI-code mistakes imports of functions that don't exist, invented package APIs, packages that don't exist, impossible versions, unfinished stubs, disabled controls
Security flaws SQL injection, XSS, SSRF, path traversal, command injection, unsafe deserialization, ReDoS
Secrets API keys, tokens, private credentials, high-entropy strings
Dependencies known CVEs, malicious packages, license policy, offline SBOM (CycloneDX, SPDX)
Quality complexity, deep nesting, duplicate branches, long functions, inconsistent returns
Dead code unused functions, classes, imports, files and dependencies, framework-aware (FastAPI, Django, Flask, Next.js, React, Laravel, ...)
CI/CD and deployment risky GitHub Actions and GitLab CI, Dockerfiles, Docker Compose, systemd, Kubernetes
LLM apps unsafe tool use, prompt-injection exposure, missing output validation

Every rule: Rules Reference and rule dictionary.

Verify the AI apps you build

If your code calls an LLM, Skylos checks the guardrails around it, with no model in the loop:

skylos discover .                    # list LLM calls, agent tools and prompt sites
skylos defend .                      # score the guardrails around them
skylos defend . --fail-on critical   # CI gate
skylos defend . --format md -o evidence.md   # evidence report with OWASP LLM Top 10 coverage

It covers Python and TypeScript/JavaScript; --owasp-framework agentic reports against the OWASP Agentic Top 10. To test a running agent against expected answers and tool calls, use skylos agent test. See agent verification and agent behavior testing.

Language Support

Language Dead code Security Quality
Python Yes Yes Yes
TypeScript / JavaScript Yes Yes Yes
Java Yes Yes Yes
Go Yes Partial Partial
PHP Yes Yes No
Rust Experimental Partial Partial
Ruby Partial Partial No
Dart Yes Partial No
C# Partial Partial Partial
C++ Partial No No
Kotlin Partial Partial No
Swift Partial No No
Shell No Partial No
  • Python has the deepest coverage.
  • Go needs the native skylos-go engine. It ships in the PyPI wheels for Linux, macOS and Windows; elsewhere skylos doctor prints the build command.
  • Dart needs pip install "skylos[dart]".
  • Rust dead code is hidden by default; --confidence 40 shows it.

Full matrix and per-language limits: language support.

Configuration

skylos init adds a starter config to pyproject.toml. Projects without one can use skylos.toml with the same keys at the top level:

# skylos.toml
exclude = ["generated", "dist"]

[gate]
max_high = 5

[done]
test_command = "npm test"

In a monorepo, each package can have its own file; the nearest one wins per key. skylos doctor shows which files are in use.

Silence one finding with a reason:

query = build_query(user_id)  # skylos: ignore[SKY-D211] user_id is an int from the router

To accept existing findings and gate only new ones, run skylos baseline . and scan with --baseline. More: configuration.

Integrations

Integration What it does
GitHub Action Pull-request gate, optional container-image gate
GitLab, Bitbucket, Azure, Jenkins, CircleCI Pull-request gate for that CI
Agent hooks Claude Code, Codex and Cursor checked on every edit
MCP server Skylos scans as tools for AI assistants
VS Code extension Findings in the editor
Skylos Cloud Optional: findings and the gate per branch, over time

Install options

pip install skylos              # core checks
pip install "skylos[llm]"       # agent commands that use an LLM
pip install "skylos[all]"       # every optional extra

Or run the container image:

docker run --rm -v "$PWD":/work -w /work ghcr.io/duriantaco/skylos:latest . -a

Other extras (lint, verdict, dart), Python-specific image tags and source installs: installation.

What leaves your machine

Your code and findings reach Skylos Cloud only when you run a command that says it uploads, such as skylos cloud or --upload. A saved login alone never uploads anything. There are no analytics.

Dependency and package checks send package names and versions to OSV and the public registries, never source. LLM commands share code only with the model provider you configure. Every request, its trigger and how to turn it off: privacy and network.

Results

10 Skylos-assisted dead-code cleanup PRs have been merged in 9 open-source projects, including Black, NetworkX, Optuna, mitmproxy and pypdf. Real-World Results lists all 26 PRs we recorded, including the ones that were closed or reverted. These are accepted cleanups, not endorsements.

Methods, dated results and competitor comparisons: BENCHMARK.md.

FAQ

Does Skylos replace Semgrep, CodeQL, Bandit or Vulture? No. It runs alongside them. It adds agent checks, framework-aware dead code and one gate across security, secrets, dependencies and quality.

Does it need an LLM? No. The core checks run locally with no model. LLM features are optional (skylos[llm]).

Is it free? The CLI is free and open source. Skylos Cloud is optional and has a free plan; see pricing.

Can I check only my changes? Yes: skylos . -a --diff origin/main. A removed security check, such as a deleted auth decorator, is still reported.

What about code that is only called dynamically? Use inline ignores, a baseline, or --trace to record what actually runs. See smart tracing.

More: FAQ.

Documentation

Need Read
Every command and flag CLI reference
Install, extras, Docker Installation
Config files, ignores, baselines Configuration
Output formats and exit codes CLI output
Agent hooks Agent hooks
skylos done Done gate
Pull-request gates First gated PR, any CI
Security and taint analysis Security
Dependencies, SBOM, licenses Dependency scanning, licenses
AI-code checks AI code verification
Network requests Privacy and network
Rule IDs Rule dictionary

Contributing

License

Apache License 2.0. See LICENSE.

About

Open source local-first PR scanner that finds dead code, security bugs, secrets, quality regressions, and AI-code mistakes before merge. For first timers refer to https://duriantaco.github.io/skylos/repo-map/

Topics

Resources

Code of conduct

Contributing

Security policy

Accessibility

Stars

947 stars

Watchers

4 watching

Forks

Releases

Packages

Used by

Contributors

Languages