sktr 1.0.0

Language-agnostic software intelligence and architecture review CLI

SKTR

System Knowledge & Technical Review

Understand your software before you change it.

Stable release: 1.0.0 is the first stable SKTR interface and artifact contract. Please report reproducible feedback through the issue tracker.

SKTR is a language-agnostic software intelligence CLI. It turns Git changes into a structured knowledge model, enriches that model with deterministic engineering metrics, applies architecture rules, and produces review artifacts for people and automation. Optional AI features explain the evidence; they do not replace it.

What is SKTR?

Run sktr review inside a configured Git repository to answer practical review questions:

• Which modules and public symbols changed?
• Did this change introduce new internal dependencies or dependency cycles?
• Which files and functions deserve attention first?
• Does the change violate a configured architecture boundary?
• What structured artifact can CI, reports, and future tooling consume?

The core is language-agnostic. Python, JavaScript/TypeScript, and Java analyzers, rule packs, outputs, and AI providers are discovered as plugins through Python entry points.

Why SKTR?

Code review tools often begin with raw source and ask a model to discover what matters. SKTR begins with deterministic facts. Git scope, symbols, dependencies, metrics, rules, risk, and review priority are computed first. AI features receive that structured context instead of the whole repository.

SKTR remains useful with AI disabled, produces stable output, and stores the result as a versioned JSON artifact rather than only printing prose.

Features

• Working-tree, branch, explicit-base, and commit review scopes
• Python analysis using the standard ast module
• JavaScript, JSX, TypeScript, TSX, and Java analysis using Tree-sitter
• Deterministic architecture and maintainability rules
• Configurable forbidden module dependencies and thresholds
• Knowledge enrichment with file, symbol, dependency, module, risk, and priority metrics
• Terminal, Markdown, JSON, and Mermaid output
• Plugin discovery and diagnostics
• CI severity gates, path exclusions, and parse diagnostics
• Optional OpenAI- or Anthropic Claude-powered explanations and recommendations

Quickstart

SKTR requires Python 3.11 or newer and a Git repository:

python -m pip install sktr==1.0.0
sktr --version
sktr --help
cd your-project
sktr init --yes
sktr review

Common next steps:

sktr review --ai
sktr review --ai --model gpt-5.6-terra
sktr review --format markdown --output REVIEW.md
sktr review --format json --output sktr-review.json
sktr graph --format mermaid --output architecture.mmd
sktr graph --scope repository --focus orders

See the quickstart for review scopes and a complete first run. See architecture graphs for repository and focused views. See analyzer semantics for visibility, modules, and metrics. See the CLI reference for every command and exit status.

Example output

SKTR Review

Summary
Risk: Medium
Score: 76/100
Changed files: 3
Issues: 2

Findings
High
! Forbidden dependency
  controllers/order_controller.py imports repositories/order_repository.py
  Reason: Controllers should access repositories through services.

Medium
! Large function detected
  create_order has 114 lines.

AI Review
Overview
The change crosses the controller-to-repository boundary and concentrates new
order behavior in one large function.

AI output appears only when enabled. Deterministic findings and scoring are the same with or without AI.

Configuration

sktr init creates sktr.yml. Use interactive setup to choose plugins, rules, outputs, and optional AI features, or use sktr init --yes for safe defaults.

project:
  name: sample-app
  default_base: main
review:
  default_scope: working_tree
  fail_on: null
  exclude:
    - node_modules/
    - .venv/
    - dist/
    - build/
    - target/
plugins:
  analyzers:
    - sktr-python
    - sktr-javascript-typescript
    - sktr-java
  rules:
    - sktr-rules-default
  outputs:
    - terminal
    - markdown
    - json
    - mermaid
rules:
  enabled:
    - new_dependency
    - large_file
    - large_function
    - forbidden_dependency
  large_file:
    max_changed_lines: 300
  large_function:
    max_lines: 80
  forbidden_dependencies:
    - source: controllers
      target: repositories
      reason: Controllers should access repositories through services.
ai:
  enabled: false

API keys never belong in this file. See the complete configuration reference.

Risk score

The score starts at 100. Deterministic findings subtract severity-weighted penalties, with caps for repeated findings and categories. A separate bounded review-breadth penalty accounts for production files, changed modules, public API changes, and unusually large diffs. Documentation and test files are reported but do not count as production files. Informational findings do not lower the score.

• Low: 85-100
• Medium: 65-84
• High: 40-64
• Critical: 0-39

AI features

AI is optional. SKTR can ask a configured provider to explain deterministic findings and recommend focused next steps using structured SKTR context.

export SKTR_OPENAI_API_KEY="your-api-key"
sktr ai doctor
sktr review --ai

OpenAI key resolution is SKTR_OPENAI_API_KEY first, then OPENAI_API_KEY. Claude is also supported:

export ANTHROPIC_API_KEY="your-api-key"
sktr ai doctor
sktr review --ai

Configure Claude in sktr.yml:

ai:
  enabled: true
  provider: anthropic
  model: claude-sonnet-5

Anthropic key resolution is SKTR_ANTHROPIC_API_KEY first, then ANTHROPIC_API_KEY. The SKTR-specific variable is useful when you want a separate key for SKTR. SKTR never stores or prints provider keys. See AI setup.

Plugins

SKTR discovers analyzers, rule packs, outputs, and AI providers from these entry point groups:

• sktr.analyzers
• sktr.rules
• sktr.outputs
• sktr.ai_providers

sktr plugins list
sktr plugins doctor

See the plugin guide to build or distribute a plugin.

Roadmap

SKTR 1.0 packages the deterministic review, three bundled analyzers, stable JSON artifact, architecture graphing, CI gates, and optional AI Review developed through v0.20. Post-v1 work remains tracked in the canonical roadmap.

The v0.16-v0.18 roadmap delivered bundled JavaScript/TypeScript and Java analyzers, followed by CI severity gates, exclusions, parse diagnostics, and a frozen artifact schema. v0.19 added repository-context graphs, and v0.20 added evidence-based API exposure, logical application modules, alias resolution, and more precise React and Java signals. See the canonical roadmap for milestone deliverables and deferred post-v1 work.

Contributing

Development uses uv:

uv sync
uv run pytest
uv run sktr review

Read CONTRIBUTING.md and development.md before adding an analyzer, rule, output, or provider. Release work is tracked in the v1.0.0 checklist.

For help, see troubleshooting and the known limitations. Report sensitive vulnerabilities privately according to SECURITY.md. Release history is recorded in the changelog.

License

SKTR is available under the MIT License.