Skip to content
Back to search

skylos

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/

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/duriantaco/skylos with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/duriantaco/skylos'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/duriantaco--skylos/badge.svg)](/listings/duriantaco--skylos)

HTML

<a href="/listings/duriantaco--skylos"><img src="/api/listings/duriantaco--skylos/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Core static analysis
pip install skylos

# LLM-powered agent workflows
pip install "skylos[llm]"

# Ruff Python linting through `skylos lint`
pip install "skylos[lint]"

# Ed25519 verification for `skylos verify-verdict`
pip install "skylos[verdict]"

# All published optional extras
pip install "skylos[all]"

Container image:

docker pull ghcr.io/duriantaco/skylos:latest
docker 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.14, 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.13 . --json --no-provenance

If a Python file cannot be parsed, Skylos reports `analysis_errors`, omits the grade, and exits with code 2 instead of treating the skipped file as clean.

See [Installation](https://docs.skylos.dev/installation) for source installs, container usage, and optional dependencies.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 400 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src="assets/DOG_1.png" alt="Skylos" width="160">
  3. <h1>Skylos</h1>
  4. <p><strong>Code checks that show their work.</strong></p>
  5. [![PyPI version](https://img.shields.io/pypi/v/skylos)](https://pypi.org/project/skylos/)
  6. ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/skylos)
  7. ![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)
  8. [![codecov](https://codecov.io/gh/duriantaco/skylos/branch/main/graph/badge.svg)](https://codecov.io/gh/duriantaco/skylos)
  9. ![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/oha.skylos-vscode-extension)
  10. [![MCP Toplist](https://mcptoplist.com/badge/io.github.duriantaco%2Fskylos.svg)](https://mcptoplist.com/server/io.github.duriantaco%2Fskylos)
  11. [Docs](https://docs.skylos.dev) · [Quick start](#quick-start) · [Website](https://skylos.dev) · [VS Code](./editors/vscode/README.md) · [Discord](https://discord.gg/Ftn9t9tErf)
  12. **English** | [Deutsch](./docs/i18n/README.de.md) | [简体中文](./docs/i18n/README.zh-CN.md)
  13. </div>
  14. ## What is Skylos?
  15. Skylos is a free, open-source (Apache-2.0) checker for the code you and your
  16. coding agents write. It runs on your machine, inside your agent's loop and as a
  17. pull-request gate. No account, no API key and no LLM needed.
  18. Coding agents such as Claude Code, Codex and Cursor write code faster than
  19. anyone can review it, and they repeat the same mistakes. They say "done" after
  20. deleting or skipping a failing test. They install packages that don't exist and
  21. import functions nobody wrote. They leave injection bugs and hard-coded keys
  22. behind. Linters and security scanners each catch a slice of this, after the
  23. fact. Skylos checks all of it in one tool, at the points where it can still be
  24. stopped.
  25. It is built for:
  26. - **Developers who let agents write code**, and want the agent checked while it
  27. works, not after.
  28. - **Maintainers** who want one free check on every pull request.
  29. - **Existing codebases** that need security, secrets, dependency, quality and
  30. dead-code findings from one scan, in Python, TypeScript, Java, Go and
  31. [more](#language-support).
  32. ## How it works
  33. Skylos steps in at four points:
  34. | When | Command | What it stops |
  35. |:---|:---|:---|
  36. | While the agent works | `skylos agent install-hooks` | Made-up package installs, reads of files holding secrets, git-hook bypasses; checks every edit |
  37. | 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 |
  38. | On every pull request | `skylos cicd init` | Critical security issues, secrets and critical AI-code mistakes, plus anything over your limits |
  39. | Any time, on the whole repo | `skylos . -a` | Security flaws, secrets, vulnerable dependencies, quality regressions, AI-code mistakes, dead code |
  40. ## See it work
  41. A 20-line Flask app, scanned with every check (excerpt):
  42. ```text
  43. $ skylos . -a --format concise
  44. app.py:15 SKY-D211 Possible SQL injection: tainted or string-built query.
  45. app.py:5 SKY-L012 Import from local module 'billing' requests 'issue_refund', but that name is not defined or re-exported there.
  46. app.py:8 SKY-S101 Potential stripe secret detected
  47. requirements.txt:1 SKY-SCA-GHSA-68rp-wp8r-4726 flask@3.1.2: Flask session does not add `Vary: Cookie` header when accessed in some ways
  48. billing.py:1 SKY-U001 unused function: charge_card
  49. ```
  50. Every finding names the file, line and rule. Security findings show the
  51. source-to-sink path when one was recorded; `--format json` keeps the full
  52. evidence.
  53. ## Quick start
  54. ```bash
  55. pip install skylos
  56. skylos . -a # run every check on this repo
  57. skylos done --base main # did the agent really finish? runs your tests, compares with main
  58. skylos cicd init # add a Skylos check to every pull request
  59. ```
  60. Working with a coding agent? Two commands:
  61. ```bash
  62. skylos setup # once per repo: connects Claude Code and Codex, installs their hooks, lets Done run your tests, writes the PR check
  63. skylos open # every day: diagram of your code, what changed in plain English, every check run
  64. ```
  65. The [tutorial](./docs/workflow.md) walks through a real session: the agent
  66. makes a change, gets blocked, and fixes it from Skylos's fix brief.
  67. `skylos .` on its own runs the fast dead-code scan. `skylos cloud` uploads
  68. results to track each branch on Skylos Cloud; it is optional.
  69. ## Check every agent edit
  70. Install hooks so the agent is checked while it works:
  71. ```bash
  72. skylos agent install-hooks # Claude Code
  73. skylos agent install-hooks --codex # Codex
  74. skylos agent install-hooks --cursor # Cursor
  75. ```
  76. - **After each edit:** checks the changed lines for security issues, secrets
  77. and AI-code mistakes, and tells the agent what to fix.
  78. - **Before a file read:** blocks files that contain hard-coded secrets.
  79. - **Before a package install** (`pip`, `uv`, `npm`, `pnpm`, `bun`, `go`, ...):
  80. blocks made-up or typosquatted packages, and asks before installs it cannot
  81. verify.
  82. - **Before a git command:** blocks `--no-verify` and other ways around your
  83. git hooks.
  84. - **At stop:** blocks "done" while issues the agent added are still open.
  85. If Skylos itself errors, the action is allowed and both you and the agent are
  86. told it went unchecked. See [agent hooks](./docs/agent-hooks.md).
  87. ## Is the agent really done?
  88. ```bash
  89. skylos done --base main
  90. ```
  91. `skylos done` compares the branch with `main` and runs your tests. It flags:
  92. - deleted, skipped or weakened tests
  93. - loosened test settings and CI test steps
  94. - silenced lint or type checks
  95. - code that special-cases the tests
  96. - code the branch left with no callers (advice, not a block)
  97. When a test fails, it reruns it on `main` and labels the failure "introduced"
  98. or "already failing". It writes a receipt to `.skylos/receipts/`. pytest runs
  99. automatically; other runners need one line:
  100. ```toml
  101. [tool.skylos.done]
  102. test_command = "npm test"
  103. ```
  104. It reads its settings from `main`, so a branch cannot loosen its own check.
  105. Exit codes: `0` pass, `1` blocked, `2` could not run. See the
  106. [done gate](./docs/done-gate.md) and what it [misses](./docs/done-gate-benchmark.md).
  107. <a id="cicd"></a>
  108. ## Gate pull requests
  109. No account or token needed:
  110. ```bash
  111. git checkout -b add-skylos-gate
  112. skylos cicd init --no-upload
  113. git add .github/workflows/skylos.yml
  114. git commit -m "Add Skylos pull request gate"
  115. git push -u origin add-skylos-gate
  116. ```
  117. The workflow reviews the changed lines of each pull request and runs
  118. `skylos done` when it finds your tests. `skylos cicd init` also sets up GitLab
  119. CI, Jenkins, Bitbucket Pipelines, Azure Pipelines and CircleCI
  120. ([any CI](./docs/ci-platforms.md)).
  121. The gate always fails on a critical security issue, a secret, or a critical
  122. AI-code issue such as an import of a package that doesn't exist. Everything
  123. else fails only above your limits:
  124. ```toml
  125. [tool.skylos.gate]
  126. max_high = 5 # high-severity security issues allowed
  127. max_quality = 10 # quality issues allowed
  128. max_ai_defects = 10 # AI-code issues allowed
  129. ```
  130. The policy is read from the base branch, so a pull request cannot loosen its
  131. own gate. Each run ends with `Quality Gate: PASSED`, `FAILED` (exit 1) or
  132. `INCOMPLETE` (exit 2) and the reasons. Walkthrough:
  133. [your first gated pull request](./docs/first-gated-pr.md).
  134. Need a person to sign off on risky changes? `skylos cicd init --risk-review`
  135. adds a check that waits for a human approval when a pull request deletes
  136. tests, removes auth checks, changes dependencies or weakens CI. See
  137. [risk review](./docs/risk-review.md).
  138. ## Scan a repository
  139. ```bash
  140. skylos . # dead code (fast, default)
  141. skylos . -a # every check
  142. skylos . -a --diff origin/main # only findings on changed lines
  143. skylos . --format pretty # grouped report with code snippets
  144. skylos . --tui # keyboard-driven triage
  145. skylos . -a --format json # full evidence for scripts and agents
  146. skylos . --format sarif # GitHub code scanning
  147. skylos cleanup . --top 5 # a prioritized fix list
  148. ```
  149. Python dead code can be removed for you: `skylos clean . --dry-run` shows the
  150. plan, `--apply` edits files. Output modes and exit codes:
  151. [CLI output](./docs/cli-output.md).
  152. ## What Skylos catches
  153. | Category | Examples |
  154. |:---|:---|
  155. | AI-code mistakes | imports of functions that don't exist, invented package APIs, packages that don't exist, impossible versions, unfinished stubs, disabled controls |
  156. | Security flaws | SQL injection, XSS, SSRF, path traversal, command injection, unsafe deserialization, ReDoS |
  157. | Secrets | API keys, tokens, private credentials, high-entropy strings |
  158. | Dependencies | known CVEs, malicious packages, license policy, offline SBOM (CycloneDX, SPDX) |
  159. | Quality | complexity, deep nesting, duplicate branches, long functions, inconsistent returns |
  160. | Dead code | unused functions, classes, imports, files and dependencies, framework-aware (FastAPI, Django, Flask, Next.js, React, Laravel, ...) |
  161. | CI/CD and deployment | risky GitHub Actions and GitLab CI, Dockerfiles, Docker Compose, systemd, Kubernetes |
  162. | LLM apps | unsafe tool use, prompt-injection exposure, missing output validation |
  163. Every rule: [Rules Reference](https://docs.skylos.dev/rules-reference) and
  164. [rule dictionary](./dictionary.md).
  165. ## Verify the AI apps you build
  166. If your code calls an LLM, Skylos checks the guardrails around it, with no
  167. model in the loop:
  168. ```bash
  169. skylos discover . # list LLM calls, agent tools and prompt sites
  170. skylos defend . # score the guardrails around them
  171. skylos defend . --fail-on critical # CI gate
  172. skylos defend . --format md -o evidence.md # evidence report with OWASP LLM Top 10 coverage
  173. ```
  174. It covers Python and TypeScript/JavaScript; `--owasp-framework agentic` reports
  175. against the OWASP Agentic Top 10. To test a running agent against
  176. expected answers and tool calls, use `skylos agent test`. See
  177. [agent verification](./docs/agent-verification.md) and
  178. [agent behavior testing](./docs/agent-behavior-testing.md).
  179. ## Language Support
  180. | Language | Dead code | Security | Quality |
  181. |:---|:---:|:---:|:---:|
  182. | Python | Yes | Yes | Yes |
  183. | TypeScript / JavaScript | Yes | Yes | Yes |
  184. | Java | Yes | Yes | Yes |
  185. | Go | Yes | Partial | Partial |
  186. | PHP | Yes | Yes | No |
  187. | Rust | Experimental | Partial | Partial |
  188. | Ruby | Partial | Partial | No |
  189. | Dart | Yes | Partial | No |
  190. | C# | Partial | Partial | Partial |
  191. | C++ | Partial | No | No |
  192. | Kotlin | Partial | Partial | No |
  193. | Swift | Partial | No | No |
  194. | Shell | No | Partial | No |
  195. - Python has the deepest coverage.
  196. - Go needs the native `skylos-go` engine. It ships in the PyPI wheels for
  197. Linux, macOS and Windows; elsewhere `skylos doctor` prints the build command.
  198. - Dart needs `pip install "skylos[dart]"`.
  199. - Rust dead code is hidden by default; `--confidence 40` shows it.
  200. Full matrix and per-language limits:
  201. [language support](https://docs.skylos.dev/language-support).
  202. ## Configuration
  203. `skylos init` adds a starter config to `pyproject.toml`. Projects without one
  204. can use `skylos.toml` with the same keys at the top level:
  205. ```toml
  206. # skylos.toml
  207. exclude = ["generated", "dist"]
  208. [gate]
  209. max_high = 5
  210. [done]
  211. test_command = "npm test"
  212. ```
  213. In a monorepo, each package can have its own file; the nearest one wins per
  214. key. `skylos doctor` shows which files are in use.
  215. Silence one finding with a reason:
  216. ```python
  217. query = build_query(user_id) # skylos: ignore[SKY-D211] user_id is an int from the router
  218. ```
  219. To accept existing findings and gate only new ones, run `skylos baseline .`
  220. and scan with `--baseline`. More: [configuration](https://docs.skylos.dev/configuration).
  221. ## Integrations
  222. | Integration | What it does |
  223. |:---|:---|
  224. | [GitHub Action](./action.yml) | Pull-request gate, optional container-image gate |
  225. | [GitLab, Bitbucket, Azure, Jenkins, CircleCI](./docs/ci-platforms.md) | Pull-request gate for that CI |
  226. | [Agent hooks](./docs/agent-hooks.md) | Claude Code, Codex and Cursor checked on every edit |
  227. | [MCP server](https://docs.skylos.dev/mcp-server) | Skylos scans as tools for AI assistants |
  228. | [VS Code extension](./editors/vscode/README.md) | Findings in the editor |
  229. | [Skylos Cloud](./docs/skylos-cloud.md) | Optional: findings and the gate per branch, over time |
  230. ## Install options
  231. ```bash
  232. pip install skylos # core checks
  233. pip install "skylos[llm]" # agent commands that use an LLM
  234. pip install "skylos[all]" # every optional extra
  235. ```
  236. Or run the container image:
  237. ```bash
  238. docker run --rm -v "$PWD":/work -w /work ghcr.io/duriantaco/skylos:latest . -a
  239. ```
  240. Other extras (`lint`, `verdict`, `dart`), Python-specific image tags and
  241. source installs: [installation](https://docs.skylos.dev/installation).
  242. ## What leaves your machine
  243. Your code and findings reach Skylos Cloud only when you run a command that
  244. says it uploads, such as `skylos cloud` or `--upload`. A saved login alone
  245. never uploads anything. There are no analytics.
  246. Dependency and package checks send package names and versions to OSV and the
  247. public registries, never source. LLM commands share code only with the model
  248. provider you configure. Every request, its trigger and how to turn it off:
  249. [privacy and network](./docs/privacy-and-network.md).
  250. ## Results
  251. 10 Skylos-assisted dead-code cleanup PRs have been merged in 9 open-source
  252. projects, including [Black](https://github.com/psf/black/pull/5041),
  253. [NetworkX](https://github.com/networkx/networkx/pull/8572),
  254. [Optuna](https://github.com/optuna/optuna/pull/6547),
  255. [mitmproxy](https://github.com/mitmproxy/mitmproxy/pull/8136) and
  256. [pypdf](https://github.com/py-pdf/pypdf/pull/3685).
  257. [Real-World Results](./REAL_WORLD_RESULTS.md) lists all 26 PRs we recorded,
  258. including the ones that were closed or reverted. These are accepted cleanups,
  259. not endorsements.
  260. Methods, dated results and competitor comparisons: [BENCHMARK.md](./BENCHMARK.md).
  261. <a id="common-questions"></a>
  262. ## FAQ
  263. **Does Skylos replace Semgrep, CodeQL, Bandit or Vulture?**
  264. No. It runs alongside them. It adds agent checks, framework-aware dead code and
  265. one gate across security, secrets, dependencies and quality.
  266. **Does it need an LLM?**
  267. No. The core checks run locally with no model. LLM features are optional
  268. (`skylos[llm]`).
  269. **Is it free?**
  270. The CLI is free and open source. Skylos Cloud is optional and has a free plan;
  271. see [pricing](https://skylos.dev/pricing).
  272. **Can I check only my changes?**
  273. Yes: `skylos . -a --diff origin/main`. A removed security check, such as a
  274. deleted auth decorator, is still reported.
  275. **What about code that is only called dynamically?**
  276. Use inline ignores, a baseline, or `--trace` to record what actually runs. See
  277. [smart tracing](https://docs.skylos.dev/smart-tracing).
  278. More: [FAQ](https://docs.skylos.dev/faq).
  279. ## Documentation
  280. | Need | Read |
  281. |:---|:---|
  282. | Every command and flag | [CLI reference](https://docs.skylos.dev/cli-reference) |
  283. | Install, extras, Docker | [Installation](https://docs.skylos.dev/installation) |
  284. | Config files, ignores, baselines | [Configuration](https://docs.skylos.dev/configuration) |
  285. | Output formats and exit codes | [CLI output](./docs/cli-output.md) |
  286. | Agent hooks | [Agent hooks](./docs/agent-hooks.md) |
  287. | `skylos done` | [Done gate](./docs/done-gate.md) |
  288. | Pull-request gates | [First gated PR](./docs/first-gated-pr.md), [any CI](./docs/ci-platforms.md) |
  289. | Security and taint analysis | [Security](https://docs.skylos.dev/security-analysis) |
  290. | Dependencies, SBOM, licenses | [Dependency scanning](./docs/dependency-scanning.md), [licenses](./docs/license-compliance.md) |
  291. | AI-code checks | [AI code verification](./docs/ai-code-verification.md) |
  292. | Network requests | [Privacy and network](./docs/privacy-and-network.md) |
  293. | Rule IDs | [Rule dictionary](./dictionary.md) |
  294. ## Contributing
  295. - Read [CONTRIBUTING.md](./CONTRIBUTING.md) before sending a pull request.
  296. - Report a bug with `skylos feedback` (no account needed), or open an issue
  297. with a minimal repro.
  298. - Report security issues through [SECURITY.md](./SECURITY.md).
  299. - Analyzer changes are tested on real projects with
  300. [liveness_primer](https://github.com/mcdigman/liveness_primer), built by
  301. [Matthew Digman](https://github.com/mcdigman). See the
  302. [guide](./docs/liveness-primer.md).
  303. - Ideas to work on: [ROADMAP.md](./ROADMAP.md). Chat: [Discord](https://discord.gg/Ftn9t9tErf).
  304. ## License
  305. Apache License 2.0. See [LICENSE](./LICENSE).
  306. <!-- mcp-name: io.github.duriantaco/skylos -->

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.