xplorer Documentation

File: README.md Copy Chapter

Why Xplorer? Copy Chapter

Most file managers haven't changed in decades. Xplorer is a ground-up rethink: a Tauri 2 desktop app with a Rust backend for speed and a React frontend for flexibility. It ships with AI chat, Git integration, an extension marketplace, and themeable UI out of the box.

Note: This is the next branch -- a full rewrite using Tauri 2, React 18, and a new extension system. Not yet production-ready, but actively developed. Feedback welcome!

Features Copy Chapter

| File Management

• Cross-platform: Windows, macOS, Linux
• 6 view modes: Grid, List, Details, Column, Gallery, Tree
• Hardware-accelerated file operations (memory-mapped I/O, parallel chunked transfers)
• Archive support: ZIP, TAR, GZ, BZ2, XZ with password protection
• Multi-tab browsing, split panes, session persistence | AI Integration
• Connect any AI provider through API (OpenAI, Anthropic, Google, DeepSeek, Mistral, Ollama)
• Natural language, fuzzy, and semantic file search
• AI chat with full file context awareness
• Agentic file operations and smart categorization |
  | --- | --- |
  | Developer Tools
• Full Git integration: branches, staging, commits, diffs, blame, stash
• Integrated terminal with SSH remote browsing
• Rich file preview: code (syntax highlighted), Markdown, PDF, Word, spreadsheets, audio, video
• Command palette and configurable keyboard shortcuts | Extensibility
• Extension marketplace at xplorer.space
• Git UI, SSH manager, Docker, Google Drive, code editor, image editor, file hasher, and more
• Themes: Tokyo Night, Dracula, Nord, Cyberpunk, Ocean Deep
• Sandboxed runtime with public SDK — build and publish your own |

Use Cases Copy Chapter

For Developers Copy Section

Split-pane file browsing with integrated Git status, terminal, and code editor. Stage commits, view diffs, and manage branches without leaving the file manager.

For Researchers and Students Copy Section

AI chat that understands your files. Ask questions about documents, get summaries, and search by meaning — not just filename.

For Power Users Copy Section

Command palette, vim keybindings, custom keyboard shortcuts, and per-folder view settings. Six view modes, smart search with filters, and bulk file operations.

Screenshots Copy Chapter

Installation Copy Chapter

Download the latest release for your platform from the Releases page.

Getting Started (Development) Copy Chapter

Prerequisites Copy Section

• Node.js 20+
• pnpm 10+
• Rust (latest stable via rustup)

Setup Copy Section

git clone https://github.com/kimlimjustin/xplorer.git -b next
cd xplorer
pnpm install
pnpm dev:app

This starts the React frontend and Tauri backend. The app window will open automatically.

To run the full stack including the marketplace web server, use pnpm dev (requires local PostgreSQL via pnpm run marketplace:db).

Build and Test Copy Section

pnpm build              # Production build
pnpm test               # Frontend unit tests (Vitest)
pnpm run test:tauri      # Rust backend tests

Architecture Copy Chapter

xplorer/
├── apps/
│   ├── client/           # React 18 + TypeScript + Vite frontend
│   ├── src-tauri/        # Rust backend (Tauri 2, Tokio, Rayon)
│   └── web/              # Next.js marketplace (Prisma, Stripe)
├── packages/
│   ├── sdk/              # @xplorer/sdk — internal service layer
│   ├── extension-sdk/    # @xplorer/extension-sdk — public extension API
│   ├── create-extension/ # CLI scaffolder for new extensions
│   └── extensions/       # Built-in extension packages
├── e2e/                  # Playwright end-to-end tests
├── infra/                # Docker Compose (PostgreSQL)
└── scripts/              # Extension signing utilities

Contributing Copy Chapter

Contributions are welcome! See CONTRIBUTING.md for setup and guidelines.

• Bug reports -- GitHub Issues
• Feature requests -- Discussions

License Copy Chapter

AGPL-3.0

File: api/updater/README.md Copy Chapter

This is Xplorer's automatic updater API. Copy Chapter

Nothing much here, just an API to check if there is an update available and to download it.
Go back to the Xplorer website for Xplorer's docs.

File: api/README.md Copy Chapter

Home for Xplorer API.

/api/updater

An API to check if there is an update available and to download it.

File: docs/docs/Community/CODE_OF_CONDUCT.md Copy Chapter

sidebar_label: "Code Of Conduct" Copy Chapter

Contributor Covenant Code of Conduct

Our Pledge Copy Chapter

We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, religion, or sexual identity
and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.

Our Standards Copy Chapter

Examples of behavior that contributes to a positive environment for our
community includes:

• Demonstrating empathy and kindness toward other people
• Being respectful of differing opinions, viewpoints, and experiences
• Giving and gracefully accepting constructive feedback
• Accepting responsibility and apologizing to those affected by our mistakes,
  and learning from the experience
• Focusing on what is best not just for us as individuals, but for the
  overall community

Examples of unacceptable behavior include:

• The use of sexualized language or imagery, and sexual attention or
  advances of any kind
• Trolling, insulting or derogatory comments, and personal or political attacks
• Public or private harassment
• Publishing others' private information, such as a physical or email
  address, without their explicit permission
• Other conduct which could reasonably be considered inappropriate in a
  professional setting

Enforcement Responsibilities Copy Chapter

Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.

Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.

Scope Copy Chapter

This Code of Conduct applies within all community spaces and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.

Enforcement Copy Chapter

Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
[email protected].
All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the
reporter of any incident.

Enforcement Guidelines Copy Chapter

Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:

1. Correction Copy Section

Community Impact: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.

Consequence: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.

2. Warning Copy Section

Community Impact: A violation through a single incident or series
of actions.

Consequence: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or
permanent ban.

3. Temporary Ban Copy Section

Community Impact: A serious violation of community standards, including
sustained inappropriate behavior.

Consequence: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.

4. Permanent Ban Copy Section

Community Impact: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.

Consequence: A permanent ban from any sort of public interaction within
the community.

Attribution Copy Chapter

This Code of Conduct is adapted from the Contributor Covenant,
version 2.0, available at
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.

Community Impact Guidelines were inspired by Mozilla's code of conduct
enforcement ladder.

For answers to common questions about this code of conduct, see the FAQ at
https://www.contributor-covenant.org/faq. Translations are available at
https://www.contributor-covenant.org/translations.

File: docs/docs/Community/Contributing.md Copy Chapter

sidebar_position: 2 Copy Chapter

Contribute

👍🎉 First off, thanks for taking the time to contribute! 🎉👍

Xplorer is currently under heavy development. We are welcoming contributors to collaborate on Xplorer.

Get involved Copy Chapter

There are many ways to contribute to Xplorer, and many of them do not involve writing any code. Here are few ideas to get started:

• Start using Xplorer! Go through the Tutorial guides. Does anything work as expected? If not, we're always looking for improvements. Let us know by opening an issue.
• Look through the Xplorer issues. If you find an issue you would like to fix, open a pull request. Issues tagged as good first issue are a good place to get started.
• Help us make the docs better. File an issue if you find anything that is confusing, any grammatical error, or can be improved.
• Take a look at GitHub Discussions and give your opinion into a discussion or consider opening a pull request if you see something you want to work on.

Contributions are very welcome!

Our development process Copy Chapter

Xplorer uses GitHub as its source of truth. The core team will work directly there. All changes will be public from the beginning.

Reporting new issues/bugs. {#issues} Copy Section

When opening a new issue, always make sure to fill out the issue template. We use GitHub issues to track public bugs. Please ensure your description is clear and has sufficient instructions to be able to reproduce the issue.

• One issue, one bug: Please report a single bug per issue.
• Provide reproduction steps: List all the steps necessary to reproduce the issue. The person reading your bug report should be able to follow these steps to reproduce your issue with minimal effort.

Feature Request {#feat} Copy Section

We use GitHub Discussions and GitHub Issues to track ideas from users. Suggest a new feature here!
Great Feature Requests tend to have:

• A quick idea summary.
• What & why you wanted to add the specific feature.
• Additional references like images, links of resources about the feature, etc.

Working on Xplorer code Copy Chapter

Prerequisite Copy Section

• Tauri environment
• Node JS
• Git
• yarn
• Code Editor, we recommend you to use VS Code

Installation Copy Section

1. After cloning the repository, run yarn in the root of the repository and run yarn in the docs folder (if you want to working on Xplorer Docs).

2. To start Xplorer locally, run yarn dev.

   To start a local development server serving the Docusaurus docs, go into the docs directory and run yarn start

Gitpod for Xplorer's development {#gitpod-env} Copy Section

The easiest way to run Xplorer in Gitpod is to use the Gitpod service, all what you need to do is to click the button below and log in with your GitHub account. Afterwards, you will see a VS Code-like environment where you can start developing and pushing your changes. Please note that you may have to wait up to minutes to get Xplorer running on the poped up VNC tab.

[](https://gitpod.io/#/https://github.com/kimlimjustin/xplorer) Copy Chapter

Semantic commit messages {#commit-msg} Copy Section

See how a minor change to your commit message style can make you a better programmer.

Format: <type>(<scope>): <subject>

<scope> is optional

Example

feat: allow overriding of webpack config
^--^  ^------------^
|     |
|     +-> Summary in present tense.
|
+-------> Type: chore, docs, feat, fix, refactor, style, or test.

the various types of commits:

• feat: new feature for the user
• fix: bug fix for the user
• docs: changes to the documentation
• style: formatting, missing semi-colons, etc.
• refactor: refactoring production code, eg. renaming a variable
• test: adding missing tests, refactoring tests.
• chore: updating grunt tasks etc

Use lower case not the upper case!

Working on Xplorer docs Copy Chapter

Xplorer documentation website is built using Docusaurus 2, and its code is located at docs folder.

Prerequisite Copy Section

• node js
• git
• yarn
• Code Editor, we recommend you to use VS Code

Installation Copy Section

After cloning the repository, run yarn in the docs folder (you can go into the docs folder by running the cd docs command).

If you want to use Gitpod, click here for the guide on how to use Gitpod.

Local development Copy Section

1. Run the yarn start command in the docs folder.
2. Edit some markdown texts in the docs folder and the website will be hot reloaded.

Pull requests Copy Chapter

Your first pull request. {#first-pull-request} Copy Section

So you have decided to contribute code back to upstream by opening a pull request. You've invested a good chunk of time, and we appreciate it. We will do our best to work with you and get the PR looked at.

Working on your first Pull Request? You can learn how from this free video series:

How to Contribute to an Open Source Project on GitHub

We have a list of beginner-friendly issues to help you get your feet wet in the Xplorer codebase and familiar with our contribution process. This is a great place to get started.

Proposing a change Copy Section

If you would like to request a new feature or enhancement but are not yet thinking about opening a pull request, you can also open a discussion and others will code it!

If you intend to fix a bug, please discuss it through Issues before submitting a pull request.

If you intend to add a new feature, please discuss it through GitHub Discussions to avoid multiple people working on the same feature request.

Sending a Pull Request Copy Section

make sure the PR does only one thing, otherwise please split it. It is recommended to follow this commit message style.

1. Fork the repository and create your branch from master.
2. Make changes and ensure your commit message is understandable.
3. Open a PR and ensure to describe your pull request clearly.

Working on Xplorer resources Copy Chapter

Locales Copy Section

We host our locales on the crowdin. To translate it, please follow these steps:

• Sign up on Crowdin and Join our project here.
• Make sure your locale exists there, if it does not exist, leave a comment in this discussion and I'll add the language option :)
• Get familiar with the Crowdin translation UI, as you will need to use it to translate JSON and Markdown files
• Translate the content!

Priority Files to translate on Crowdin

1. src/Locales files
2. docs/ files

Production

Once the files on src/Locales have been translated for more than 80%, we will add it into the Xplorer app, and for the docs, we will add it into production once the translation looks good!

Please comment here if you have any questions!

File Library Copy Section

The json library of file types and thumbnail are found under lib folder and the icons are found under src/Icons folder. You may add file types and icons for file extensions you want to use and submit a PR.

File: docs/docs/Community/support.md Copy Chapter

sidebar_position: 1 Copy Chapter

Support

Xplorer is an open-source project which you can freely join and seek support 😊.

On this page, we've listed some communities/forums you can participate in to seek support or help others.

Before participating in Xplorer's communities, please read our Code Of Conduct.

Issues Copy Chapter

We use GitHub Issues to track public bugs. Please ensure your description is clear and has sufficient instructions to be able to reproduce the issue. Report a bug by opening a new issue here.

GitHub Discussions Copy Chapter

GitHub Discussions is used for multiple purposes, such as:

1. Asking questions
2. Making feature requests and sharing ideas
3. Chat on Xplorer
4. Show and tell: Making custom themes/plug-ins for Xplorer and showing them there!

Feature Request Copy Section

We use GitHub Discussions and GitHub Issues to track ideas from users. Suggest a new feature here!
Great Feature Requests tend to have:

• A quick idea summary.
• What & why you wanted to add the specific feature.
• Additional context like images, links to resources to implement the feature, etc.

Help Copy Section

You can ask for help using GitHub Discussion or Discord Channel.

:::note
Remember to choose the discussion category as Q&A so that your question will be published with answers enabled.
:::

News Copy Chapter

For the latest news about Xplorer, you can see it through posts on Forem.

File: docs/docs/Extensions/create.mdx Copy Chapter

Write your extension (Beta)

Currently extension type that is supported is theme extension. Stay tuned for other extensions!

Get started Copy Chapter

In this topic, we'll teach you how to create your first extension for Xplorer. To get started, make sure you have Node.js installed, then install yeoman and Xplorer Extension Generator by running following command:

npm i yo generator-xplorer-extensions

The generator scaffolds a new extension project ready for development. Run the generator and fill out a few fields to get started.

yo xplorer-extensions

Start the development process Copy Chapter

You can start the development process by running the following command:

npm start

You can start edit the extension file and see the changes in Xplorer, it's hot reloaded!

Theme Copy Section

Your generated theme extension file is under ./themes folder and is a JSON file. The syntax for the theme file is as follows:

"<scope><element query><CSS key>": "<CSS value>"

Scopes are: root, windowmanager, tabs, settings, favorites, favorites, grid, contextmenu, prompt, preview and properties. Scopes are used to group the theme.

Element query: basically just like what a CSS query does.

CSS Key is the name of the CSS property you want to change. Please note that snakeCase will be converted into snake-case.

:::tip

There're some CSS variables provided to the theme value that you can make use of are:

1. --sidebar-transparency, the transparency of the sidebar, in percentage
2. --workspace-transparency, the transparency of the workspace, in percentage
3. --topbar-transparency, the transparency of the topbar, in percentage

:::

Examples

Examples of theme extensions are found in the example/themes on GitHub repository.

Packaging your extension Copy Chapter

When you're ready to package your extension, you can run the following command:

npm run build

This command will package and build your extensions into Xplorer reserved .xtension file format.

Install the packaged extension Copy Chapter

npm run xplorer:install

File: docs/docs/Extensions/theme.md Copy Chapter

Themes (Beta)

Get Started Copy Chapter

The Theme extension is a way to define the look of the Xplorer. Xplorer comes with a few default themes (which are light, dark, light+, and dark+), but you can also create your own, which is a great way to personalize your Xplorer and is documented in this guide.

How do I change between themes?

You can switch between themes by opening settings and on the Preference page, you can see a dropdown menu with the available themes under App Theme section.

Installing a theme Copy Chapter

There are 2 ways to install a theme:

Via `.xtension` file Copy Section

You can download .xtension file from the theme developer and simply double clicking it on Xplorer.

Install from public URL via Xplorer CLI. Copy Section

You can also install a theme from a public URL via Xplorer CLI by running following command:

xplorer extensions theme install

Example

[Shades of Purple](https://github.com/kimlimjustin/xplorer/tree/master/example/themes/shades%20of%20purple)

Run following command to install Shades of Purple theme:

xplorer extensions theme install https://raw.githubusercontent.com/kimlimjustin/xplorer/master/example/themes/shades%20of%20purple/dist/themes.xtension

[Winter](https://github.com/kimlimjustin/xplorer/tree/master/example/themes/winter)

Run following command to install Winter theme:

xplorer extensions theme install https://raw.githubusercontent.com/kimlimjustin/xplorer/master/example/themes/winter/dist/themes.xtension

Uninstalling a theme Copy Chapter

To uninstall a theme, you can run following command:

xplorer extensions uninstall

Official Themes Copy Chapter

There are currently 2 official themes:

• Shades of Purple
• Winter

Show yours! 👋 Copy Chapter

Our community is always looking for new themes. If you have a theme that you think would be a good fit, please tell it to us.

File: docs/docs/guides/cli.md Copy Chapter

Launch Xplorer from Terminal

Commands Copy Chapter

Xplorer CLI:

xplorer <options> [dir1] [dir2] [dir3]

Xplorer will open dir, dir2, dir3 as tabs on Xplorer. If there's no directory(dir) passed into the command, Xplorer will start at the Home page.

Options:

Subcommands Copy Chapter

Extensions Copy Section

Install

Install an extension from xtension file type. Command:

xplorer extensions install

Uninstall

Uninstall an installed extension. Command:

xplorer extensions uninstall <extension identifier>

Theme

Build

Package and build theme into themes.xtension file to distribute. Command:

xplorer extensions theme build

Install

Install an extension from xtension file type.

xplorer extensions theme install

File: docs/docs/guides/operation.md Copy Chapter

Operations

Copy files Copy Chapter

You can copy files by right-clicking it and click the Copy option or select the file then press Ctrl + C as a shortcut and paste it by clicking the Paste option or press Ctrl + V on the destination folder.

:::info

For current implementation, Xplorer write down what to copy locally (not copying to clipboard).

TODO: implement copy to clipboard

:::

Copy Location Path Copy Chapter

You can copy a file/folder location path into your clipboard by right-clicking it and click Copy Location Path or select the file then press Alt + Shift + C as a shortcut.

Cut files Copy Chapter

You can cut files by right-clicking it and click the Cut option or select the file then press Ctrl + X as a shortcut and paste it by clicking the Paste option or press Ctrl + V on the destination folder.

:::info

For current implementation, Xplorer write down what to cut locally (not copying to clipboard).

:::

Delete files Copy Chapter

You can delete files by right-clicking it and click the Delete option or select the file then press Del as a shortcut.

Trashed files Copy Section

The trashed file can be accessed at xplorer://Trash or your system trash folder.
:::danger Open Issue

Please note that Trash folder cannot be accessed on macos via Xplorer since the trash crate Xplorer relies to does not support it (see this issue for more details).

Any contributions to either the trash crate or Xplorer itself for this topic are welcome.
:::

Restore files Copy Section

You can restore files by opening the xplorer://Trash and right-clicking it and click the Restore option

Permanently delete Copy Section

:::danger
A permanently deleted file cannot be restored. Please check again before permanently delete any files.

:::

You can permanently delete a file by:

1. Delete it into Trash and right-clicking it and click the Permanent Delete option
2. Select the file and press Shift + Del as a shortcut

Search files Copy Chapter

Xplorer uses glob patterns to search matched files. Learn about Glob pattern syntax. To get started, press Ctrl + F and type inside the search box.

Instant search Copy Section

You can instant search a file/dir by typing the starting characters of the file/dir name and Xplorer will select the file for you. Some rules of instant search:

• Any english diacritic is removed
• The interval for instant search is 750ms. After 750ms, the search query will be reseted.
• Typing the same character will make Xplorer to find the next matches.

New Copy Chapter

:::caution Be careful with new file/folder name
Xplorer treats / on file name/folder as subdir/subfile
:::

New file Copy Section

You can create a new file by right-clicking the workspace, expand the New option and select the file option, or press Alt + N as a shortcut.

New folder Copy Section

You can create a new folder by right-clicking the workspace, expand the New option and select the folder option, or press Shift + N as a shortcut.

Open file Copy Chapter

You can open a file on the default application by double-clicking it or select the file then press Enter as a shortcut.

Open in Terminal Copy Section

This is a built-in function by Xplorer. You can open a folder on Terminal by right-clicking it and click the Open in terminal option or select the folder then press Alt + T as a shortcut.

Open in VSCode Copy Section

This is a built-in function by Xplorer. You can open a file/folder on VSCode by right-clicking it and click the Open in vscode option or select the file then press Ctrl + Enter as a shortcut. You won't able to do this if you don't have VSCode installed.

Pin to Sidebar Copy Chapter

You can pin a file/folder into the sidebar by right-clicking it and click Pin to Sidebar or select the file then press Alt + P as a shortcut.

Preview file Copy Chapter

You can preview a file directly from Xplorer by right-clicking it and click the Preview option or select the file then press Ctrl+O.

:::info

Files available to preview for now:

• Markdown files
• Image files
• Text files
• Video files
• Pdfs
• Almost all programming language with syntax highlighting

:::

Properties Copy Chapter

You can view properties of a file/folder by right-clicking it and click Properties or select the file then press Ctrl + P as a shortcut.
Available properties for now (will be improved at the next version):

• Size
• File Path
• Created At
• Accessed At
• Modified At
• Is Hidden

Rename file/folder Copy Chapter

You can rename a file/folder by right-clicking it and click the Rename option or select the file then press F2 as a shortcut. It will prompt a dialog, enter the new name and the file/folder will be renamed.