# Adding Custom Package Sources

The Package Manager allows you to extend its functionality by adding custom package sources. This guide explains how to set up and manage your own package repositories to access additional components beyond the default offerings.

## Setting up a Package Source Repository

A package source repository is a Git repository that contains packages organized in a specific structure. You can create your own repository to host custom packages:

### Repository Requirements

1. **Proper Structure**: The repository must follow the required directory structure
2. **Valid Metadata**: Each package must include properly formatted metadata files
3. **Git Repository**: The source must be a Git repository accessible via HTTPS

### Creating a New Repository

1. Create a new repository on GitHub, GitLab, or another Git hosting service
2. Initialize the repository with a README.md file
3. Clone the repository to your local machine:

```bash
git clone https://github.com/your-username/your-package-repo.git
cd your-package-repo
```

4. Create the basic repository structure:

```bash
mkdir -p packages modes "mcp servers" prompts
touch metadata.en.yml
```

5. Add repository metadata to `metadata.en.yml`:

```yaml
name: "Your Repository Name"
description: "A collection of custom packages for Roo Code"
version: "1.0.0"
```

6. Commit and push the initial structure:

```bash
git add .
git commit -m "Initialize package repository structure"
git push origin main
```

## Required Structure and Metadata

A package source repository must follow a specific structure to be properly recognized by the Package Manager:

### Repository Structure

```
repository-root/
├── metadata.en.yml           # Repository metadata
├── README.md                 # Repository documentation
├── packages/                 # Directory for package components
│   ├── package-1/
│   │   ├── metadata.en.yml   # Package metadata
│   │   └── README.md
│   └── package-2/
│       ├── metadata.en.yml
│       └── README.md
├── modes/                    # Directory for mode components
│   └── custom-mode/
│       └── metadata.en.yml
├── mcp servers/              # Directory for MCP server components
│   └── custom-server/
│       └── metadata.en.yml
└── prompts/                  # Directory for prompt components
    └── custom-prompt/
        └── metadata.en.yml
```

### Repository Metadata

The root `metadata.en.yml` file describes the repository itself:

```yaml
name: "Custom Components Repository"
description: "A collection of specialized components for data science workflows"
version: "1.0.0"
author: "Your Name or Organization"
tags:
    - custom
    - data-science
```

### Component Organization

- Components should be organized by type in their respective directories
- Each component must have its own directory containing a metadata file
- Components can be nested within packages
- Follow the same structure as described in [Adding Packages](./05-adding-packages.md)

## Adding Sources to Roo Code

Once you have a properly structured package source repository, you can add it to your Roo Code Package Manager:

### Default Package Source

Roo Code comes with a default package source:

- URL: `https://github.com/RooVetGit/Roo-Code-Packages`
- This source is enabled by default, and anytime all sources have been deleted.

### Adding a New Source

1. Open VS Code with the Roo Code extension
2. Navigate to the Package Manager
3. Switch to the "Sources" tab
4. Click the "Add Source" button
5. Enter the repository URL:
    - Format: `https://github.com/username/repository.git`
    - Example: `https://github.com/your-username/your-package-repo.git`
6. Click "Add" to save the source

### Managing Sources

The "Sources" tab provides several options for managing your package sources:

1. **Remove**: Delete a source from your configuration
2. **Refresh**: Update the package list from a sources - this is forced git clone/pull to override local caching of data

### Source Caching and Refreshing

Package Manager sources are cached to improve performance:

- **Cache Duration**: Sources are cached for 1 hour (3600000 ms)
- **Force Refresh**: To force an immediate refresh of a source:
    1. Go to the "Sources" tab
    2. Click the "Refresh" button next to the source you want to update
    3. This will bypass the cache and fetch the latest data from the repository

### Troubleshooting Sources

If a source isn't loading properly:

1. Check that the repository URL is correct
2. Ensure the repository follows the required structure
3. Look for error messages in the Package Manager interface
4. Try refreshing the sources list
5. Disable and re-enable the source

## Creating Private Sources

For team or organization use, you might want to create private package sources:

### Private Repository Setup

1. Create a private repository on your Git hosting service
2. Follow the same structure requirements as public repositories
3. Set up appropriate access controls for your team members

### Authentication Options

To access private repositories, you may need to:

1. Configure Git credentials on your system
2. Use a personal access token with appropriate permissions
3. Set up SSH keys for authentication

### Organization Best Practices

For teams and organizations:

1. Designate maintainers responsible for the package source
2. Establish quality standards for contributed packages
3. Create a review process for new additions
4. Document usage guidelines for team members
5. Consider implementing versioning for your packages

## Using Multiple Sources

The Package Manager supports multiple package sources simultaneously:

### Benefits of Multiple Sources

- Access components from different providers
- Separate internal and external components
- Test new packages before contributing them to the main repository
- Create specialized sources for different projects or teams

### Source Management Strategy

1. Keep the default source enabled for core components
2. Add specialized sources for specific needs
3. Create a personal source for testing and development
4. Refresh sources after you've pushed changes to them to get the latest components

---

**Previous**: [Adding Packages](./05-adding-packages.md) | **Next**: [Package Manager Architecture](../implementation/01-architecture.md)
