Projectmind

ProjectMind Your project, explained by AI. by Plaintext · MPL-2.0

ProjectMind uses AI-ready project maps to explain software architecture, classes, modules and relationships in a way humans and coding agents can navigate. It's a lightweight, read-only architecture browser for source code that pairs bidirectionally with LLM-driven coding agents — Claude Code, ChatGPT / OpenAI Codex, Gemini CLI, Cursor, and any other frontier model that speaks the Model Context Protocol (MCP).

An AI agent authors this tour live over MCP — steps, line highlights and narration are pushed into the viewer. No human clicked anything.

> Status: v0.8 — MCP server + desktop app for macOS, Linux and Windows, with signed auto-updates. Java + Rust language plugins, Spring + Lombok framework recognisers, eight diagram types (bean graph, C4 container, folder heatmap, package tree, inheritance tree, doc graph, architecture layers, language stats), Markdown + HTML browsers (sandboxed), guided AI walkthroughs with quiz support, live AI-generated HTML/Markdown artifacts, and bidirectional MCP sync between LLM, desktop app and browser.

Quickstart

Install the desktop app + MCP server with one line. The script picks the right pre-built bundle for your OS / arch, no build toolchain required.

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/Plaintext-Gmbh/projectmind/master/scripts/install.sh | sh

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/Plaintext-Gmbh/projectmind/master/scripts/install.ps1 | iex

The desktop app lands in /Applications (macOS), ~/.local/share/projectmind (Linux), or %LOCALAPPDATA%\Programs\ProjectMind (Windows). The MCP server binary is installed alongside on your PATH so any LLM CLI can launch it.

Re-running the script upgrades to the newest release. Pin a specific version with PM_VERSION=v1.2.3 …. Skip components with PM_NO_APP=1 or PM_NO_MCP=1 (Bash) / $env:PM_NO_APP="1" (PowerShell).

When the bash installer detects a supported LLM CLI on PATH (currently claude and codex) it offers to register projectmind-mcp for you with a single claude mcp add / codex mcp add call. Override with PM_REGISTER=yes (auto-register every detected CLI without prompting) or PM_REGISTER=no (skip the prompt and just print the manual command).

Why

Modern AI-assisted development with CLI agents is great — until you want to see what just changed, visualise how the architecture is evolving, or drill into the structure without firing up a heavy IDE.

projectmind aims to be the missing piece:

• Standalone desktop app (Mac & Linux); not a VS Code extension.
• Read-only — no editing, no builds. Just an "architecture lens".
• MCP-bidirectional — your LLM can say "show class X with lines 42-58 highlighted" and the viewer renders it. You can mark code regions and the selection flows back into the conversation.
• Plugin-based — languages (Java, Kotlin, TypeScript, …), frameworks (Spring, Lombok, JSF, …) and visualisations (bean graph, package tree, C4, …) are all plugins.

GUI tabs

The Tauri shell has four tabs (each disabled until a repository is open):

• Code — module sidebar, class list, source viewer with stereotype filters, package drilldown.
• Diagrams — Mermaid bean graph or package tree; click a node to drill in.
• MD — every Markdown file in the repo, grouped by top-level directory, with rendered preview, mermaid blocks, and embedded images.
• HTML — every .html / .xhtml / .htm / .jsp / .vm / .ftl file plus HTML snippets extracted from .java / .kt / .groovy / .scala string literals (Java text blocks supported). Toggle Rendered ↔ Source; Rendered uses a strict sandbox iframe (no JS, no network) so untrusted repo content stays inert.

What it looks like

A 21-module Spring Boot monorepo (543 classes), straight after open_repo:

| Folder heatmap | C4 container view | Guided AI walkthrough | |---|---|---| | | | |

Dark and light themes, five UI languages, resizable panes throughout.

What works today

The Phase 1 MVP ships a Rust MCP server (projectmind-mcp) that any MCP-aware client — Claude Code, ChatGPT, Gemini CLI, Cursor, or your own custom agent — can connect to. It implements:

| Tool | What it does | |---|---| | open_repo | Open a repository. Detects Maven multi-module layouts (any pom.xml) and Cargo workspaces (any Cargo.toml with a [package]); falls back to a single module otherwise. | | repo_info | Summary (modules, classes) of the active repo. | | module_summary | Per-module class count and stereotype histogram. | | list_classes | List parsed classes (filter by stereotype). | | find_class | Case-insensitive substring search by simple or fully-qualified name. | | class_outline | Methods, fields, annotations and visibility of a class — without source. | | show_class | Source of a class with optional line-range highlights. | | list_changes_since | Files changed since a given git ref. | | show_diff | Unified diff between two refs (or ref vs working tree). | | show_diagram | Mermaid bean graph (subgraphs per Maven module, colour-coded by stereotype) or package tree. | | list_html | List HTML / XHTML / JSP / Velocity / FreeMarker template files in the open repository. | | list_html_snippets | Scan source files (.java, .kt, .groovy, .scala, incl. Java text blocks) for HTML snippets in string literals — filtered to ≥2 tags so XML namespace declarations and short error strings drop out. | | plugin_info | List active language and framework plugins. | | start_gui | Launch the ProjectMind desktop app if it isn't already running (the view_* tools auto-launch on demand, so call this only to bring up the window before any view intent). Honours $PROJECTMIND_APP for an override path. | | open_browser_repo | Start the in-process browser host that serves the ProjectMind webapp at a tokenized URL — same UI as the Tauri shell, but reachable from any browser. Default binds on 127.0.0.1; pass lan: true to bind on 0.0.0.0 so the URL works from another device on the same WLAN (iPad / phone / second laptop). The bearer token in the URL fragment gates every API call. | | browser_status | Return the running browser host's bind address, tokenized URLs and open repo, or null if no host is started. Side-effect free — handy to re-surface the URL/token without restarting the host. | | stop_browser | Forget the cached browser host status so the next open_browser_repo starts fresh. | | present_artifact | Render an AI-generated HTML or Markdown artifact live in every open viewer. Content is passed inline (not read from the repo), so the LLM can show generated dashboards, notes or diagrams without writing them to disk. HTML renders inside a sandboxed, CSP-locked iframe (no scripts, no network); Markdown renders like a .md file (mermaid + images). Re-use the id to iterate/stream. Max ~2 MB. | | list_artifacts | List the pushed artifacts (id, title, format, size, created/updated) — bodies excluded. |

The browser host is the natural answer to "open this repo on my iPad while I keep working on the laptop": ask the LLM to call open_browser_repo with lan: true, the response carries a http://:/#token=… URL you open on the second device. Both the Tauri desktop window and the browser tab subscribe to the same shared statefile, so any subsequent view_* / walkthrough_* push from the LLM mirrors to whichever viewers happen to be open.

Active language plugins in Phase 1:

• Java — Tree-sitter parser. Classes, interfaces, enums, records; methods, fields, annotations, visibility.
• Rust — Tree-sitter parser. Structs, enums, traits, unions; impl blocks attach methods and lift impl Trait for T as annotations on T. Module namespace is derived from the nearest [package].name.

Active framework recognisers in Phase 1:

• Spring — @Service, @RestController, @Controller, @Component, @Repository, @Configuration. Constructor and field injection (@Autowired, @Inject, @Resource) become Mermaid edges.
• Lombok — @Data, @Value, @Builder, @SuperBuilder, @*ArgsConstructor, @ToString, @EqualsAndHashCode, @Slf4j/@Log*, @Getter, @Setter, @With, … attached as a lombok stereotype with the detected annotations in class.extras.

Smoke-tested against real codebases: a 21-module Spring Boot Maven monorepo parses to ~500 classes with stereotype histograms and a Mermaid bean graph grouped by module; an 8-crate Cargo workspace (this repo) parses to ~60 classes with per-crate modules.

Build the MCP server (Ubuntu / Debian)

This is the path you want for using projectmind from any MCP-aware agent (Claude Code, ChatGPT, Gemini CLI, …) on Ubuntu — no GUI required.

The repo ships an installer for the impatient:

git clone git@github.com:Plaintext-Gmbh/projectmind.git
cd projectmind
./scripts/install-ubuntu.sh             # MCP server only
# or:
./scripts/install-ubuntu.sh --with-app  # also build the Tauri shell

The script installs build prerequisites, the Rust toolchain (via rustup, if missing), then builds and prints a ready-made .mcp.json snippet. If you'd rather install manually:

sudo apt update
sudo apt install -y build-essential pkg-config libssl-dev cmake git curl
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"

git clone git@github.com:Plaintext-Gmbh/projectmind.git
cd projectmind
cargo build --release --bin projectmind-mcp

# Result: target/release/projectmind-mcp

Build the MCP server (macOS)

# Prerequisites — Homebrew + Rust
brew install rustup-init || true
rustup-init -y
source "$HOME/.cargo/env"

git clone git@github.com:Plaintext-Gmbh/projectmind.git
cd projectmind
cargo build --release --bin projectmind-mcp

Build the Tauri shell (optional, GUI)

The Tauri app is the read-only graphical browser. It is the same engine, just with a UI on top.

Ubuntu / Debian

# Tauri prerequisites
sudo apt install -y \
  libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev \
  librsvg2-dev libsoup-3.0-dev libjavascriptcoregtk-4.1-dev patchelf

# Node toolchain (for the frontend)
curl -fsSL https://get.pnpm.io/install.sh | sh -

# Build
cd app
pnpm install
pnpm tauri build

macOS

# Node toolchain
brew install pnpm

cd app
pnpm install
pnpm tauri build

Run the app in dev mode (live-reload):

cd app && pnpm tauri dev

Use with an MCP-aware agent

ProjectMind speaks the Model Context Protocol (MCP), so any frontier LLM client that supports MCP can drive it: Claude Code, ChatGPT desktop, Gemini CLI, Cursor, Continue, or your own scripted agent. Add the server to whichever config the client uses (e.g. .mcp.json for Claude Code, mcp_settings.json for Cursor):

{
  "mcpServers": {
    "projectmind": {
      "type": "stdio",
      "command": "/absolute/path/to/projectmind-mcp",
      "env": {
        "PROJECTMIND_LOG": "info"
      }
    }
  }
}

Where is projectmind-mcp on disk?

Pick whichever of these you have installed:

• Desktop app installed — the MCP server is bundled next to the GUI

binary, so you can point your client straight at the in-app path. No separate install step:

• macOS: /Applications/ProjectMind.app/Contents/MacOS/projectmind-mcp
• Linux (.deb / .AppImage): /usr/bin/projectmind-mcp (.deb

installs to /usr/bin/; .AppImage mounts a temporary FUSE root — extract the AppImage with --appimage-extract if you need the binary on a stable path)

• Windows (.msi): C:\Program Files\ProjectMind\projectmind-mcp.exe
• MCP-only install (without the desktop app) — use the standalone

tarball from the Releases page or the helper scripts under [scripts/](scripts/). The binary lands wherever you placed it (commonly ~/.local/bin/projectmind-mcp).

• From source — target/release/projectmind-mcp after

cargo build --release --bin projectmind-mcp.

Claude Code users can register the bundled binary in one line:

# macOS
claude mcp add projectmind /Applications/ProjectMind.app/Contents/MacOS/projectmind-mcp

Re-running the same command after a desktop-app upgrade is a no-op, so the MCP server stays in lockstep with the GUI version automatically.

Restart the client. From a session, you can then ask things like:

• "Open the repo at /home/me/projects/my-spring-app and tell me how many services and controllers there are per module."
• "Find any class containing Auszahl and outline the most relevant one."
• "Show me the UserService class — highlight lines 80-95."
• "Which files changed since HEAD~5? Group them by module."
• "Render the bean graph as a Mermaid diagram."

The agent will pick the right tool calls from the list above.

Pre-built binary

The latest release on the Releases page ships projectmind-mcp and desktop app bundles where the GitHub runners can build them. New releases are produced by the Auto-Release workflow from the Actions tab; it bumps the version, opens a PR, merges, tags, and publishes in one shot.

Tests / development

For day-to-day work, use the small ./build helper:

./build dev      # Tauri app with hot reload
./build check    # cargo fmt --check + cargo clippy
./build test     # cargo test --workspace --all-targets + doctests
./build ci       # check + test
./build mcp      # release-build and smoke-test projectmind-mcp
./build app      # desktop app bundle for this machine
./build dist     # app bundle plus tar.gz + sha256 package

The lower-level CI wrapper is still available when you need exactly the workflow commands:

./scripts/ci.sh check
./scripts/ci.sh test
./scripts/ci.sh all

CI runs on Ubuntu 22.04 and macOS 14 for every push and pull request, plus a Linux release-build smoke test.

Architecture

A Cargo workspace with seven crates plus a Svelte frontend:

| Crate | Purpose | |---|---| | crates/plugin-api | Public traits and types (no implementations) | | crates/core | Repo loader, file walker, plugin pipeline, Maven + Cargo discovery, git helpers | | crates/mcp-server | The projectmind-mcp binary (JSON-RPC over stdio) | | plugins/lang-java | Java parser via Tree-sitter | | plugins/lang-rust | Rust parser via Tree-sitter | | plugins/framework-spring | Spring stereotypes + bean graph | | plugins/framework-lombok | Lombok annotation recogniser | | app/src-tauri | Tauri shell (Rust backend exposing Tauri commands) | | app/src/ | Svelte + TypeScript frontend with Mermaid integration |

Phase 1 plugins are statically registered. Phase 2 will add dynamic loading from a ./plugins/ directory next to the binary, so third-party plugins can drop in .so / .dylib files.

Reference docs (in the repo)

• [docs/architecture.md](docs/architecture.md) — workspace layout, plugin API, MCP tool schemas. Living reference, kept in sync with the code.
• [docs/SYNC.md](docs/SYNC.md) — how the MCP server and the Tauri GUI stay in sync (statefile + view intents).
• [docs/branding.md](docs/branding.md) — colour, typography, logo specs.
• [docs/reviews/](docs/reviews/) — historical architecture reviews.

Roadmap & planning

The roadmap and feature backlog now live on GitHub:

• Issues — concrete, schedulable work items (bugs, features, sub-tasks of epics)
• Project board — Kanban view of what's in flight
• Discussions — vision, longer-form des

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Plaintext-Gmbh
• Source: Plaintext-Gmbh/projectmind
• License: MPL-2.0
• Homepage: https://plaintext.ch/#projectmind

Install and usage instructions live in the source repository linked above.