Lipstyk

https://github.com/styrene-lab/lipstyk
Admin
Lipstyk is a static analysis tool that detects machine-generated code patterns and AI-written code...
Tokens:15,939
Snippets:180
Trust Score:5.9
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install lipstyk with Cargo

Source: https://github.com/styrene-lab/lipstyk/blob/main/README.md

Install the lipstyk tool directly from its Git repository using Cargo.

```bash
cargo install --git https://github.com/styrene-lab/lipstyk
```

--------------------------------

### Build and Install Lipstyk Agent

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

Build the lipstyk agent binary in release mode and install it to the system's PATH for use with MCP servers.

```bash
# Build the agent binary
car go build --release --features agent

# Install to PATH
cp target/release/lipstyk-agent ~/.local/bin/

```

--------------------------------

### Configuration File Example

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

A `.lipstyk.toml` file in the project root allows customization of rules, exclusion patterns, and thresholds. Rules can be enabled/disabled and their weights adjusted.

```toml
# .lipstyk.toml - project-level configuration

[settings]
exclude_tests = true      # Suppress findings in test code
threshold = 20            # Default CI gate threshold
ignore = ["vendor/**", "generated/**"]  # Glob patterns to skip

# Disable a rule entirely
[rules.structural-repetition]
enabled = false

# Adjust rule weight (lower = less impact on score)
[rules.redundant-clone]
weight = 0.25             # Downweight for Axum/actix projects that need clones

[rules.pub-overuse]
weight = 0.5              # Your mod.rs is intentionally public

# Disable verbose comment rules if your team prefers them
[rules.restating-comment]
enabled = false

[rules.over-documentation]
enabled = false
```

--------------------------------

### Build and Install Lipstyk LSP

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

Build the release version of the lipstyk-lsp binary and copy it to your local bin directory for use as a language server.

```bash
cargo build --release --features lsp
cp target/release/lipstyk-lsp ~/.local/bin/
```

--------------------------------

### Build and Install Lipstyk Agent

Source: https://github.com/styrene-lab/lipstyk/blob/main/INTEGRATION.md

Build the Lipstyk agent in release mode with the 'agent' feature and install the CLI and agent binaries to a local bin directory. Alternatively, create symbolic links for development.

```bash
cargo build --release --features agent
cp target/release/lipstyk target/release/lipstyk-agent ~/.local/bin/
ln -s $(pwd)/target/release/lipstyk ~/.local/bin/lipstyk
ln -s $(pwd)/target/release/lipstyk-agent ~/.local/bin/lipstyk-agent
```

--------------------------------

### CLI Output Example

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

This is an example of the output generated by the lipstyk CLI, showing file scores, specific findings with severity and rule names, and a summary of the analysis.

```text
src/handler.rs — slop score: 42.5 (12.3/100 lines)
  src/handler.rs:4  [warn] comment restates the code: `create a new hashmap` (restating-comment)
  src/handler.rs:12 [warn] `.unwrap()` — consider propagating with `?` (unwrap-overuse)
  src/handler.rs:22 [SLOP] 4 step-by-step comments — AI loves narrating code like a tutorial (over-documentation)
  src/handler.rs:31 [warn] `fn process_data` — name is too vague to convey intent (generic-naming)

--- summary ---
files: 3/12 with findings
diagnostics: 23 (hint: 4, warn: 17, slop: 2)
total score: 42.5
elapsed: 8ms
```

--------------------------------

### Install Lipstyk for Omegon Development

Source: https://github.com/styrene-lab/lipstyk/blob/main/INTEGRATION.md

For Omegon development, symlink the Lipstyk repository into the Omegon extensions directory. Ensure the agent binary is built and available at the path specified in manifest.toml.

```bash
ln -s /path/to/lipstyk ~/.omegon/extensions/lipstyk
cd /path/to/lipstyk && cargo build --release --features agent
```

--------------------------------

### Analyze Code with lipstyk

Source: https://github.com/styrene-lab/lipstyk/blob/main/README.md

Basic usage examples for lipstyk, including analyzing a directory, excluding tests, and applying a CI gate with a threshold.

```bash
lipstyk src/                                          # analyze everything
```

```bash
lipstyk --exclude-tests src/                          # skip #[test] / #[cfg(test)]
```

```bash
lipstyk --diff main --exclude-tests src/              # only changed lines
```

```bash
lipstyk --exclude-tests --threshold 20 src/           # CI gate
```

--------------------------------

### Lipstyk Self-Review Workflow Example

Source: https://github.com/styrene-lab/lipstyk/blob/main/README.md

Example markdown snippet for performing automatic self-reviews using `lipstyk_check` after code modifications.

```markdown
After modifying code, call lipstyk_check on the changed file. If
verdict is "suspicious" or "sloppy", fix the top findings and
re-check. Don't commit until pass: true.
```

--------------------------------

### Lipstyk TOML Configuration Example

Source: https://github.com/styrene-lab/lipstyk/blob/main/INTEGRATION.md

This TOML configuration file allows customization of Lipstyk's behavior, including excluding test files, setting CI gate thresholds, and enabling/disabling specific rules or adjusting their weights. The configuration is auto-discovered by walking parent directories.

```toml
[settings]
exclude_tests = true     # Suppress test-code findings
threshold = 20           # CI gate threshold

[rules.structural-repetition]
enabled = false          # Disable this rule entirely

[rules.pub-overuse]
weight = 0.5             # Reduce this rule's weight

[rules.restating-comment]
enabled = false          # Your team prefers verbose comments

```

--------------------------------

### Neovim LSP Configuration for Lipstyk

Source: https://github.com/styrene-lab/lipstyk/blob/main/INTEGRATION.md

Configure Neovim's `nvim-lspconfig` to use the Lipstyk LSP server. This setup specifies the command, root directory detection based on `.lipstyk.toml`, and supported file types for inline diagnostics.

```lua
vim.lsp.start({
  name = 'lipstyk',
  cmd = { 'lipstyk-lsp' },
  root_dir = vim.fs.dirname(vim.fs.find('.lipstyk.toml', { upward = true })[1]),
  filetypes = { 'rust', 'python', 'typescript', 'javascript', 'go', 'html', 'css', 'java', 'sh', 'yaml', 'markdown' },
})

```

--------------------------------

### Lipstyk CI Integration Examples

Source: https://github.com/styrene-lab/lipstyk/blob/main/README.md

Integrate Lipstyk into CI pipelines for code quality checks, PR diff analysis, and SARIF reporting.

```yaml
# gate
- run: lipstyk --exclude-tests --threshold 20 src/
```

```yaml
# diff-only PR check
- run: lipstyk --diff origin/${{ github.base_ref }} --exclude-tests --threshold 15 src/
```

```yaml
# SARIF for inline annotations
- run: lipstyk --sarif --exclude-tests src/ > lipstyk.sarif
  continue-on-error: true
- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: lipstyk.sarif
  continue-on-error: true
```

```yaml
# markdown in job summary
- run: lipstyk --report --exclude-tests src/ >> $GITHUB_STEP_SUMMARY
  continue-on-error: true
```

--------------------------------

### Build Lipstyk LSP Server Binary

Source: https://github.com/styrene-lab/lipstyk/blob/main/INTEGRATION.md

This command builds the Language Server Protocol (LSP) binary for Lipstyk, enabling inline editor diagnostics. Ensure you have the necessary build tools (e.g., Cargo) installed.

```bash
cargo build --release --features lsp

```

--------------------------------

### Use Lipstyk as a Rust Library

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

Integrate Lipstyk into your Rust project to perform code analysis programmatically. This example shows how to configure the linter, analyze source code, and generate a report.

```rust
use lipstyk::{Config, Linter, Report, Severity};
use std::collections::BTreeMap;
use std::time::Instant;

fn main() {
    // Create linter with all default rules
    let config = Config::discover(std::path::Path::new("src/"));
    let linter = Linter::with_defaults()
        .exclude_tests(true)
        .with_config(config);

    // Analyze source code
    let source = r#" 
        fn process_data(s: String) -> Result<(), Box<dyn std::error::Error>> {
            let val = s.parse::<i32>().unwrap();
            println!("value: {}", val);
            Ok(())
        }
    "#;

    let start = Instant::now();
    let score = linter.lint_source("example.rs", source).unwrap();

    println!("File: {}", score.file);
    println!("Score: {:.1}", score.total);
    println!("Findings: {}", score.diagnostics.len());

    for d in &score.diagnostics {
        let sev = match d.severity {
            Severity::Hint => "hint",
            Severity::Warning => "warn",
            Severity::Slop => "SLOP",
        };
        println!("  Line {}: [{}] {} ({})", d.line, sev, d.message, d.rule);
    }

    // Build full report for JSON/SARIF output
    let mut sources = BTreeMap::new();
    sources.insert("example.rs".to_string(), source.to_string());
    let report = Report::build(vec![score], 1, &sources, start.elapsed(), None);

    // Serialize to JSON
    let json = serde_json::to_string_pretty(&report).unwrap();
    println!("{}", json);
}
```

--------------------------------

### lipstyk_rules: List available rules

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

Use `lipstyk_rules` to get a list of all available analysis rules and the languages they support, including the number of rules and file extensions.

```json
{
  "name": "lipstyk_rules",
  "arguments": {}
}
```

--------------------------------

### Configuration File (.lipstyk.toml)

Source: https://github.com/styrene-lab/lipstyk/blob/main/INTEGRATION.md

Details on how to configure Lipstyk using a `.lipstyk.toml` file in the project root.

```APIDOC
## Configuration (`.lipstyk.toml`)

Lipstyk can be configured using a `.lipstyk.toml` file placed in your project's root directory. This configuration is automatically discovered by walking parent directories.

### Global Settings

- **`settings.exclude_tests`** (boolean) - Suppress findings from test code. Default: `false`.
- **`settings.threshold`** (integer) - The CI gate threshold. Findings above this threshold may cause CI to fail. Default: Not specified.

### Rule-Specific Settings

Rules can be enabled, disabled, or have their weights adjusted.

- **`rules.<rule-name>.enabled`** (boolean) - Enable or disable a specific rule entirely. Example: `rules.structural-repetition.enabled = false`.
- **`rules.<rule-name>.weight`** (number) - Adjust the weight of a specific rule. Example: `rules.pub-overuse.weight = 0.5`.

### Example Configuration

```toml
[settings]
exclude_tests = true     # Suppress test-code findings
threshold = 20           # CI gate threshold

[rules.structural-repetition]
enabled = false          # Disable this rule entirely

[rules.pub-overuse]
weight = 0.5             # Reduce this rule's weight

[rules.restating-comment]
enabled = false          # Your team prefers verbose comments
```

Both the CLI and the agent extension respect this configuration file.
```

--------------------------------

### Build lipstyk from Source

Source: https://github.com/styrene-lab/lipstyk/blob/main/README.md

Clone the lipstyk repository and build the release binary manually. The executable is then copied to a local bin directory.

```bash
git clone https://github.com/styrene-lab/lipstyk
cd lipstyk
cargo build --release
cp target/release/lipstyk ~/.local/bin/
```

--------------------------------

### Build Lipstyk with LSP Server Feature

Source: https://github.com/styrene-lab/lipstyk/blob/main/README.md

Build the Lipstyk binary with the LSP server feature enabled for inline diagnostics in editors.

```bash
cargo build --release --features lsp
```

--------------------------------

### Build Lipstyk Agent for MCP Integration

Source: https://github.com/styrene-lab/lipstyk/blob/main/README.md

Build the lipstyk-agent binary with the agent feature enabled for MCP integration.

```bash
cargo build --release --features agent
```

--------------------------------

### LSP Server (inline editor diagnostics)

Source: https://github.com/styrene-lab/lipstyk/blob/main/INTEGRATION.md

Instructions for building and configuring the Lipstyk Language Server Protocol (LSP) server for inline diagnostics in editors.

```APIDOC
## LSP Server (inline editor diagnostics)

Build the Language Server Protocol (LSP) binary for inline diagnostics in editors.

### Build Command

```bash
cargo build --release --features lsp
```

### VS Code Configuration

Add the following to your `.vscode/settings.json` file:

```json
{
  "lsp.lipstyk.command": "lipstyk-lsp",
  "lsp.lipstyk.filetypes": ["rust", "python", "typescript", "javascript", "html", "css", "java"]
}
```

Alternatively, use a generic LSP client extension and point it to the `lipstyk-lsp` executable.

### Neovim (nvim-lspconfig) Configuration

Configure `nvim-lspconfig` with the following Lua snippet:

```lua
vim.lsp.start({
  name = 'lipstyk',
  cmd = { 'lipstyk-lsp' },
  root_dir = vim.fs.dirname(vim.fs.find('.lipstyk.toml', { upward = true })[1]),
  filetypes = { 'rust', 'python', 'typescript', 'javascript', 'go', 'html', 'css', 'java', 'sh', 'yaml', 'markdown' },
})
```
```

--------------------------------

### Configure Neovim for Lipstyk LSP

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

Configure Neovim to use lipstyk-lsp as a language server. This involves specifying the command, root directory, and supported filetypes.

```lua
vim.lsp.start({
  name = 'lipstyk',
  cmd = { 'lipstyk-lsp' },
  root_dir = vim.fs.dirname(vim.fs.find('.lipstyk.toml', { upward = true })[1]),
  filetypes = { 'rust', 'python', 'typescript', 'javascript', 'go', 'html', 'css', 'java', 'sh', 'yaml', 'markdown' },
})
```

--------------------------------

### Configure Lipstyk MCP Server with Debug Logging

Source: https://github.com/styrene-lab/lipstyk/blob/main/INTEGRATION.md

Enable debug logging for the Lipstyk MCP server by setting the LIPSTYK_LOG environment variable in the mcpServers configuration. Diagnostic output will be sent to stderr.

```json
{
  "mcpServers": {
    "lipstyk": {
      "command": "lipstyk-agent",
      "args": ["--mcp"],
      "env": {
        "LIPSTYK_LOG": "lipstyk=debug"
      }
    }
  }
}
```

--------------------------------

### Lipstyk TOML Configuration

Source: https://github.com/styrene-lab/lipstyk/blob/main/README.md

Configure Lipstyk settings, rule weights, and enabled/disabled rules in the .lipstyk.toml file.

```toml
[settings]
exclude_tests = true
threshold = 20

[rules.redundant-clone]
weight = 0.25         # downweight for Axum/actix projects

[rules.structural-repetition]
enabled = false
```

--------------------------------

### MCP Server Configuration for AI Coding Assistants

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

Register lipstyk as an MCP server for AI coding assistants. Configuration files vary based on the editor or IDE.

```json
{
  "mcpServers": {
    "lipstyk": {
      "command": "lipstyk-agent",
      "args": ["--mcp"]
    }
  }
}

```

```json
{
  "mcpServers": {
    "lipstyk": {
      "command": "lipstyk-agent",
      "args": ["--mcp"]
    }
  }
}

```

```json
{
  "mcpServers": {
    "lipstyk": {
      "command": "lipstyk-agent",
      "args": ["--mcp"]
    }
  }
}

```

```json
{
  "mcpServers": {
    "lipstyk": {
      "command": "lipstyk-agent",
      "args": ["--mcp"],
      "env": { "LIPSTYK_LOG": "lipstyk=debug" }
    }
  }
}

```

--------------------------------

### Basic CLI Analysis

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

Run lipstyk on files or directories to analyze code for AI-generated patterns. Use `--exclude-tests` to skip test files and `--diff` to analyze only changed lines.

```bash
# Basic analysis on a directory
lipstyk src/

# Analyze specific files
lipstyk handler.rs utils.ts views.py

# Exclude test code from analysis
lipstyk --exclude-tests src/

# Diff mode - only score changed lines since a git ref
lipstyk --diff main src/
lipstyk --diff HEAD --exclude-tests src/

# Set a score threshold for CI gating (exit 1 if any file exceeds)
lipstyk --threshold 20 --exclude-tests src/

# Combine options
lipstyk --diff origin/main --exclude-tests --threshold 15 src/
```

--------------------------------

### Register Lipstyk Agent as MCP Server

Source: https://github.com/styrene-lab/lipstyk/blob/main/README.md

Configure your editor or IDE to use the lipstyk-agent as an MCP server by providing its command and arguments.

```json
{
  "mcpServers": {
    "lipstyk": {
      "command": "lipstyk-agent",
      "args": ["--mcp"]
    }
  }
}
```

--------------------------------

### Configure Lipstyk as a Language Server

Source: https://github.com/styrene-lab/lipstyk/blob/main/INTEGRATION.md

Add this TOML configuration to enable Lipstyk as a language server for Rust development. The LSP server provides diagnostics on file operations.

```toml
[language-server.lipstyk]
command = "lipstyk-lsp"

[[language]]
name = "rust"
language-servers = ["rust-analyzer", "lipstyk"]
```

--------------------------------

### VS Code LSP Configuration for Lipstyk

Source: https://github.com/styrene-lab/lipstyk/blob/main/INTEGRATION.md

Configure VS Code to use the Lipstyk LSP server by specifying the command and supported file types in `settings.json`. This enables real-time code analysis within the editor.

```json
{
  "lsp.lipstyk.command": "lipstyk-lsp",
  "lsp.lipstyk.filetypes": ["rust", "python", "typescript", "javascript", "html", "css", "java"]
}

```

--------------------------------

### Configure Lipstyk Pre-commit Hook

Source: https://github.com/styrene-lab/lipstyk/blob/main/README.md

Integrate Lipstyk as a pre-commit hook by adding it to your .pre-commit-config.yaml file.

```yaml
repos:
  - repo: https://github.com/styrene-lab/lipstyk
    rev: main
    hooks:
      - id: lipstyk
```

--------------------------------

### lipstyk Output Formats

Source: https://github.com/styrene-lab/lipstyk/blob/main/README.md

Demonstrates different output formats available for lipstyk analysis, including terminal, JSON, SARIF, Markdown, and summary.

```bash
lipstyk src/                          # terminal (default)
```

```bash
lipstyk --json src/                   # full JSON report
```

```bash
lipstyk --sarif src/                  # SARIF 2.1.0 for GitHub code scanning
```

```bash
lipstyk --report src/                 # Markdown for PR comments
```

```bash
lipstyk --summary src/                # one line per file
```

--------------------------------

### GitHub Actions: Upload SARIF for Code Scanning

Source: https://github.com/styrene-lab/lipstyk/blob/main/INTEGRATION.md

This workflow step runs Lipstyk to generate a SARIF file and then uploads it to GitHub for code scanning. `continue-on-error` is necessary because Lipstyk exits with a non-zero status code when findings are present, ensuring the SARIF upload still occurs.

```yaml
- name: Lipstyk analysis
  run: lipstyk --sarif --exclude-tests src/ > lipstyk.sarif
  continue-on-error: true

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: lipstyk.sarif

```

--------------------------------

### GitHub Actions: Basic Lipstyk Quality Gate

Source: https://github.com/styrene-lab/lipstyk/blob/main/INTEGRATION.md

Implement a basic quality gate in GitHub Actions using the standalone Lipstyk CLI. This step runs Lipstyk on the source files and fails the action if the threshold is exceeded.

```yaml
- name: Lipstyk slop check
  run: lipstyk --exclude-tests --threshold 20 src/
```

--------------------------------

### CLAUDE.md Integration for AI Review

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

Instructions for integrating Lipstyk into CLAUDE.md to enable AI assistants to self-review code. This includes commands for checking code quality and common fixes.

```markdown
## Code quality

After modifying code, call the lipstyk_check tool with `path` set
to the file you changed. If verdict is "suspicious" or "sloppy",
fix the highest-severity findings and re-check. Do not commit until
lipstyk_check returns pass: true.

For pre-commit review of all changes, call lipstyk_diff with
`path` set to the project root and `base` set to "HEAD".

Common fixes:
- unwrap-overuse: Replace .unwrap() with ? or match
- generic-naming: Use domain-specific names, not "processData"
- restating-comment: Delete comments that restate the code
- error-swallowing: Handle errors explicitly, don't ignore them
```

--------------------------------

### Generate Markdown Dogfood Report

Source: https://github.com/styrene-lab/lipstyk/blob/main/dogfood-reports/README.md

Use this command to generate a human-readable Markdown report of Lipstyk's self-analysis. Excludes test files and saves the report with a date-stamped filename.

```bash
lipstyk --report --exclude-tests src/ > dogfood-reports/self-$(date +%Y-%m-%d).md
```

--------------------------------

### Configure Lipstyk for CLAUDE.md Integration

Source: https://github.com/styrene-lab/lipstyk/blob/main/INTEGRATION.md

Add instructions to your project's CLAUDE.md file to automatically trigger Lipstyk for self-review after code modifications or for pre-commit checks.

```markdown
## Code quality

After modifying code, call the lipstyk_check tool with `path` set
to the file you changed. If verdict is "suspicious" or "sloppy",
fix the highest-severity findings and re-check. Do not commit until
lipstyk_check returns pass: true.

For pre-commit review of all changes, call lipstyk_diff with
`path` set to the project root and `base` set to "HEAD".
```

--------------------------------

### Configure VS Code for Lipstyk LSP

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

Configure VS Code settings to use lipstyk-lsp. Specify the command and the list of filetypes for which the language server should be active.

```json
{
  "lsp.lipstyk.command": "lipstyk-lsp",
  "lsp.lipstyk.filetypes": ["rust", "python", "typescript", "javascript", "html", "css", "java"]
}
```

--------------------------------

### Configure Lipstyk Pre-commit Hooks

Source: https://github.com/styrene-lab/lipstyk/blob/main/INTEGRATION.md

Integrate Lipstyk into your pre-commit workflow using this YAML configuration. It includes hooks for full scans and diff-based analysis.

```yaml
repos:
  - repo: https://github.com/styrene-lab/lipstyk
    rev: main
    hooks:
      - id: lipstyk           # full scan, threshold 20
      - id: lipstyk-diff      # changed lines only, threshold 15
```

--------------------------------

### SARIF upload (GitHub code scanning)

Source: https://github.com/styrene-lab/lipstyk/blob/main/INTEGRATION.md

This section details how to use Lipstyk to generate a SARIF file and upload it for GitHub code scanning.

```APIDOC
## SARIF upload (GitHub code scanning)

This process involves generating a SARIF file using Lipstyk and then uploading it to GitHub for code scanning.

### Workflow

1. **Lipstyk analysis**: Run `lipstyk --sarif --exclude-tests src/ > lipstyk.sarif` to generate the SARIF file.
   - `continue-on-error: true` is used because Lipstyk returns exit code 1 when findings exist, ensuring the next step runs.
2. **Upload SARIF**: Use the `github/codeql-action/upload-sarif@v3` action to upload the generated `lipstyk.sarif` file.
   - `if: always()` ensures this step executes regardless of previous step failures.

### Purpose

Creates inline annotations on Pull Requests based on the SARIF report. The `continue-on-error` flag is crucial for ensuring the SARIF upload step executes even if Lipstyk detects issues.
```

--------------------------------

### Generate JSON Dogfood Report

Source: https://github.com/styrene-lab/lipstyk/blob/main/dogfood-reports/README.md

Use this command to generate a machine-readable JSON report of Lipstyk's self-analysis. Excludes test files and saves the report with a date-stamped filename. This JSON format is the source of truth for trend tracking.

```bash
lipstyk --json --exclude-tests src/ > dogfood-reports/self-$(date +%Y-%m-%d).json
```

--------------------------------

### Configure Omegon Tool Policy for Lipstyk

Source: https://github.com/styrene-lab/lipstyk/blob/main/INTEGRATION.md

Add Lipstyk tools to your Omegon posture's tool policy to enable automatic approval for read-only analysis.

```toml
[tools.lipstyk_check]
auto_approve = true

[tools.lipstyk_diff]
auto_approve = true
```

--------------------------------

### GitHub Actions CI Pipeline with Lipstyk

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

Configure GitHub Actions to run lipstyk for automated code quality gates. Supports hard gates, diff-only PR checks, SARIF uploads, job summaries, and JSON artifacts.

```yaml
name: Code Quality

on: [push, pull_request]

jobs:
  lipstyk:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Required for diff mode

      - name: Install lipstyk
        run: cargo install --git https://github.com/styrene-lab/lipstyk

      # Option 1: Hard gate - fail if any file exceeds threshold
      - name: Quality gate
        run: lipstyk --exclude-tests --threshold 20 src/

      # Option 2: Diff-only PR check - only score changed lines
      - name: Diff check
        if: github.event_name == 'pull_request'
        run: lipstyk --diff origin/${{ github.base_ref }} --exclude-tests --threshold 15 src/

      # Option 3: SARIF upload for inline PR annotations
      - name: Generate SARIF
        run: lipstyk --sarif --exclude-tests src/ > lipstyk.sarif
        continue-on-error: true

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: lipstyk.sarif
        continue-on-error: true

      # Option 4: Markdown in job summary
      - name: Add to summary
        run: lipstyk --report --exclude-tests src/ >> $GITHUB_STEP_SUMMARY
        continue-on-error: true

      # Option 5: JSON artifact for dashboards
      - name: Generate report
        run: lipstyk --json --exclude-tests src/ > lipstyk-report.json
        continue-on-error: true

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: lipstyk-report
          path: lipstyk-report.json

```

--------------------------------

### lipstyk_check: Analyze file from disk

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

Analyze a specific file using `lipstyk_check` by providing its path. This is useful for single-file reviews.

```json
{
  "name": "lipstyk_check",
  "arguments": {
    "path": "src/handler.rs"
  }
}
```

--------------------------------

### Generate Reports in Different Formats

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

Lipstyk supports generating reports in JSON for dashboards, SARIF for GitHub code scanning, Markdown for PR comments, and a concise summary format.

```bash
# JSON - full structured report for dashboards/metrics
lipstyk --json --exclude-tests src/ > report.json

# SARIF - GitHub code scanning integration
lipstyk --sarif --exclude-tests src/ > lipstyk.sarif

# Markdown - PR comments, GitHub Action summaries
lipstyk --report --exclude-tests src/ >> $GITHUB_STEP_SUMMARY

# Summary - one line per file for quick overview
lipstyk --summary src/
```

--------------------------------

### Configure Helix for Lipstyk LSP

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

Configure Helix editor to use lipstyk-lsp by defining the language server command and associating it with specific languages in languages.toml.

```toml
[language-server.lipstyk]
command = "lipstyk-lsp"

[[language]]
name = "rust"
language-servers = ["rust-analyzer", "lipstyk"]

[[language]]
name = "python"
language-servers = ["pylsp", "lipstyk"]

[[language]]
name = "typescript"
language-servers = ["typescript-language-server", "lipstyk"]
```

--------------------------------

### JSON report for dashboards

Source: https://github.com/styrene-lab/lipstyk/blob/main/INTEGRATION.md

Instructions for generating a JSON report with Lipstyk for use in dashboards and data visualization tools.

```APIDOC
## JSON report for dashboards

This section describes how to generate a JSON report from Lipstyk analysis, suitable for ingestion by dashboarding tools.

### Workflow

1. **Lipstyk report generation**: Execute `lipstyk --json --exclude-tests src/ > lipstyk-report.json` to create the JSON report.
   - `continue-on-error: true` is included to ensure the report is generated even if Lipstyk encounters errors.
2. **Upload artifact**: Use the `actions/upload-artifact@v4` action to upload the `lipstyk-report.json` file as an artifact.
   - `name: lipstyk-report` sets the name of the artifact.
   - `path: lipstyk-report.json` specifies the file to upload.

### Report Content

The JSON report contains detailed information including per-file scores, breakdowns by rule, aggregates by category, Git metadata, and analysis duration, making it ready for use with tools like Grafana or VictoriaMetrics.
```

--------------------------------

### Configure Aider Lint Command with Lipstyk

Source: https://github.com/styrene-lab/lipstyk/blob/main/INTEGRATION.md

Configure Aider to use Lipstyk as a lint command for automatic code quality checks after each edit. Non-zero exit codes from Lipstyk will trigger a fix cycle.

```bash
aider --lint-cmd "lipstyk --exclude-tests --threshold 20"
```

--------------------------------

### Troubleshooting Lipstyk

Source: https://github.com/styrene-lab/lipstyk/blob/main/INTEGRATION.md

Common issues and their solutions when using Lipstyk tools and agents.

```APIDOC
## Troubleshooting

This section addresses common problems encountered when using Lipstyk.

### Tools don't appear in Claude Code / Cursor

- **Verify `$PATH`**: Ensure the `lipstyk-agent` binary is in your system's PATH. Use `which lipstyk-agent` to check.
- **Test manually**: Execute `echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | lipstyk-agent --mcp` to test the agent.
- **Check stderr**: Redirect stderr to a file for debugging: `lipstyk-agent --mcp 2>/tmp/lipstyk-debug.log`.

### MCP server crashes on startup

- **Build with `agent` feature**: Ensure Lipstyk was built with the agent feature enabled: `cargo build --release --features agent`.
- **Correct binary**: The `lipstyk` binary (without `-agent`) is for CLI usage; the agent is a separate binary.

### Agent reports "tool not found"

- **Restart editor/harness**: Restart your editor or agent harness after updating the MCP configuration.
- **Validate `.mcp.json`**: Ensure the `.mcp.json` file contains valid JSON. Trailing commas can cause parsing errors.

### Too many false positives

- **Configuration file**: Use a `.lipstyk.toml` in your project root to tune or disable specific rules.
- **Exclude tests**: Use the `--exclude-tests` flag or set `exclude_tests = true` in the config.
- **Diff analysis**: Use the `--diff` option to analyze only changed lines.

### Debugging agent protocol

- **Set log level**: Set the `LIPSTYK_LOG` environment variable to `lipstyk=debug` in the MCP server's `env` configuration.
- **Stderr for logs**: All diagnostic output is sent to stderr, not stdout, as stdout is used for the protocol channel.
```

--------------------------------

### Add Lipstyk Pre-commit Hooks

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

Integrate Lipstyk into your pre-commit configuration to automatically scan code before commits. Supports full scans and diff-based scans.

```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/styrene-lab/lipstyk
    rev: main
    hooks:
      - id: lipstyk           # Full scan with threshold 20
      - id: lipstyk-diff      # Changed lines only, threshold 15
```

--------------------------------

### lipstyk_check: Analyze entire directory

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

Use `lipstyk_check` to analyze all supported files within a directory. This performs a comprehensive review of the specified path.

```json
{
  "name": "lipstyk_check",
  "arguments": {
    "path": "src/"
  }
}
```

--------------------------------

### lipstyk_rules: Rules Response

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

The response from `lipstyk_rules` details supported languages, the number of rules per language, and associated file extensions, along with the total number of rules.

```json
{
  "languages": {
    "rust": { "rules": 21, "extensions": [".rs"] },
    "typescript": { "rules": 14, "extensions": [".ts", ".tsx", ".js", ".jsx"] },
    "python": { "rules": 15, "extensions": [".py"] },
    "go": { "rules": 8, "extensions": [".go"] },
    "html_css": { "rules": 6, "extensions": [".html", ".htm", ".css", ".vue", ".svelte"] },
    "java": { "rules": 4, "extensions": [".java"] },
    "shell": { "rules": 3, "extensions": [".sh", ".bash", ".zsh"] },
    "dockerfile": { "rules": 1, "extensions": ["Dockerfile", "Containerfile"] },
    "yaml": { "rules": 2, "extensions": [".yml", ".yaml"] },
    "markdown": { "rules": 3, "extensions": [".md", ".mdx"] }
  },
  "total_rules": 77
}
```

--------------------------------

### lipstyk_check API

Source: https://github.com/styrene-lab/lipstyk/blob/main/INTEGRATION.md

Documentation for the `lipstyk_check` tool, used for self-reviewing code with detailed analysis.

```APIDOC
## `lipstyk_check`

Self-review tool that returns a compact, agent-optimized response.

### Method

N/A (CLI Tool)

### Parameters

- **code** (string) - Required - Source code to check. Provide either `code` + `filename` or `path`.
- **filename** (string) - Required - Filename for language detection (e.g. `app.tsx`). Provide either `code` + `filename` or `path`.
- **path** (string) - Required - File or directory to check from disk. Provide either `code` + `filename` or `path`.

### Response (Success)

- **pass** (boolean) - Indicates if the code passed the checks.
- **verdict** (string) - The overall verdict of the analysis (e.g., `clean`, `mild`, `suspicious`, `sloppy`).
- **score** (number) - A numerical score representing the code quality.
- **files_scanned** (integer) - The number of files scanned.
- **files_with_findings** (integer) - The number of files containing findings.
- **total_findings** (integer) - The total number of findings across all scanned files.
- **by_severity** (object) - An object detailing the count of findings by severity level (e.g., `slop`, `warning`, `hint`).
  - **slop** (integer) - Count of 'slop' severity findings.
  - **warning** (integer) - Count of 'warning' severity findings.
  - **hint** (integer) - Count of 'hint' severity findings.
- **categories** (array) - An array of objects, each detailing findings by category.
  - **category** (string) - The name of the category (e.g., `naming`).
  - **count** (integer) - The number of findings in this category.
  - **weight** (number) - The weight assigned to this category.
- **findings** (array) - An array of objects, each describing a specific finding.
  - **file** (string) - The file where the finding occurred.
  - **line** (integer) - The line number of the finding.
  - **rule** (string) - The rule that was violated.
  - **severity** (string) - The severity level of the finding (e.g., `Warning`, `Hint`).
  - **message** (string) - A description of the finding.
  - **fix** (string) - A suggested fix for the finding.

### Verdicts

- `clean` (< 5) — No action needed
- `mild` (< 15) — Acceptable, review hints if you want
- `suspicious` (< 30) — Address warnings before committing
- `sloppy` (≥ 30) — Significant rework needed

### Request Example

```json
{
  "code": "fn process_data(input: Vec<u8>) -> Vec<u8> { input }",
  "filename": "handler.rs"
}
```

### Response Example

```json
{
  "pass": false,
  "verdict": "mild",
  "score": 9.5,
  "files_scanned": 1,
  "files_with_findings": 1,
  "total_findings": 7,
  "by_severity": { "slop": 0, "warning": 6, "hint": 1 },
  "categories": [
    { "category": "naming", "count": 3, "weight": 4.5 }
  ],
  "findings": [
    {
      "file": "handler.rs",
      "line": 1,
      "rule": "generic-naming",
      "severity": "Warning",
      "message": "`fn process_data` — name is too vague",
      "fix": "Rename to describe what this specifically does"
    }
  ]
}
```
```

--------------------------------

### lipstyk_diff API

Source: https://github.com/styrene-lab/lipstyk/blob/main/INTEGRATION.md

Documentation for the `lipstyk_diff` tool, which performs diff-aware code analysis.

```APIDOC
## `lipstyk_diff`

Diff-aware analysis tool. It provides the same response format as `lipstyk_check`.

### Method

N/A (CLI Tool)

### Parameters

- **path** (string) - Required - File or directory to check.
- **base** (string) - Optional - Git ref to diff against. Examples: `HEAD`, `main`, `origin/main`. Defaults to unstaged changes.

### Response

Same response format as `lipstyk_check`.
```

--------------------------------

### lipstyk_check: Analyze inline code

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

Use `lipstyk_check` to analyze a string of code directly. Provide the code and an optional filename for context.

```json
{
  "name": "lipstyk_check",
  "arguments": {
    "code": "fn process_data(s: String) -> Result<(), Box<dyn Error>> {\n    let map = HashMap::new(); // create a new hashmap\n    let val = map.get(\"key\").unwrap();\n    Ok(())
}",
    "filename": "handler.rs"
  }
}
```

--------------------------------

### GitHub Actions: Diff-Only Lipstyk Check for PRs

Source: https://github.com/styrene-lab/lipstyk/blob/main/INTEGRATION.md

Configure a diff-only quality check in GitHub Actions for pull requests. This command uses Lipstyk to score only the lines changed in the PR against a specified base reference, combined with a threshold for a hard gate.

```yaml
- name: Lipstyk diff check
  run: lipstyk --diff origin/${{ github.base_ref }} --exclude-tests --threshold 15 src/
```

--------------------------------

### lipstyk_report: Generate Markdown report

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

Generate a Markdown-formatted report for code analysis results. This is useful for integrating with PR comments or documentation.

```json
{
  "name": "lipstyk_report",
  "arguments": {
    "path": "src/",
    "base": "main"
  }
}
```

--------------------------------

### GitHub Actions: Upload JSON Report for Dashboards

Source: https://github.com/styrene-lab/lipstyk/blob/main/INTEGRATION.md

This workflow generates a JSON report with detailed analysis results and uploads it as an artifact. This report can be consumed by dashboarding tools like Grafana or VictoriaMetrics.

```yaml
- name: Lipstyk report
  run: lipstyk --json --exclude-tests src/ > lipstyk-report.json
  continue-on-error: true

- name: Upload artifact
  uses: actions/upload-artifact@v4
  with:
    name: lipstyk-report
    path: lipstyk-report.json

```

--------------------------------

### JSON Output Structure

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

This is the structure of the JSON report generated by lipstyk, detailing version, timestamp, git information, a summary of findings, and detailed diagnostics per file.

```json
{
  "version": "0.1.0",
  "timestamp": "2024-01-15T10:30:00Z",
  "duration_ms": 42,
  "git": { "branch": "main", "commit": "abc1234", "dirty": false },
  "summary": {
    "files_scanned": 12,
    "files_with_findings": 3,
    "total_score": 42.5,
    "total_diagnostics": 23,
    "by_severity": { "hint": 4, "warning": 17, "slop": 2 },
    "by_rule": { "unwrap-overuse": { "count": 8, "total_weight": 4.0 } },
    "by_category": { "error-handling": { "count": 10, "total_weight": 8.5, "rules": ["unwrap-overuse", "error-swallowing"] } }
  },
  "files": [
    {
      "file": "src/handler.rs",
      "score": 25.5,
      "lines": 150,
      "score_per_100_lines": 17.0,
      "diagnostics": [
        { "rule": "unwrap-overuse", "category": "error-handling", "message": "...", "line": 12, "severity": "Warning", "weight": 0.5 }
      ]
    }
  ]
}
```

--------------------------------

### lipstyk_rules API

Source: https://github.com/styrene-lab/lipstyk/blob/main/INTEGRATION.md

Information about the `lipstyk_rules` tool, which provides metadata on supported languages and rule counts.

```APIDOC
## `lipstyk_rules`

Returns metadata about supported languages and rule counts.

### Method

N/A (CLI Tool)

### Parameters

None

### Response

(Response format not specified in the provided text, but it is expected to contain information about supported languages and rule counts.)
```

--------------------------------

### lipstyk_diff: Check changes since HEAD

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

Analyze code changes in a path relative to the latest commit (HEAD). This is useful for reviewing uncommitted work.

```json
{
  "name": "lipstyk_diff",
  "arguments": {
    "path": "src/",
    "base": "HEAD"
  }
}
```

--------------------------------

### lipstyk_check: Analysis Response

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

The response from `lipstyk_check` includes a pass/fail verdict, score, and detailed findings with severity and suggested fixes.

```json
{
  "pass": false,
  "verdict": "suspicious",
  "score": 18.5,
  "files_scanned": 1,
  "files_with_findings": 1,
  "total_findings": 5,
  "by_severity": { "slop": 0, "warning": 4, "hint": 1 },
  "categories": [
    { "category": "error-handling", "count": 2, "weight": 5.0 },
    { "category": "naming", "count": 1, "weight": 1.5 },
    { "category": "documentation", "count": 1, "weight": 1.5 }
  ],
  "findings": [
    {
      "file": "handler.rs",
      "line": 1,
      "rule": "boxed-error",
      "severity": "Warning",
      "message": "Returns Box<dyn Error> — consider a domain error type",
      "fix": "Define a domain error enum with thiserror and use it instead of Box<dyn Error>"
    },
    {
      "file": "handler.rs",
      "line": 1,
      "rule": "generic-naming",
      "severity": "Warning",
      "message": "`fn process_data` — name is too vague to convey intent",
      "fix": "Rename to describe what this specifically does in your domain, not what kind of operation it is"
    },
    {
      "file": "handler.rs",
      "line": 1,
      "rule": "string-params",
      "severity": "Warning",
      "message": "`fn process_data` takes owned String — would &str work here?",
      "fix": "Change the parameter from String to &str — the caller can pass &s or &string"
    },
    {
      "file": "handler.rs",
      "line": 2,
      "rule": "restating-comment",
      "severity": "Warning",
      "message": "Comment restates the code: `create a new hashmap`",
      "fix": "Delete the comment — it says what the code already says. Keep only comments that explain why."
    },
    {
      "file": "handler.rs",
      "line": 3,
      "rule": "unwrap-overuse",
      "severity": "Hint",
      "message": "`.unwrap()` — consider propagating with `?`",
      "fix": "Replace .unwrap() with ? operator or handle the error with match/if let"
    }
  ]
}
```

--------------------------------

### lipstyk_diff: Check changes since a branch

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

Analyze code changes in a path compared to a specified git branch, such as `origin/main`. This helps in reviewing changes intended for merging.

```json
{
  "name": "lipstyk_diff",
  "arguments": {
    "path": ".",
    "base": "origin/main"
  }
}
```

--------------------------------

### lipstyk_report: Report Response

Source: https://context7.com/styrene-lab/lipstyk/llms.txt

The response from `lipstyk_report` contains the generated Markdown content, a summary, score, and verdict.

```json
{
  "markdown": "## Lipstyk Analysis\n\n**Verdict:** suspicious (18.5)\n...",
  "summary": "3/12 files, score 18.5 (suspicious)",
  "score": 18.5,
  "verdict": "suspicious",
  "pass": false
}
```
Tokens:
Raw