projectmind

<p align="center"> <img src="docs/assets/logo.png" alt="ProjectMind" width="96" height="96"/> </p> <h1 align="center">ProjectMind</h1> <p align="center"><strong>Your project, explained by AI.</strong></p> <p align="center">_{by Plaintext · MPL-2.0}</p> 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)**. <p align="center"> <img src="docs/assets/demo-walkthrough.gif" alt="An AI agent authors a guided tour of a Spring codebase over MCP; ProjectMind renders every step live" width="820"/> </p> <p align="center">_{An AI agent authors this tour <strong>live over MCP</strong> — steps, line highlights and narration are pushed into the viewer. No human clicked anything.}</p> > **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, 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:** ```sh curl -fsSL https://raw.githubusercontent.com/Plaintext-Gmbh/projectmind/master/scripts/install.sh | sh ``` **Windows (PowerShell):** ```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. | 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://<lan-ip>:<port>/#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: ```bash 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: ```bash 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) ```bash # 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 ```bash # 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 ```bash # Node toolchain brew install pnpm cd app pnpm install pnpm tauri build ``` Run the app in dev mode (live-reload): ```bash 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): ```json { "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](https://github.com/Plaintext-Gmbh/projectmind/releases/latest) 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: ```bash # 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](https://github.com/Plaintext-Gmbh/projectmind/releases/latest) 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: ```bash ./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: ```bash ./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](https://github.com/Plaintext-Gmbh/projectmind/issues)** — concrete, schedulable work items (bugs, features, sub-tasks of epics) - **[Project board](https://github.com/Plaintext-Gmbh/projectmind/projects)** — Kanban view of what's in flight - **[Discussions](https://github.com/Plaintext-Gmbh/projectmind/discussions)** — vision, longer-form design conversations, and visualisation sketches. The [Vision & Roadmap thread](https://github.com/Plaintext-Gmbh/projectmind/discussions/58) is the canonical place for high-level direction. Phase summary: - **Phase 1 (done):** MCP server with Java + Spring + Lombok plugins, Rust plugin, package tree, bean graph, folder map, diff view, Markdown + HTML browsers, walkthrough mode, core MCP tools, Tauri shell with bidirectional MCP sync. - **Phase 2 (in progress):** Annotation round-trip, ~~draw.io embed~~ (`.drawio` files render via the embedded diagrams.net viewer), Confluence MCP bridge, dynamic plugin loading from `./plugins/`. - **Phase 3:** Plugin marketplace, more languages, JSF / PrimeFaces preview, C4 diagram generator. ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md). The project is in early design — discussions, ideas, and visualisation sketches are very welcome. ## License [MPL 2.0](LICENSE) — Mozilla Public License Version 2.0.