Shelf CLI

shelf is a command-line interface (CLI) utility designed to help developers manage the context provided to the Gemini CLI. It allows you to declaratively control which files are ignored, ensuring that Gemini loads the correct files into memory on startup and focuses on the most relevant parts of your codebase.

After enabling a profile with shelf, you can verify that the correct files are in scope by running the /memory list command within the Gemini CLI.

How it Works

shelf works by modifying your project's .geminiignore file. Based on the active profile, it generates rules to ignore everything by default, and then adds specific exceptions for the files and directories you want to include.

This allows you to precisely control the context Gemini uses.

Verifying the Active Context

After you enable a profile, you should restart your Gemini CLI session. You can then verify which files have been loaded into memory by running:

/memory list

This command will show you the list of GEMINI.md files and other resources that Gemini is actively using, allowing you to confirm that your profile has been applied correctly.

Project Goal

To provide a robust, ergonomic CLI tool in Rust that enables developers to quickly scope the Gemini CLI's context. By managing the .geminiignore file, shelf ensures that only relevant project files are loaded into memory, improving the accuracy of suggestions and reducing noise from unrelated code.

Core Functionality: Declarative Profiles

The tool's behavior is defined by a YAML configuration file, .shelf.yaml, located in the project root. This file defines named "profiles" that specify which files to include or exclude from the LLM's context.

.shelf.yaml Configuration Structure

• global (Optional): A top-level key for patterns that should be included or excluded from the context regardless of the active profile. It can contain includes and excludes.
• <profile_name>: A unique name for a context profile (e.g., frontend, backend).
  • description (Optional): A short, human-readable description of the profile's purpose.
  • includes: A list of directories or files to be included in the context.
  • excludes: A list of directories or files to be excluded, which can override patterns in the includes list.

Example .shelf.yaml

# Global includes and exclusions apply to all profiles.
global:
  includes:
    - '.ai/'
    - 'docs/'
  excludes:
    - '**/tmp/'
    - '*.log'
    - 'legacy/'
    - '**/node_modules/'
    - '**/.DS_Store'
    - '**/target/'
    - '**/*.pyc'
    - '**/__pycache__/'

# Profile for backend development on all services
backend:
  description: "Focus on all backend services."
  includes:
    - 'services/'
    - 'packages/api-client/'
    - '.gitlab-ci.yml'
  excludes:
    - 'services/*/tests/frontend/'

# Profile for working on just the main frontend application
frontend:
  description: "Scope to the main web application and its shared UI components."
  includes:
    - 'web/main-app/'
    - 'packages/ui-components/'
  excludes:
    - 'web/main-app/dist/'

# Profile for a full-stack developer working on a specific feature
feature-slice:
  description: "Full-stack context for a feature (orders service and main app)."
  includes:
    - 'services/order-service/'
    - 'web/main-app/'
    - 'packages/'
  excludes:
    - 'services/order-service/tmp/'

# Profile for technical writers
tech-docs:
  description: "Context for writing documentation."
  includes:
    - 'docs/'
    - 'database/schema.sql'
    - 'README.md'

CLI Specification

shelf list

Lists all available profiles defined in .shelf.yaml.

Usage:

shelf list

Output:

Available profiles:
• backend      : Focus on all backend services.
• feature-slice: Full-stack context for a feature (orders service and main app).
• frontend     : Scope to the main web application and its shared UI components.
• tech-docs    : Context for writing documentation.

shelf status

Shows the currently active profile and any user-defined patterns in .geminiignore.

Usage:

shelf status

Output (Profile Active with User Patterns):

Profile 'frontend' is active.

User-defined patterns:
• .env
• *.swo

Output (No Profile Active, with User Patterns):

No shelf profile is active.

User-defined patterns:
• .env
• *.swo

Output (No Profile Active, No User Patterns):

No shelf profile is active.

Output (No .geminiignore file):

No .geminiignore file found.

shelf enable <profile_name>

Activates a profile, modifying the .geminiignore file to reflect the profile's include and exclude rules.

Usage:

shelf enable frontend

Output:

✔ Activated profile 'frontend'. .geminiignore updated.

shelf disable

Deactivates any active profile by clearing the shelf-managed block in the .geminiignore file.

Usage:

shelf disable

Output:

✔ All shelf profiles disabled. .geminiignore updated.

Installation

If you have the Rust toolchain installed, you can install shelf from source:

git clone https://github.com/your-username/shelf.git
cd shelf
cargo install --path .

Development

Contributions are welcome! Here's how to get started:

Getting Started

1. Clone the repository:

   git clone https://github.com/your-username/shelf.git
   cd shelf

2. Build the project:

   cargo build

Running Tests

To run the test suite:

cargo test

Code Style

This project uses rustfmt for code formatting and clippy for linting. Please ensure your code is formatted and free of linting errors before submitting a pull request.

cargo fmt
cargo clippy -- -D warnings

Pull Requests

We welcome pull requests. Please make sure your PR includes:

• A clear description of the changes.
• Tests for any new features or bug fixes.
• Updated documentation if applicable.