> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/sinelaw/fresh/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started with Plugins

> Install, manage, and use plugins in Fresh with the built-in package manager

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:

<Steps>
  <Step title="Open Command Palette">
    Press `Ctrl+P` to open the command palette, then type `>`.
  </Step>

  <Step title="Search for Install Command">
    Type "pkg: Install Plugin" and press Enter.
  </Step>

  <Step title="Browse Available Plugins">
    Select a plugin from the list of available plugins in the registry.
  </Step>

  <Step title="Restart Fresh">
    Restart Fresh to activate the newly installed plugin.
  </Step>
</Steps>

## 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:

<Steps>
  <Step title="Open Command Palette">
    Press `Ctrl+P >` to open the command palette.
  </Step>

  <Step title="Select Install from URL">
    Search for `pkg: Install from URL` and press Enter.
  </Step>

  <Step title="Enter Git URL">
    Paste the git repository URL:

    ```
    https://github.com/user/fresh-plugin
    ```
  </Step>

  <Step title="Restart Fresh">
    Restart Fresh to activate the plugin.
  </Step>
</Steps>

### Monorepo Support

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

```bash theme={null}
https://github.com/user/fresh-plugins#packages/rainbow-brackets
```

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

<Tip>
  This is useful for monorepos or repositories that contain multiple related plugins.
</Tip>

## Package Locations

Installed packages are stored in your config directory:

<CodeGroup>
  ```bash Linux/macOS theme={null}
  # Plugins
  ~/.config/fresh/plugins/packages/

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

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

  ```bash macOS (Homebrew) theme={null}
  # If installed via Homebrew, create a symlink:
  ln -s /Users/username/fresh-plugins /opt/homebrew/bin/plugins
  ```
</CodeGroup>

<Note>
  Each package is a git repository, so you can update manually with `git pull` if needed.
</Note>

## Custom Registry Sources

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

```json config.json theme={null}
{
  "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.

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

## Plugin Development Location

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

```bash theme={null}
~/.config/fresh/plugins/
```

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

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

## Bundled Plugins

Fresh ships with many production-ready plugins already installed:

### Essential Plugins

<AccordionGroup>
  <Accordion title="Git Integration" icon="git">
    * **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
  </Accordion>

  <Accordion title="Code Tools" icon="code">
    * **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
  </Accordion>

  <Accordion title="Editing Features" icon="pencil">
    * **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
  </Accordion>

  <Accordion title="Language Support" icon="language">
    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...
  </Accordion>
</AccordionGroup>

## Using Plugins

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

### Command Palette

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

```bash theme={null}
# 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:

<Steps>
  <Step title="Open Command Palette">
    Press `Ctrl+P >` to open the command palette.
  </Step>

  <Step title="Update All Packages">
    Search for `pkg: Update All` and press Enter.
  </Step>

  <Step title="Restart Fresh">
    Restart Fresh to load the updated plugins.
  </Step>
</Steps>

### Manual Update

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

```bash theme={null}
cd ~/.config/fresh/plugins/packages/plugin-name
git pull
```

## Removing Plugins

Remove unwanted plugins:

<Steps>
  <Step title="Open Command Palette">
    Press `Ctrl+P >` to open the command palette.
  </Step>

  <Step title="Remove Package">
    Search for `pkg: Remove Package` and select the plugin to remove.
  </Step>

  <Step title="Restart Fresh">
    Restart Fresh to complete the removal.
  </Step>
</Steps>

## Troubleshooting

### Plugin Not Loading

<AccordionGroup>
  <Accordion title="Check Plugin Location">
    Ensure the plugin is in the correct directory:

    ```bash theme={null}
    ~/.config/fresh/plugins/
    # or for installed packages:
    ~/.config/fresh/plugins/packages/
    ```
  </Accordion>

  <Accordion title="Check TypeScript Syntax">
    Plugins must have valid TypeScript syntax. Check for syntax errors:

    ```typescript theme={null}
    /// <reference path="../types/fresh.d.ts" />

    // Your plugin code here
    ```
  </Accordion>

  <Accordion title="Check Debug Logs">
    Run Fresh with debug logging:

    ```bash theme={null}
    RUST_LOG=debug fresh
    ```
  </Accordion>

  <Accordion title="Restart Fresh">
    Plugins are only loaded at startup. Always restart Fresh after installing or modifying plugins.
  </Accordion>
</AccordionGroup>

### 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

<CardGroup cols={2}>
  <Card title="Plugin Development" icon="code" href="/plugins/development">
    Learn how to create your own plugins
  </Card>

  <Card title="Plugin Examples" icon="lightbulb" href="/plugins/examples">
    Explore real plugin examples with code
  </Card>

  <Card title="Plugin Overview" icon="info" href="/plugins/overview">
    Learn about the plugin system architecture
  </Card>

  <Card title="API Reference" icon="book" href="/api">
    Complete API documentation
  </Card>
</CardGroup>