|
Sokrates
Polyglot source code examination tool
|
"Talk is expensive. Show me the code."
― Željko Obrenović
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:
| DOWNLOAD: | sokrates-LATEST.jar (40 MB) |
| CURL: |
curl https://d2bb1mtyn3kglb.cloudfront.net/builds/sokrates-LATEST.jar --output sokrates-LATEST.jar |
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]
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
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
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
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
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.
Read a finished Sokrates analysis (_sokrates/) and write findings with verifiable evidence. Each scanner answers one question:
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:
The field references were read from the Sokrates Java source — including the places where documentation and code disagree.
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)
| Tool | Reads skills from | Invoke |
|---|---|---|
| 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.git | activates 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 tools | any Agent-Skills folder: ./install.sh <folder>, or copy the skill folders | see the tool's documentation |
Requirements: Python 3.9+ (standard library only) for the scripts, and a Sokrates analysis of your project.
cd <your-project> java -jar sokrates.jar init java -jar sokrates.jar extractGitHistory # optional, enables history-based insights java -jar sokrates.jar generateReports
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:
Then regenerate the reports so the analysis reflects the refined configuration:
java -jar sokrates.jar generateReports
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.
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.
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.
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.
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.
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.
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 exportStandardConventions
NOTE: Analysis is limited to repositories with commits in past year or two.
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.