Getting Started with Plugins

Fresh includes a built-in package manager for installing, updating, and managing plugins, themes, and language packs.

Installing Plugins

Use the command palette to install plugins from the registry:

Open Command Palette

Press Ctrl+P to open the command palette, then type >.

Search for Install Command

Type “pkg: Install Plugin” and press Enter.

Browse Available Plugins

Select a plugin from the list of available plugins in the registry.

Restart Fresh

Restart Fresh to activate the newly installed plugin.

Package Manager Commands

All package management is done through the command palette (Ctrl+P >):

Command	Description
`pkg: Install Plugin`	Browse and install plugins from the registry
`pkg: Install Theme`	Browse and install themes from the registry
`pkg: Install from URL`	Install directly from any git repository URL
`pkg: List Installed`	Show all installed packages
`pkg: Update All`	Update all installed packages
`pkg: Remove Package`	Remove an installed package
`pkg: Sync Registry`	Fetch the latest package lists from registry sources

Installing from Git URL

Any git repository can be installed directly:

Open Command Palette

Press Ctrl+P > to open the command palette.

Select Install from URL

Search for pkg: Install from URL and press Enter.

Enter Git URL

Paste the git repository URL:

https://github.com/user/fresh-plugin

Restart Fresh

Restart Fresh to activate the plugin.

Monorepo Support

For repositories containing multiple plugins, use a URL fragment to specify the subdirectory:

https://github.com/user/fresh-plugins#packages/rainbow-brackets

This installs only the packages/rainbow-brackets directory from the repository.

This is useful for monorepos or repositories that contain multiple related plugins.

Package Locations

Installed packages are stored in your config directory:

# Plugins
~/.config/fresh/plugins/packages/

# Themes
~/.config/fresh/themes/packages/

# Language Packs
~/.config/fresh/grammars/

Each package is a git repository, so you can update manually with git pull if needed.

Custom Registry Sources

By default, Fresh uses the official package registry. You can add additional registries in your config:

config.json

{
  "packages": {
    "sources": [
      "https://github.com/sinelaw/fresh-plugins-registry",
      "https://github.com/my-org/private-plugins"
    ]
  }
}

After adding sources, run pkg: Sync Registry from the command palette to fetch the latest package lists.

Only add registry sources you trust, as plugins have access to the editor API.

Plugin Development Location

When developing your own plugins, place them in the main plugins directory:

~/.config/fresh/plugins/

Any .ts file in this directory will be automatically loaded when Fresh starts.

For quick testing, you can create a plugin file directly in this directory without using the package manager.

Bundled Plugins

Fresh ships with many production-ready plugins already installed:

Essential Plugins

Git Integration

git_grep.ts - Interactive search through git-tracked files
git_find_file.ts - Fuzzy file finder for git repositories
git_blame.ts - Git blame view with commit navigation
git_log.ts - Git log viewer with history browsing
git_gutter.ts - Show git diff markers in the gutter

Code Tools

diagnostics_panel.ts - LSP diagnostics panel with navigation
find_references.ts - Find references across the codebase
todo_highlighter.ts - Highlights TODO/FIXME/HACK in comments
color_highlighter.ts - Preview color codes inline

Editing Features

search_replace.ts - Search and replace functionality
path_complete.ts - Path completion in prompts
markdown_compose.ts - Semi-WYSIWYG markdown editing
merge_conflict.ts - 3-way merge conflict resolution

Language Support

LSP integration for:

TypeScript/JavaScript (typescript-lsp.ts)
Rust (rust-lsp.ts)
Python (python-lsp.ts)
Go (go-lsp.ts)
C/C++ (clangd-lsp.ts)
And many more…

Using Plugins

Once installed, plugins automatically register their commands. Access them through:

Command Palette

Press Ctrl+P > and search for the plugin’s commands:

# Examples:
> Git Grep
> Git: Find File
> Git Blame
> Show Diagnostics
> Find References

Keybindings

Plugins can register keybindings. Check your config or the plugin’s documentation for available shortcuts.

Automatic Features

Some plugins work automatically:

todo_highlighter.ts - Automatically highlights TODO/FIXME keywords
color_highlighter.ts - Automatically previews color codes
git_gutter.ts - Automatically shows git changes in the gutter
diagnostics_panel.ts - Automatically shows LSP diagnostics

Updating Plugins

Keep your plugins up to date:

Open Command Palette

Press Ctrl+P > to open the command palette.

Update All Packages

Search for pkg: Update All and press Enter.

Restart Fresh

Restart Fresh to load the updated plugins.

Manual Update

Since each package is a git repository, you can also update manually:

cd ~/.config/fresh/plugins/packages/plugin-name
git pull

Removing Plugins

Remove unwanted plugins:

Open Command Palette

Press Ctrl+P > to open the command palette.

Remove Package

Search for pkg: Remove Package and select the plugin to remove.

Restart Fresh

Restart Fresh to complete the removal.

Troubleshooting

Plugin Not Loading

Check Plugin Location

Ensure the plugin is in the correct directory:

~/.config/fresh/plugins/
# or for installed packages:
~/.config/fresh/plugins/packages/

Check TypeScript Syntax

Plugins must have valid TypeScript syntax. Check for syntax errors:

/// <reference path="../types/fresh.d.ts" />

// Your plugin code here

Check Debug Logs

Run Fresh with debug logging:

RUST_LOG=debug fresh

Restart Fresh

Plugins are only loaded at startup. Always restart Fresh after installing or modifying plugins.

Plugin Conflicts

If two plugins conflict (e.g., both register the same keybinding), the last loaded plugin wins. Check your keybindings config to resolve conflicts.

Next Steps

Plugin Development

Learn how to create your own plugins

Plugin Examples

Explore real plugin examples with code

Plugin Overview

Learn about the plugin system architecture

API Reference

Complete API documentation

Getting Started

Core Features

Configuration

Advanced Features

Plugins

Reference

Getting Started with Plugins

Installing Plugins

Package Manager Commands

Installing from Git URL

Monorepo Support

Package Locations

Custom Registry Sources

Plugin Development Location

Bundled Plugins

Essential Plugins

Using Plugins

Command Palette

Keybindings

Automatic Features

Updating Plugins

Manual Update

Removing Plugins

Troubleshooting

Plugin Not Loading

Plugin Conflicts

Next Steps

Plugin Development

Plugin Examples

Plugin Overview

API Reference

Build docs developers (and LLMs) love

Getting Started

Core Features

Configuration

Advanced Features

Plugins

Reference

​Installing Plugins

​Package Manager Commands

​Installing from Git URL

​Monorepo Support

​Package Locations

​Custom Registry Sources

​Plugin Development Location

​Bundled Plugins

​Essential Plugins

​Using Plugins

​Command Palette

​Keybindings

​Automatic Features

​Updating Plugins

​Manual Update

​Removing Plugins

​Troubleshooting

​Plugin Not Loading

​Plugin Conflicts

​Next Steps

Plugin Development

Plugin Examples

Plugin Overview

API Reference

Build docs developers (and LLMs) love

Installing Plugins

Package Manager Commands

Installing from Git URL

Monorepo Support

Package Locations

Custom Registry Sources

Plugin Development Location

Bundled Plugins

Essential Plugins

Using Plugins

Command Palette

Keybindings

Automatic Features

Updating Plugins

Manual Update

Removing Plugins

Troubleshooting

Plugin Not Loading

Plugin Conflicts

Next Steps