lucidshark 0.10.0

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.

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

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.

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:

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

What It Checks

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

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