lucidshark

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.

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

./lucidshark init

This configures .mcp.json and .claude/CLAUDE.md for Claude Code integration.

Restart your AI tool after running init to activate.

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 Claude Code integration | | ./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](do