Beret
A codebase intelligence tool that builds an in-memory RDF knowledge graph and exposes it through CLI commands, MCP tools, and SPARQL queries. It parses 17 programming languages using structural AST analysis, extracts metadata from config files and documents, indexes git history for human activity analysis, detects engineering practices, and generates architecture diagrams.
Installation
The release profile enables LTO and single codegen unit for maximum binary performance.
Usage
Beret operates in three modes: CLI for direct analysis, stdio MCP for AI tool integration, and HTTP MCP for remote access.
CLI mode
Run analysis commands directly from the terminal. Each command indexes the target directory and prints JSON to stdout.
beret describe # consolidated project analysis
beret activity # git contributors, active files, recent commits
beret testing # test frameworks, test ratio
beret architecture # layers, structure counts
beret dependencies # package managers, dep count
beret practices # all detected engineering practices
beret stats # counts by structure type
beret find main # find symbols named "main"
beret diagram # generate LikeC4 architecture diagram
beret query 'SELECT ?f WHERE { ?f <http://repo.example.org/a> <http://repo.example.org/Function> }'
All commands accept an optional [PATH] argument (defaults to current directory):
beret describe /path/to/project
beret activity ~/repos/my-app
Use --exclude to skip paths during indexing with gitignore-style patterns (repeatable):
beret describe --exclude node_modules --exclude target
beret stats --exclude '*.generated.*' --exclude vendor/
beret describe /path/to/project --exclude dist --exclude .cache
MCP server mode
The server starts with an empty knowledge graph and indexes on demand. Call refresh_index with a directory path to populate the graph, then use the other tools to explore. This lets you launch one server and re-target it at different projects or subdirectories as you work.
An optional [PATH] argument (e.g., beret /path/to/project) sets the default directory for refresh_index when called without a path. If omitted, defaults to the current working directory.
In stdio mode, --exclude patterns passed on the command line are applied as defaults to every refresh_index call. Additional patterns can be passed via the exclude tool parameter.
MCP client configuration
All entries are placed in
{
"mcpServers": {
"beret": ...
}
}
in your client config (e.g., mcp.json, claude_desktop_config.json).
After connecting, ask the agent to index a directory (e.g., "index the current project") or for remote HTTP, a repository (e.g., "index https://github.com/user/repo").
Tools
All list-returning tools support limit, offset, and exclude parameters. exclude takes a comma-separated list of directory names to filter out (e.g., "docs,stories,dist"). When results exceed the limit, the response includes has_more: true and next_offset for pagination.
Exploration tools
Call graph tools
Dependency & config tools
Code search tools
Visualization tools
depth:0= auto (default),1= directories,2= +files,3= +functions/classescode_only:true(default) — excludes docs, configs, binaries, test dirs, stories, etc.exclude: comma-separated directory names to additionally exclude- Beret theme: custom colors (navy
#00005F, orange#F5921B, gold#FFCC17, teal#37A3A3, blue#0066CC), distinct shapes per element type, styled relationship arrows - Output: paste into playground.likec4.dev, save as
.c4, or render withnpx likec4
Practice & project analysis tools
Index management tools
Pagination
When results are paginated, the response wraps results with metadata:
{
"results": [...],
"total": 1847,
"returned": 200,
"offset": 0,
"has_more": true,
"next_offset": 200,
"message": "Showing 1–200 of 1847 results. Use offset: 200 to see the next page."
}
search_pattern examples
Find all Rust functions:
pattern: "fn $NAME($$$ARGS) { $$$BODY }"
language: "rust"
Find all console.log calls in JavaScript:
pattern: "console.log($MSG)"
language: "javascript"
Find Python classes inheriting from a base:
pattern: "class $NAME($BASE): $$$BODY"
language: "python"
query_codebase SPARQL examples
All IRIs use the repo: prefix, which expands to http://repo.example.org/.
List all functions:
SELECT ?func WHERE {
?func <http://repo.example.org/a> <http://repo.example.org/Function>
}
Find all callers of a function:
SELECT ?caller WHERE {
?caller <http://repo.example.org/calls> <http://repo.example.org/process>
}
Find all dependencies:
SELECT ?file ?dep WHERE {
?file <http://repo.example.org/dependsOn> ?dep
}
Find test functions (annotation or path-based):
SELECT ?func WHERE {
?func <http://repo.example.org/isTestFunction> <http://repo.example.org/true>
}
Find recent commit authors:
SELECT ?author ?date ?message WHERE {
?commit <http://repo.example.org/commitAuthor> ?author .
?commit <http://repo.example.org/commitDate> ?date .
?commit <http://repo.example.org/commitMessage> ?message
} ORDER BY DESC(?date) LIMIT 10
Find most-modified files:
SELECT ?file ?count WHERE {
?file <http://repo.example.org/commitCount> ?count
} ORDER BY DESC(?count) LIMIT 20
List binary files with MIME types:
SELECT ?file ?mime WHERE {
?file <http://repo.example.org/a> <http://repo.example.org/Binary> .
?file <http://repo.example.org/hasMimeType> ?mime
}
Check if any call relationships exist:
ASK { ?a <http://repo.example.org/calls> ?b }
Knowledge graph schema
Code structures
Subjects are qualified with the file path (e.g., src/main.rs/handle_request). Call targets are the unqualified callee name. For method calls like obj.method(), only method is recorded. For namespaced calls like mod::func(), only func is recorded.
Test detection: Functions are marked as tests via @Test/@ParameterizedTest/@RepeatedTest annotations (Java), [TestMethod]/[Fact]/[Theory]/[Test] attributes (C#), or when located in test directories (/test/, /tests/, /__tests__/, /spec/).
Config files (JSON, YAML)
Documents (Markdown, HTML, AsciiDoc, reStructuredText, man pages)
Stylesheets (CSS)
Binary files
Git activity
Indexed from git log output (last 500 commits). Gracefully skipped if not a git repo.
Supported languages
Non-code files
Binary files (metadata only)
Images (.png, .jpg, .gif, .webp, .svg, .ico, .bmp), audio (.mp3, .wav, .ogg, .flac, .aac), video (.mp4, .webm, .avi, .mov, .mkv), fonts (.ttf, .otf, .woff, .woff2), documents (.pdf), archives (.zip, .gz, .tar), executables (.exe, .dll, .so, .dylib, .wasm), databases (.sqlite, .db).
Build file dependency extraction
Dependencies are extracted from 20+ build file formats: package.json, Cargo.toml, pom.xml, build.gradle(.kts), go.mod, Gemfile, Podfile, requirements.txt, pyproject.toml, composer.json, Pipfile, pubspec.yaml, Package.swift, build.sbt, mix.exs, .csproj/.fsproj, Dockerfile/Containerfile (FROM), docker-compose.yml (image), .spec (Requires/BuildRequires), debian/control (Depends/Build-Depends).
Engineering practices
Detected from file presence and directory structure. All use <project> as subject.
Performance
The ingestor uses parallel file walking (via the ignore crate) and direct tree-sitter node kind matching for speed. Benchmarked at 5,000 files / 60,000 triples in under 1 second in debug mode. Git history indexing adds a single git log call after the file walk.
Publishing
Crates.io
cargo publish
Publishes as chapeaux-beret. Users install with cargo install chapeaux-beret.
npm
cd npm && npm publish --access public
Publishes as @chapeaux/beret. Requires pre-built binaries uploaded to GitHub releases.
JSR
cd npm && npx jsr publish
Publishes as @chapeaux/beret on JSR. Users run with npx jsr:@chapeaux/beret.
Testing
cargo test
License
MIT