Documentation

Install pude, learn the daily flow, and build your first plugin — read it the way you'd read it in pude.

Version 0.1.1 · Published release

README.md

Overview

pude is a local-first desktop code editor. It opens a local folder, edits text, shows Git, starts terminals on demand and loads local plugins — and keeps everything else out of the core.

What 0.1 includes

Local workspaces, a lazy Explorer and multiple windows
Multi-tab editing, syntax highlighting, find and replace, Markdown preview
Git status, commit graph, diffs and common actions through your system Git
Multiple on-demand terminals backed by real PTYs
Local plugins with permission review (API 2) and a restricted LSP process manager

What it leaves out on purpose

Project-wide indexing, a debugger or a build system
AI services, cloud sync and accounts
A plugin marketplace, automatic updates and bundled language servers

Reading these docs

Each file in the Explorer is one topic. Use Source / Preview in the status bar to see the Markdown behind any page, exactly as pude shows it.

install.md

Install and update

Platform	Installer
Windows 11 x64	`pude-windows-x64-setup.exe` (unsigned)
macOS 14+ Apple Silicon	`pude-macos-arm64.dmg`
Linux	Planned

Verify a download

Each release ships SHA256SUMS.txt, covering both installers and the license files. Compare the checksum before you install:

bash# macOSshasum -a 256 pude-macos-arm64.dmg# Windows (PowerShell)Get-FileHash .\pude-windows-x64-setup.exe -Algorithm SHA256

Manual updates

pude never updates itself and never checks for updates at startup. To update, close pude, download the newer installer and run it. In stable builds, the About dialog can look up the latest release — only when you click it.

using-pude.md

Using pude

Open a workspace

Choose Open folder (⌘K ⌘O, or Ctrl+K Ctrl+O on Windows) and pick a local directory. Only the top level is read; folders load as you expand them. A fresh start shows your recent projects, and every new window keeps its own workspace, tabs and terminals.

Explorer

Create, rename and delete files and folders. Deleting moves items to the Recycle Bin or Trash — never a permanent delete.
Right-click for Copy Path, Copy Relative Path and revealing the item in your file manager.
Long folders stay fast: only visible rows are rendered.

Edit

Tabs support drag to reorder, pinning, middle-click close, Close Others, Close to the Right and reopening a closed tab.
Find and replace with case, regex and whole-word options; ⌘G jumps to a line.
Multiple cursors, undo and redo, and indentation come from CodeMirror 6.
Hold ⌘ (or Ctrl) and scroll over the editor to set the font size between 11 and 24.
Markdown opens as source; switch to a rendered preview with Source / Preview in the status bar.

Files pude opens

UTF-8 and UTF-8 with BOM. Invalid UTF-8 and other encodings are refused rather than silently converted.
Files over 5 MiB open in large-file mode: editing and search stay on, heavy parsing and preview turn off.
Text files are limited to 20 MiB. Supported images open in an image preview.

Saving safely

Saves are queued per file and replace it atomically. Every line keeps its original LF or CRLF ending. If a file changes on disk while you have unsaved edits, pude offers Compare, Reload or Keep Editor Version — it never overwrites either side silently.

Unsaved work is checkpointed locally for recovery. Recovery restores the last completed checkpoint, not every keystroke.

git.md

Git

pude uses the Git installed on your system, so git must be on your PATH. Without Git, editing keeps working and the Git panel says it is unavailable.

Status and history

Switch the sidebar to GIT for the branch plus staged, unstaged, untracked, renamed and conflicted files.
The commit graph handles detached HEAD, unborn branches and multiple refs, and loads older history on demand.
Open any change as a side-by-side or stacked diff.

Actions

Stage and unstage, commit, push and pull, create, switch or safely delete branches, stash and pop. When a command fails, the full Git output opens in a dialog instead of a toast that disappears.

terminal.md

Terminal

Toggle the panel with ⌘` (Ctrl+` on Windows) and add as many tabs as you need. Each tab loads xterm.js and starts its own PTY the first time it is shown.

Hiding the panel keeps sessions running. Closing a tab, switching workspace or closing the window stops that tab's process tree.
Windows uses ComSpec, falling back to powershell.exe. macOS and Linux use SHELL, falling back to /bin/sh.
If the workspace has a Python virtual environment in .venv, venv or env, new terminals activate it.
Scrollback keeps 5,000 lines. ANSI colors, the alternate screen, mouse tracking, CJK text and IME input work as expected.

settings.md

Settings and local data

Setting	What it does
Font size	Editor text size. `⌘` + scroll changes it too.
Tab size	Width used for tabs and indentation.
Word wrap	Wraps long lines inside the editor.
Hide dot files	Hides names starting with `.` in the Explorer.
Watcher excluded paths	Paths the file watcher ignores, such as build output.

Where your data lives

Workspace files stay at their own paths. pude never copies them elsewhere.
Settings and session metadata are kept in local WebView storage.
Recovery checkpoints use IndexedDB with a local fallback. Clearing app storage can remove them.
Installed plugins are copied into the app data directory.

shortcuts.md

Keyboard shortcuts

Action	macOS	Windows
Save	`⌘S`	`Ctrl+S`
Save as	`⌘⇧S`	`Ctrl+Shift+S`
Save all	`⌘⌥S`	`Ctrl+Alt+S`
Open file	`⌘O`	`Ctrl+O`
Open folder	`⌘K ⌘O`	`Ctrl+K Ctrl+O`
Close tab	`⌘W`	`Ctrl+W`
Next / previous tab	`⌃⇥` / `⌃⇧⇥`	`Ctrl+Tab` / `Ctrl+Shift+Tab`
Find	`⌘F`	`Ctrl+F`
Replace	`⌘⌥F`	`Ctrl+H`
Go to line	`⌘G`	`Ctrl+G`
Command palette	`⌘⇧P`	`Ctrl+Shift+P`
Toggle terminal	⌘`	Ctrl+`
Font size	`⌘` + scroll	`Ctrl` + scroll

plugins.md

Building a plugin

A plugin is a local folder with a plugin.json manifest and a JavaScript entry. It runs in a Web Worker inside an opaque-origin sandbox and reaches pude only through the asynchronous pude API — no DOM, CodeMirror, Tauri or browser storage.

1. Write the manifest

This is the runnable example from examples/plugins/document-case-toggle. Every contributed command needs a matching onCommand:<id> event; onLanguage:<id>, onFileOpen, onFileSave and onWorkspaceOpen are also available.

json{  "id": "pude.example.document-case-toggle",  "name": "Document Case Toggle",  "version": "1.0.0",  "apiVersion": "2",  "entry": "extension.js",  "permissions": ["editor.read", "editor.write", "commands.register", "ui.notification"],  "activationEvents": ["onCommand:pude.example.document-case-toggle.toggleCase"],  "contributes": {    "commands": [      { "command": "pude.example.document-case-toggle.toggleCase", "title": "Toggle Document Case" }    ]  }}

2. Write the entry

jsconst commandId = "pude.example.document-case-toggle.toggleCase";function toggleCase(text) {  return text === text.toUpperCase() ? text.toLowerCase() : text.toUpperCase();}void pude.commands.register(commandId, async () => {  const file = await pude.editor.getFileInfo();  const text = await pude.editor.getText();  if (text.length === 0) {    await pude.ui.notify("The active document is empty.");    return;  }  await pude.editor.applyEdits(file.revision, [    { from: 0, to: text.length, insert: toggleCase(text) },  ]);  await pude.ui.notify("Document case toggled.");});

3. Install and iterate

Open Plugins, choose Install local plugin and select the folder.
Review the requested permissions and approve only what the plugin needs. Cancel keeps the current version and grants.
Enable the plugin and run its command from the command palette.
After editing, use Update from folder. The new version replaces the old one only after you approve it.

API at a glance

Permission	Calls	Notes
`editor.read`	`getText`, `getTextRange`, `getSelection`, `getCursor`, `getFileInfo`	Up to 128 Ki code units per call
`editor.write`	`applyEdits(revision, edits)`	Up to 1,000 edits; normal undo and dirty state
`workspace.read`	`list`, `readFile`, `getFileInfo`, `readFileRange`	128 KiB per read; ranges for larger files
`workspace.write`	`writeFile`	Conflict-checked; never deletes
`commands.register`	`commands.register`	Declared commands only
`ui.*`	`ui.notify`, `ui.statusBar`, `ui.quickPick`	Rendered by pude, bounded text
`git.read`	`git.getStatus`, `git.getDiff`	Read only
`terminal.write`	`terminal.write`	Only terminals the user opened
`network`	`network.fetch`	HTTPS to approved domains
`process.spawn:lsp`	`lsp.start`, `send`, `cancel`, `stop`	Declared servers only

Each run allows 512 concurrent requests, 20 requests per second, a 30-second timeout, 64 KiB requests and 1 MiB responses. The full reference lives in docs/plugin-api-v2.md.

build.md

Build from source

Node.js 22.12+, 24+ or 26+ with npm 10.9+ (Node.js 24 recommended)
Rust stable through rustup, and Git on PATH
macOS: Xcode Command Line Tools · Windows: MSVC C++ build tools and WebView2 · Linux: the Tauri GTK/WebKit packages

bashgit clone <repository-url>cd pudenpm ci

Commands

Command	Purpose
`npm run tauri:dev`	Run the native desktop app
`npm run dev`	Desktop UI in a browser shell (port 5173)
`npm run web:dev`	This website (port 5174)
`npm test`	Desktop Vitest suite
`npm run tauri:build`	Native bundles for the current platform

Before a pull request

bashnpm run checkcargo test --locked --manifest-path apps/desktop/src-tauri/Cargo.toml