KnockGuard

KnockGuard is a local CLI tool for Java/Spring Boot backend developers. Its goal is to analyze one local Git diff and produce a reviewable risk report and execution trace.

Current stage: P5 optional LLM risk analysis.

The CLI can collect git diff <base>...HEAD, save .knockguard/runs/<run_id>/diff.patch, classify changed files by backend layer, expand lightweight text context, optionally call an OpenAI-compatible LLM for structured risk analysis, generate report.md, and write trace.json.

Usage

After installing the project in editable mode:

python -m pip install -e .
knockguard --help
knockguard analyze --help

Without installation:

python -m knockguard --help
python -m knockguard analyze --help

Desktop Workbench

KnockGuard keeps the Python runtime as the primary analysis engine and wraps it with a small Tauri desktop client under apps/workbench.

Install the workbench dependencies once:

npm --prefix apps/workbench install

Then start the desktop client:

knockguard gui

For frontend-only inspection, apps/workbench/index.html can still be opened directly, but the intended local client is the Tauri window. The legacy browser bridge is available only as an explicit fallback:

knockguard gui --browser-bridge

LLM Configuration

Copy the safe template when you want project-level defaults:

cp .knockguard.yaml.example .knockguard.yaml

.knockguard.yaml is intentionally ignored by Git. Do not commit real OpenAI-compatible base URLs, model codes, or API keys.

Configure default OpenAI-compatible LLM settings step by step:

knockguard config init

Or set them non-interactively:

knockguard config set \
  --llm-base-url http://localhost:11434/v1 \
  --llm-model your-model-code \
  --llm-api-key your-api-key \
  --llm-timeout 60

You can also keep the key in an environment variable:

knockguard config set \
  --llm-base-url http://localhost:11434/v1 \
  --llm-model your-model-code \
  --llm-api-key-env OPENAI_API_KEY

Then run without repeating LLM flags:

knockguard analyze --repo ./demo-project --base main

Useful config commands:

knockguard config test-llm
knockguard config show
knockguard config path
knockguard config clear

KnockGuard can store the API key value in the local config file for convenience. config show masks the key value, and analyze-time CLI flags still override saved config. During analyze, progress is printed to stderr and a short LLM risk preview is printed in the final CLI summary. Full LLM analysis is written to report.md and trace.json.