Sokrates
Polyglot source code examination tool

"Talk is expensive. Show me the code."

Željko Obrenović

What is Sokrates?

  • Sokrates is a tool built by Željko Obrenović. It implements his vision on how to document and analyze software architectures of complex systems.
  • Sokrates is provides a pragmatic, inexpensive way to extract rich data from any source code repositories. No need for long interviews and workshops. Just show the code.
  • Sokrates can help you to understand your code by making visible the size, complexity, and coupling of software, as well all people interactions and team topologies.
  • Sokrates is one of several open-source tools we use when implementing Grounded Architecture Lightweight Architectural Analytics
  • Sokrates borrows ideas from code spelunking tool, in particular grep, adding structure on top of regex source code searches.

Sokrates in 5 minutes

See a 5 minutes video on using Sokrates CLI to analyze source code of Sokrates:

See a 5 minutes video on using Sokrates Explorer to analyze source code of JUnit4:

Background

PRE-REQUIREMENTS

  • Java runtime
  • Optional set the SOKRATES_ANALYSIS_DATE system variable (in the YYYY-MM-dd format) to define the reference date for commit history analyses. By default, Sokrates uses the current date to calculate the number of commits and contributors in different periods relative to the reference date (e.g. past 30 days, past 90 days, past year).
  • If you want to run Sokrates in a Docker container, see Sokrates Dockerfile

COMMAND LINE INTERFACE (CLI) JAR

DOWNLOAD: sokrates-LATEST.jar (40 MB)
CURL:
curl https://d2bb1mtyn3kglb.cloudfront.net/builds/sokrates-LATEST.jar --output sokrates-LATEST.jar

Command Line Usage:

Usage: java -jar sokrates.jar <command> <options>

Help: java -jar sokrates.jar <command> -help

Commands: init, generateReports, updateLandscape, updateConfig, extractGitHistory, createConventionsFile, exportStandardConventions, extractGitSubHistory

* init: Creates a new Sokrates analysis configuration file based on standard and optional custom conventions
   - options: [-srcRoot <arg>] [-confFile <arg>] [-conventionsFile <arg>] [-name <arg>] [-description <arg>] [-logoLink <arg>] [-addLink <arg>] [-timeout <arg>] [-help]

* generateReports: Generates Sokrates reports based on the analysis configuration
   - options: [-confFile <arg>] [-outputFolder <arg>] [-timeout <arg>] [-date <arg>] [-help]

* updateLandscape: Updates or creates a Sokrates landscape report, aggregating results of multiple analyses
   - options: [-analysisRoot <arg>] [-confFile <arg>] [-recursive] [-setName <arg>] [-setDescription <arg>] [-setLogoLink <arg>] [-addLink <arg>] [-timeout <arg>] [-date <arg>] [-help]

* updateConfig: Updates an analysis configuration file and completes missing fields
   - options: [-confFile <arg>] [-skipComplexAnalyses] [-setCacheFiles <arg>] [-setName <arg>] [-setDescription <arg>] [-setLogoLink <arg>] [-addLink <arg>] [-timeout <arg>] [-help]

* extractGitHistory: Extract a git history in a format used by Sokrates and saves it in the git-history.txt file
   - options: [-analysisRoot <arg>] [-help]

* createConventionsFile: Create a new analysis conventions file and saves it in <current-folder>/analysis_conventions.json

* exportStandardConventions: Export standard Sokrates analysis convention to <current-folder>/standard_analysis_conventions.json.

* extractGitSubHistory: A utility function to split a git history file (git-history.txt) into smaller ones based on a commit file path prefix, removing the prefix from file path in split files
   - options: [-prefix <arg>] [-analysisRoot <arg>] [-help]
CLI Usage Example 1. Analyze a single projects (Junit4):
    git clone https://github.com/junit-team/junit4
    cd junit4

    java -jar <sokrates-folder>/sokrates-LATEST.jar extractGitHistory
    java -jar <sokrates-folder>/sokrates-LATEST.jar init
    java -jar <sokrates-folder>/sokrates-LATEST.jar generateReports

    open _sokrates/reports/html/index.html
  
CLI Usage Example 2. Analyze multiple projects and create a landscape page that summarizes data from these two analyses:
    git clone https://github.com/junit-team/junit4
    cd junit4
    java -jar <sokrates-folder>/sokrates-LATEST.jar extractGitHistory
    java -jar <sokrates-folder>/sokrates-LATEST.jar init
    java -jar <sokrates-folder>/sokrates-LATEST.jar generateReports

    cd ..

    git clone https://github.com/junit-team/junit5
    cd junit5
    java -jar <sokrates-folder>/sokrates-LATEST.jar extractGitHistory
    java -jar <sokrates-folder>/sokrates-LATEST.jar init
    java -jar <sokrates-folder>/sokrates-LATEST.jar generateReports

    cd ..

    mkdir landscape
    mv junit4/_sokrates landscape/junit4
    mv junit5/_sokrates landscape/junit5

    rm -rf junit4
    rm -rf junit5

    cd landscape
    java -jar <sokrates-folder>/sokrates-LATEST.jar updateLandscape

    open _sokrates_landscape/index.html
  
CLI Usage Example 3. Analyzing a project using custom configurations:
    git clone https://github.com/junit-team/junit5
    cd junit5
    java -jar <sokrates-folder>/sokrates-LATEST.jar extractGitHistory
    java -jar <sokrates-folder>/sokrates-LATEST.jar createConventionsFile
    # edit the 'analysis_conventions.json' file to define your custom conventions
    java -jar <sokrates-folder>/sokrates-LATEST.jar init -conventionsFile analysis_conventions.json
    java -jar <sokrates-folder>/sokrates-LATEST.jar generateReports
  

BIG SCALE ANALYSES

BIG SCALE ANALYSES ON AWS

BIG SCALE ANALYSES

VISUAL EXPLORER

DOWNLOAD: sokrates-explorer-LATEST.jar (78 MB)

NOTE: require JavaFX (download it and install it from openjfx.io)

   java --module-path $JAVAFX_HOME/lib --add-modules=javafx.controls,javafx.web -jar sokrates-explorer-LATEST.jar
  

AI INSIGHTS — SKILLS FOR AI CODING TOOLS

Sokrates measures: size, complexity, duplication, churn, coupling, contributors. The sokrates-skills project adds the layer only an AI reader can add — what the code is, what it depends on, where the real risks are, how it got here — and makes Sokrates itself more useful by configuring it well. The skills work with Claude Code and similar AI coding tools that can load SKILL.md instructions.

Analysis skills (scanners)

Read a finished Sokrates analysis (_sokrates/) and write findings with verifiable evidence. Each scanner answers one question:

  • functionality-scan — what the software does: purpose, features, entry points, workflows, data, integrations, hidden functionality, documentation-vs-code gaps
  • domain-language-scan — the domain language: glossary, bounded contexts, concepts per capability, language drift
  • architecture-scan — the implemented architecture: style, components, boundaries, violations, communication, migrations, and the security boundaries as structure (trust map, sandboxing, escape hatches)
  • tech-stack-scan — languages, frameworks, libraries, build tooling, CI/CD, infrastructure, external services
  • cicd-scan — the CI/CD process as a narrative: triggers, build, tests, gates, release, deployment, hygiene
  • testing-scan — the tests as a system: layers as implemented, coverage map inferred from what tests reference, assertion/mocking/determinism quality, flakiness and skips, infrastructure, gaps on load-bearing paths
  • observability-scan — logging, metrics, tracing, error reporting, health surfaces, blind spots
  • reliability-scan — how the code behaves when things go wrong: error model, failure handling on load-bearing paths, isolation and blast radius, retries and timeouts, degradation, resource cleanup and shutdown
  • performance-scan — static performance review: workload model and scaling factors, hot-path algorithms and data structures, I/O and memory, parallelism, caching, cost limits, ranked bottlenecks
  • storage-scan — persistent data: data classes and where they live, access patterns, schema and format versioning, integrity and corruption recovery, retention and cleanup
  • network-scan — connectivity: endpoint topology, protocols as used, timeouts, TLS and proxies, endpoint configurability, offline behaviour, data in transit
  • security-scan — security review, design first and code second: identity and permission design, secrets by design and in the tree, boundary validation, injection, crypto, unsafe code, third-party and model-output trust, with a coverage statement
  • risk-synthesis-scan — Sokrates hotspots explained: what each risky file does, knowledge risk, change coupling
  • evolution-scan — the history as a story: eras, growth, focus shift, people, module lifecycle, trajectory
  • full-scan — runs all of them in dependency order and merges the results

Configuration skills

Create and tune Sokrates configuration before an analysis. Each comes with a checker that simulates Sokrates' own rules on the real tree, so a configuration is verified before Sokrates runs:

  • sokrates-repo-config_sokrates/config.json: scope, file classification, thresholds, history settings
  • sokrates-decompositions — meaningful components: folder depth, build modules, mixed depth for monorepos, ownership, layers
  • sokrates-features-of-interest — concerns worth tracking: debt markers, security-sensitive code, feature flags, domain vocabulary
  • sokrates-landscape-config_sokrates_landscape/ files: discovery, filters, tags, teams
  • sokrates-people-config — contributor identity merging from git history, with a review file for the human decisions
  • sokrates-virtual-landscapes — sub-landscapes from your grouping or from naming conventions, technology, activity, teams

The field references were read from the Sokrates Java source — including the places where documentation and code disagree.

HOW TO USE

1. Install the skills

Every skill is a folder with a SKILL.md in the open Agent Skills format, so the same folders work in any AI coding tool that supports skills. The repository's install.sh symlinks all of them into the right places; git pull then updates every tool at once.

git clone https://github.com/zeljkoobrenovic/sokrates-skills.git
cd sokrates-skills
./install.sh            # → ~/.claude/skills (Claude Code) and ~/.agents/skills (Codex, Gemini CLI, Cursor, Copilot, …)
./install.sh --project  # → ./.claude/skills and ./.agents/skills of the current project instead (shareable via git)
ToolReads skills fromInvoke
Claude Code~/.claude/skills/ (personal), .claude/skills/ (project)automatically when relevant, or /tech-stack-scan
OpenAI Codex CLI~/.agents/skills/ (personal), .agents/skills/ (repository)automatically, or $tech-stack-scan
Gemini CLI~/.gemini/skills/ or ~/.agents/skills/ (user), .gemini/skills/ or .agents/skills/ (workspace); or gemini skills install https://github.com/zeljkoobrenovic/sokrates-skills.gitactivates a matching skill after a confirmation; gemini skills list --all
Cursor~/.cursor/skills/ or ~/.agents/skills/ (user), .cursor/skills/ or .agents/skills/ (project); .claude/skills/ is read too/ in Agent chat, or automatically
GitHub Copilot
(CLI, VS Code, coding agent)
~/.copilot/skills/ or ~/.agents/skills/ (personal), .github/skills/, .agents/skills/ or .claude/skills/ (repository)automatically; gh skill installs from repositories
Other toolsany Agent-Skills folder: ./install.sh <folder>, or copy the skill folderssee the tool's documentation

Requirements: Python 3.9+ (standard library only) for the scripts, and a Sokrates analysis of your project.

2. Analyze the project with Sokrates

cd <your-project>
java -jar sokrates.jar init
java -jar sokrates.jar extractGitHistory      # optional, enables history-based insights
java -jar sokrates.jar generateReports

3. Refine the configuration with the config skills

The default init configuration is a starting point. In the project folder, ask your AI tool to improve it — each configuration skill previews the effect on the real tree before Sokrates runs:

  • "check the Sokrates configuration of this repository" — scope, ignored and misclassified files, thresholds (sokrates-repo-config)
  • "define meaningful components for this repository" — modules, mixed depth for monorepos, ownership, layers (sokrates-decompositions)
  • "which features of interest should Sokrates track here?" — debt markers, security-sensitive code, feature flags, domain vocabulary (sokrates-features-of-interest)
  • "merge duplicate contributors" — identity merging with a review file (sokrates-people-config)

Then regenerate the reports so the analysis reflects the refined configuration:

java -jar sokrates.jar generateReports

4. Ask for insights

In the project folder, ask your AI tool: "run a tech stack scan", "explain the risks in this codebase", "what does this software do?", "how did this codebase evolve?", or "run a full scan" for all fourteen scanners. Every scanner reads the Sokrates data first and spends its reading budget where the numbers point.

5. Open the AI Insights Explorer

Results land in <your-project>/_sokrates/findings/ai-insights/: one JSON file per scanner and index.html — a self-contained interactive page with an overview, a page per scanner, a cross-scanner list of attention items, severity and confidence filters, full-text search, and every finding's evidence as file, line range and verbatim snippet.

6. Illustrate the summaries (optional)

export GEMINI_API_KEY=...
python3 skills/illustrators/generate_summary_visuals.py <your-project>/_sokrates/findings/ai-insights

The illustrator script (in the skills/illustrators/ folder of the repository) turns each scanner's summary into one calm, mostly visual illustration that tells its story with a few key words — a pipeline for CI/CD, a landscape with glowing hotspots for risks, growth rings for evolution. It uses Google's Gemini image model ("Nano Banana"), saves the images next to the findings (ai-insights/visuals/), records them in the findings JSON and re-renders the explorer, which shows each image at the end of the foldable summary block. Existing images are kept on re-runs; --force regenerates them. Skip this step and the explorer looks exactly as before.

7. Embed the explorer in the Sokrates report

cd <your-project>
java -jar sokrates.jar addCustomTab -label "AI Insights*" -iframeLink "../../findings/ai-insights/index.html"

This registers an AI Insights* tab in the configuration of the main Sokrates HTML report (_sokrates/reports/html/index.html) that shows the explorer inline, so the quantitative reports and the AI findings live in one place.

8. Regenerate the reports to see the new tab

java -jar sokrates.jar generateReports

The tab is part of the generated report from now on; it picks up the explorer's regenerated index.html automatically whenever you re-run the scanners.

Why the findings can be trusted

  • Every finding carries evidence: file, line range, verbatim snippet.
  • A validator mechanically checks each snippet against the actual file — a scan is not finished until validation passes. This is the guard against hallucinated findings.
  • Findings have a severity (info → critical) and a confidence (certain / likely / possible); claims without evidence must say so.
  • Finding ids are stable across runs, so two scans of the same project can be diffed: new, resolved, persisting.
  • Scanners cite Sokrates data (component:, metric: references) instead of re-measuring it.

Landscapes and many repositories

  • The configuration skills also cover landscapes: repository discovery, filters and thresholds, tags, teams, contributor identity merging across repositories, and virtual sub-landscapes.
  • Each has a checker that previews exactly what Sokrates will do — which repositories are found, which tags match, how contributors map to people and teams — before updateLandscape runs.
  • Typical order for a portfolio: repository config → decompositions → features of interest → generateReports → landscape config → people config → virtual landscapes → updateLandscape → scanners per repository.

EXTENDING

All scanners share one contract (sokrates-scan-core): the findings format, the evidence rules, the validator and the explorer renderer. A new scanner is a SKILL.md that defines its question and its group taxonomy; the proven way to build one is to run it live on a real codebase with a fresh agent, ask that agent what was unclear, and fold the answers back into the skill. See the development notes.

Configuration File for Project Analyses

Configuration File for a Landscape Analysis

Configuring the Analysis Initialization

  • The init command creates a configuration file for project analyses. Without any parameters, this command uses the standard conventions to generate a project analysis configuration.
  • You can also use your own custom conventions to initialize projects and create new configuration files:
    •     java -jar <sokrates-folder>/sokrates-LATEST.jar createConventionsFile
          # edit the 'analysis_conventions.json' file to define your custom conventions
          java -jar <sokrates-folder>/sokrates-LATEST.jar init -conventionsFile analysis_conventions.json
    • See example of a custom conventions file

Examples: Sokrates Analyses of Individual Repositories

OpenAI
Codex
Anthropics
Official Claude Plugins
NOTE: If you want to perform similar landscape analyses of all repositories in a GitHub organization, take a look at this project github.com/zeljkoobrenovic/sokrates-oss-landscape-analysis and Dockerized AWS version github.com/zeljkoobrenovic/sokrates-oss-landscape-analysis-aws.

Recent Sokrates Analyses of Big Projects and Whole GitHub Organizations

NOTE: Analysis is limited to repositories with commits in past year or two.

Older Examples

Source Code Overview

  • For analysis purposes Sokrates separate files in scope into several categories: main, test, generated, deployment and build, and other.
  • The main category contains all manually created source code files that are being used in the production.
  • Files in the main category are used as input for other analyses: logical decomposition, concerns, duplication, file size, unit size, and cyclomatic complexity.
  • Test source code files are used only for testing of the product. These files are normally not deployed to production.
  • Build and deployment source code files are used to configure or support build and deployment process.
  • Generated source code files are automatically generated files that have not been manually changed after generation.
  • While a source code folder may contain a number of files, Sokrates is primarily interested in the source code files that are being written and maintained by developers.
  • Files containing binaries, documentation, or third-party libraries, for instance, are excluded from analysis. The exception are third-party libraries that have been changed by developers.

Duplication

  • For duplication, Sokrates look at places in code where there are six or more lines of code that are exactly the same.
  • Before duplication is calculated, the code is cleaned to remove empty lines, comments, and frequently duplicated constructs such as imports.

Logical Decomposition: Components and Dependencies

Logical decomposition is a representation of the organization of the main source code, where every and each file is put in exactly one logical component.

  • A software system can have one or more logical decompositions.
  • A logical decomposition can be defined in two ways.
  • First approach is based on the folders structure. Components are mapped to folders at defined folder depth relative to the source code root.
  • Second approach is based on explicit definition of each component. In such explicit definitions, components are explicitly named and their files are selected based on explicitly defined path and content filters.
  • A logical decomposition is considered invalid if a file is selected into two or more components.This constraint is introduced in order to facilitate measuring of dependencies among components.
  • Files not assigned to any component are put into a special "Unclassified" component.

Features of Interest

  • Features of interests are cross-curring concerns of a software system that can be identified thourgh patterns in code.
  • A single fetaure of interest may be present in multiple files. One source code file may contain multiple concerns.

File Size

  • File size measurements show the distribution of size of files.
  • Files are classified in four categories based on their size (lines of code): 1-200 (small files), 200-500 (medium size files), 501-1000 (long files), 1001+ (very long files).

Unit Size

  • Unit size measurements show the distribution of size of units of code (methods, functions...).
  • Units are classified in four categories based on their size (lines of code): 1-20 (small units), 20-50 (medium size units), 51-100 (long units), 101+ (very long units).

Conditional Complexity

  • Conditional complexity (also known as cyclomatic complexity) is a software metric (measurement), used to indicate the complexity of a program. It is a quantitative measure of the number of linearly independent paths through a program's source code.
  • Conditional complexity is measured at the unit level (methods, functions...).
  • Units are classified in four categories based on the measured McCabe index: 1-5 (simple units), 6-10 (medium complex units), 11-25 (complex units), 26+ (very complex units).

File Age

  • File age measurements show the distribution of file ages (days since the first commit) and the recency of file updates (days since the latest commit).

File Churn

  • File change frequency (churn) measurements show the distribution of the number of file updates (days with at least one commit).

Temporal Dependencies

  • A temporal dependency occurs when a developer changes two or more files at the same time (in the same commit).

Detailed Metrics

  • A list of all measurements.

Goals & Controls

  • A semaphore-like controls, to get warnings based on the range or metric values.

Supported Languages

Any textual file can be analyzed in Sokrates with standard analyses (empty lines cleaning, source code overview, duplication, file size, file age, file change frequency, temporal dependencies, committers & contributions, features of interest, findings, metrics, controls).

For several popular languages Sokrates provides more in-depth analyses:

Language Units Analysis Dependencies Extensions
Abap X - .abap
AdabasNatural X - .nsd .nsh .nsn .nsm .nsp
CSharp X X .cs .csx .cake
CStyle X - .c .idc .cats
Cfg - - .cfg
ClojureLang - - .cljscm .wisp .cl2 .hl .clj .rg .boot .cljc .cljx .cljs .hic .edn
Cpp X X .ipp .cc .h .hpp .cp .m .hh .c++ .hxx .tpp .mm .cpp .re .cxx .dart .h++ .tcc .inl .ino
Css - - .css
D X - .d .di
Dbc - - .dbc
GoLang X X .v .go
Gradle X X .gradle
Groovy X X .grt .gvy .groovy .gtpl
Hack X - .hack
Html X X .ascx .jsx .haml .mustache .htm .ashx .razor .erb .asmx .vue .aspx .soy .mtml .njk .deface .phtml .st .asp .jinja .handlebars .vbhtml .jinja2 .hbs .xhtml .axd .rtml .hhi .cshtml .xht .ecr .html .asax .eex
Java X X .ck .j .java .uc
JavaScript X - .jsb .jsm .cy .pac .es .xsjslib .jake .gs .cjs .sjs .js .es6 .xsjs .frag ._js .njs .ssjs .bones .jscad .jsfl
Json - - .sublime-mousemap .sublime-theme .sublime-menu .webmanifest .json .tfstate.backup .geojson .sublime-commands .yyp .avsc .sublime_session .tfstate .sublime-workspace .gltf .sublime_metrics .json5 .sublime-macro .sublime-project .jsonc .webapp .ice .jsonl .har .topojson .jsonld .yy .mcmeta .sublime-completions .sublime-settings .sublime-build .jsoniq .sublime-keymap .JSON-tmLanguage
Jsp - - .jsp .gsp
Julia X - .jl
Kotlin X X .ktm .kts .kt
Less - - .less
Lua X - .wlua .rbxs .rockspec .p8 .nse .pd_lua .lua
ObjectPascal X - .dfm .p .pas .dpr .pascal .lpr
Perl X X .al .t .ph .pl .plx .pm .psgi .perl
Php X X .aw .php .php4 .php5 .php3 .phpt .phps .ctp .inc
PlSql X X .plsql .pck .pkb .pks .plb .pls
Puppet - - .pp
Python X X .numpyw .pyde .xpy .wsgi .eb .gn .smk .gyp .rpy .pytb .py .numsc .numpy .gypi .lmi .py3 .pxd .pxi .pyi .pyp .pyt .pyx .pyw .tac
R X - .rda .r .rds .rdata .rd .rsx
Ruby - X .rbi .rbw .rbx .podspec .god .gemspec .rbuild .watchr .ruby .rb .eye .ru .builder .rabl .jbuilder .thor .mspec .rake
Rust X - .rlib .in .rs
Sass - - .sass
Scala X X .sbt .kojo .sc .scala
Scss - - .scss
Shell - - .ksh .zsh .tool .sh .bats .tmux .bash .command
Sql - - .viw .bdy .fnc .tpb .tps .spc .trg .cql .sql .mysql .prc .vw .tab .udf .ddl
Swift X - .swift
Thrift - - .thrift
TypeScript X - .tsx .ts
VisualBasic X - .bas .frm .cls .frx .ctl .vb .vba .vbs
Xml - - .xmi .xml .sch .axml .csdef .glade .gml .gmx .wsdl .nuspec .cscfg .xsp-config .xquery .ct .rdf .xpl .xql .xqm .vcxproj .xacro .xqy .csproj .mxml .xsd .xsl .ivy .cproject .xproc .x3d .wsf .xul .tml .shproj .xproj .admx .ccproj .odd .adml .fsproj .wixproj .scxml .psc1 .targets .ncl .pluginspec .dita .workflow .sublime-snippet .wxi .wxl .wxs .xliff .fxml .ditamap .stTheme .jelly .dotsettings .clixml .ant .tmTheme .xslt .csl .pt .ccxml .builds .pkgproj .natvis .storyboard .sfproj .vsixmanifest .rss .tmSnippet .launch .xaml .nproj .ui .dll.config .ux .grxml .zcml .tmPreferences .xspec .tmLanguage .filters .xq .vbproj .mod .osm .srdf .props .ps1xml .depproj .kml .jsproj .plist .tmCommand .proj .ndproj .ditaval .owl .xml.dist .xib .mdpolicy .iml .mjml .vxml .vstemplate .urdf .resx .xlf .vssettings
Yaml - - .sed .syntax .reek .rviz .mir .tf .yaml .sublime-syntax .yaml-tmlanguage .yml

The Sokrates Book