LucidShark

Ship AI-generated code without the fear

AI writes code → LucidShark checks → AI fixes → repeat

The quality gate for agentic engineering. As AI agents increasingly write production code, LucidShark ensures high standards through automated, comprehensive quality checks - no manual code review bottlenecks.

LucidShark Demo

Why LucidShark

Local-first - No server, no SaaS account. Runs on your machine and in CI with the same results.
Configuration-as-code - lucidshark.yml lives in your repo. Same rules for everyone, changes go through code review.
AI-native - MCP integration with Claude Code, Cursor and Windsurf, plus a lint hook for Aider. Structured feedback that AI agents can act on directly.
Unified pipeline - Linting, type checking, formatting, security (SAST/SCA/IaC), tests, coverage, and duplication detection in one tool. Stop configuring 5+ separate tools.
Open source & extensible - Apache 2.0 licensed. Add your own tools via the plugin system.

Quick Start

# 1. Install LucidShark
curl -fsSL https://raw.githubusercontent.com/toniantunovi/lucidshark/main/install.sh | bash

# 2. Configure Claude Code integration (add --cursor, --windsurf, --aider for other tools)
./lucidshark init

# 3. Restart your AI tool, then ask it:
#    "Autoconfigure LucidShark for this project"

That's it! Your AI assistant will analyze your codebase, ask you a few questions, and generate the lucidshark.yml configuration.

Installation Options

Method	Command	Usage	Notes
Install Script (Linux/macOS)	`curl -fsSL .../install.sh \| bash`	`./lucidshark`	Recommended, installs to current directory
Manual	Download from Releases	`./lucidshark`	Pre-built binaries for Linux and macOS

Important: LucidShark is distributed as a standalone binary. The installation creates a project-local ./lucidshark file. Always use ./lucidshark to ensure you're running the project-specific version.

Verified Downloads

Nothing LucidShark installs runs unverified:

The LucidShark binary. Every release publishes a SHA256SUMS file and a signed build provenance attestation. The install script checks the binary against SHA256SUMS before making it executable and aborts on mismatch. The self-updater does the same before staging an update, and checks the hash again before applying it. SHA256SUMS comes from the same release as the binary, so it catches corrupted or tampered transfers. The attestation is what proves a binary was built by this repository's release workflow. To verify a manual download:
```
shasum -a 256 -c SHA256SUMS --ignore-missing     # or: sha256sum -c SHA256SUMS --ignore-missing
gh attestation verify lucidshark-linux-amd64 --repo toniantunovi/lucidshark
```
Scanner and tool binaries (Trivy, OpenGrep, Checkov, gosec, PMD, Checkstyle, SpotBugs, ktlint, detekt, duplo). Each download is checked against a SHA-256 pinned inside LucidShark for that exact version, asset and platform (checksums.py). A mismatch, or a URL with no pin, is refused before anything is written to disk. The pins are generated by scripts/update_tool_checksums.py, which cross-checks each hash against the digest GitHub recorded when the asset was uploaded.

Running Scans

./lucidshark scan --all             # Run all quality checks
./lucidshark scan --linting         # Run specific domains
./lucidshark scan --linting --fix   # Auto-fix linting issues
./lucidshark scan --all --dry-run   # Preview what would be scanned

Scan domains: --linting, --type-checking, --formatting, --sast, --sca, --iac, --container, --testing, --coverage, --duplication

Incremental Scanning

By default, LucidShark scans only uncommitted changes (staged, unstaged, untracked files):

# Default: scan only changed files (no extra flags needed)
./lucidshark scan --linting --type-checking

# Full project scan
./lucidshark scan --all --all-files

# PR/CI: filter results to files changed since a branch
./lucidshark scan --all --base-branch origin/main

See Incremental Scanning for threshold scopes, CI integration, and advanced usage.

Note: LucidShark runs in strict mode by default - all configured tools must run successfully. If a tool is missing, not applicable, or fails to execute, the scan fails with a HIGH severity issue and fix suggestions. Security tools (trivy, opengrep, gosec, checkov), duplo, PMD, Checkstyle, SpotBugs, ktlint, and detekt are downloaded automatically.

Example Output

When issues are found:

$ ./lucidshark scan --linting --type-checking --sast
Total issues: 4

By severity:
  HIGH: 1
  MEDIUM: 2
  LOW: 1

By scanner domain:
  LINTING: 2
  TYPE_CHECKING: 1
  SAST: 1

Scan duration: 1243ms

When everything passes:

$ ./lucidshark scan --all
No issues found.

Use --format table for a detailed per-issue breakdown, or --format json for machine-readable output.

Diagnostics

Check your LucidShark setup with the doctor command:

./lucidshark doctor

This checks:

Configuration file presence and validity
Tool availability (security scanners, linters, type checkers)
Python environment compatibility
Git repository status
MCP integration (Claude Code)

AI Tool Setup

init configures Claude Code by default. Tool flags select other tools and combine freely; --all-tools configures all of them. --dry-run, --force and --remove apply to every selected tool, and shared files (CLAUDE.md, CONVENTIONS.md, .aider.conf.yml, MCP JSON files) are merged, never overwritten.

Tool	Command	What it writes
Claude Code	`./lucidshark init`	`.mcp.json`, `.claude/skills/lucidshark/SKILL.md`, `.claude/CLAUDE.md` section, `.claude/settings.json` hook
Cursor	`./lucidshark init --cursor`	`.cursor/mcp.json`, `.cursor/rules/lucidshark.mdc` (always applied)
Windsurf	`./lucidshark init --windsurf`	`.windsurf/rules/lucidshark.md` (`trigger: always_on`); prints the MCP snippet for `~/.codeium/windsurf/mcp_config.json`, since Windsurf keeps MCP servers in your home directory and `init` does not write there
Aider	`./lucidshark init --aider`	`.aider.conf.yml` keys `lint-cmd` (LucidShark on every edited file), `auto-lint`, `read: [CONVENTIONS.md]`, plus a `CONVENTIONS.md` section. Aider has no MCP support
All of the above	`./lucidshark init --all-tools`

Restart your AI tool after running init to activate.

Any other MCP client can run the server directly with lucidshark serve --mcp .. Or tell your agent:

Add the LucidShark MCP server so you can test your own output before committing.

Supported Languages

LucidShark supports 14 programming languages with full tool coverage:

Languages	What's Included
Python, TypeScript, JavaScript, Java, Kotlin, Rust, Go, C#, C, C++, Scala, Swift, Ruby, PHP	Linting, type checking, formatting, testing, coverage, security, duplication

For detailed per-language tool coverage, configuration examples, and detection info, see the Language Reference.

What It Checks

Domain	Tools	What It Catches
Linting	Ruff, ESLint, Biome, Clippy, Checkstyle, PMD, ktlint, golangci-lint, dotnet format, clang-tidy, Scalafix, SwiftLint, RuboCop, phpcs	Style issues, code smells, bug detection
Formatting	Ruff Format, Prettier, ktlint, rustfmt, gofmt, dotnet format, clang-format, Scalafmt, SwiftFormat, RuboCop Format, PHP-CS-Fixer	Code formatting, whitespace style
Type Checking	mypy, Pyright, TypeScript (tsc), SpotBugs (managed), detekt, cargo check, go vet, dotnet build, cppcheck, scalac, Swift compiler, Sorbet, PHPStan	Type errors, static analysis bugs
Security (SAST)	OpenGrep, gosec (Go)	Code vulnerabilities
Security (SCA)	Trivy	Dependency vulnerabilities
Security (IaC)	Checkov	Infrastructure misconfigurations
Security (Container)	Trivy	Container image vulnerabilities
Testing	pytest, Jest, Vitest, Mocha, Karma (Angular), Playwright (E2E), Maven/Gradle (JUnit), cargo test, go test, dotnet test, CTest, sbt test, swift test, RSpec, PHPUnit	Test failures
Coverage	coverage.py, Istanbul, Vitest, JaCoCo, Tarpaulin, go cover, dotnet coverage, gcov/lcov, Scoverage, llvm-cov, SimpleCov, PHPUnit Clover	Coverage gaps
Duplication	Duplo	Code clones, duplicate blocks

All results are normalized to a common format.

Quality Overview

Track quality trends over time with a git-committed quality dashboard - no server or SaaS required.

./lucidshark scan --all --all-files && ./lucidshark overview --update

This creates QUALITY.md at your repo root showing:

Health score (0-10) with visual bar
Domain status table with trends
Issues breakdown by severity
Top files by issue count
Test coverage and duplication metrics
Historical trend chart

Add to your CI pipeline to auto-update on merge to main. See docs/help.md for configuration options.

Configuration

LucidShark auto-detects your project. For custom settings, create lucidshark.yml:

version: 1
pipeline:
  linting:
    enabled: true
    tools: [{ name: ruff }]
  type_checking:
    enabled: true
    tools: [{ name: mypy, strict: true }]
  formatting:
    enabled: true
    tools: [{ name: ruff_format }]
  security:
    enabled: true
    tools:
      - { name: trivy, domains: [sca, container] }
      - { name: opengrep, domains: [sast] }
      - { name: gosec, domains: [sast] }   # Go-specific SAST (auto-detected)
  testing:
    enabled: true
    command: "make test"            # Optional: custom command overrides plugin-based runner
    post_command: "make clean"      # Optional: runs after tests complete
    tools: [{ name: pytest }]
  coverage:
    enabled: true
    threshold: 80
    tools: [{ name: coverage_py }]
  duplication:
    enabled: true
    threshold: 10.0
fail_on:
  linting: error
  security: high
  testing: any
ignore_issues:
  - rule_id: CVE-2021-3807
    reason: "Not exploitable in our context"
    expires: 2026-06-01
exclude: ["**/node_modules/**", "**/.venv/**"]

See docs/help.md for the full configuration reference.

CLI Reference

Command	Description
`./lucidshark scan --all`	Run all quality checks
`./lucidshark scan --linting --fix`	Lint and auto-fix
`./lucidshark scan --formatting --fix`	Format and auto-fix
`./lucidshark overview --update`	Generate/update QUALITY.md
`./lucidshark init`	Configure AI tool integration (Claude Code by default; `--cursor`, `--windsurf`, `--aider`, `--all-tools`)
`./lucidshark doctor`	Check setup and environment health
`./lucidshark validate`	Validate `lucidshark.yml`

For the full CLI reference, all scan flags, output formats, and exit codes, see docs/help.md.

Development

To build LucidShark from source:

git clone https://github.com/toniantunovi/lucidshark.git
cd lucidshark

# Install Python dependencies
pip install -r requirements.txt -r requirements-dev.txt

# Build the binary
pyinstaller lucidshark.spec

# The binary will be in the dist/ directory
./dist/lucidshark --version

Documentation

Supported Languages - Per-language tool coverage, detection, and configuration
Incremental Scanning - PR-based filtering, threshold scopes, CI integration
Quality Overview - Git-committed quality dashboard, trends, and CI integration
LLM Reference Documentation - For AI agents and detailed reference
Exclude Patterns & Issue Ignoring - File exclusions, per-domain excludes, and ignoring specific issues
Full Specification

License

Apache 2.0