Jinni

🚀 Jinni Project Guide

Jinni is a tool designed to manage project contexts, ensuring that relevant files are included and unnecessary ones are excluded. It provides flexible rules for context management and offers solutions to common issues such as context size limitations.

🚀 Quick Start

Project Root Directory

• --root or root: Specify the root directory of the project. If not specified, the path configured in the MCP client will be used by default.
• Function: Determines which files can be included in the context and serves as the basis for all relative path calculations.

Rule Application Logic

1. Determine the Target: Jinni identifies the target directory to be processed (either provided by the user or the project root directory).
2. Override Check: If --overrides (command-line interface) or rules (MCP) is used, these rules will be used exclusively, ignoring all .contextfiles and default rules. Path matching is based on the target directory.
3. Dynamic Context Rules (No Overrides): When processing each file or subdirectory:
   • Jinni searches downward from the target directory for all .contextfiles until the directory of the current item.
   • Combines the rules found in these .contextfiles with the default rules.
   • Compiles these combined rules into a specification (PathSpec).
   • Matches the current file/subdirectory path, which is a relative path calculated based on the target directory.
4. Matching: The last pattern that matches the relative path of the current item determines its fate. ! negates the match. If no user-defined pattern matches, the item is included unless it matches the default exclusions (e.g., !.*).
5. Target Processing: Explicitly provided files bypass the rule check. Explicitly provided directories become the root for rule discovery and matching of their contents. The output path is always based on the original project_root.

💻 Usage Examples

Basic Usage

# Run the server module in the development environment
python -m jinni.serve serve --root /path/to/your/project_root

• Note: If you need to adjust the Python path, you can modify the environment variables according to your actual needs.

📚 Documentation

Context Size Error (DetailedContextSizeError)

• Problem: When the size of the included context exceeds the limit, Jinni provides a list of the 10 largest files that were attempted to be included.
• Solutions:
  1. Review the Largest Files: Check the file list in the error message. Are there large files (e.g., data files, logs, build artifacts, media) that should not be part of the LLM context?
  2. Configure Exclusions: Use .contextfiles or --overrides / rules to exclude unnecessary files or directories.
     • Example (.contextfiles): Exclude all .log files and a specific large data directory:

       # Exclude all log files
       !*.log
       
       # Exclude a large data file directory
       !large_data_files/
       

  3. Increase the Limit (Use with Caution): If all included files are necessary, you can use --size-limit-mb (command-line interface) or size_limit_mb (MCP) to increase the size limit. Be aware of the LLM context window limit and processing costs.
  4. Use jinni usage / usage: If you need to review these instructions or configuration details again, use the jinni usage command or refer to the usage documentation.

Configuration Files

• Override Rules: Use the --overrides parameter to specify the path to a custom .contextfiles file to override the default behavior.
• MCP Configuration: Set the rules attribute in the MCP client to an array containing specific paths to exclude or include.

🛠️ Troubleshooting

• Context Size Limit: When encountering issues with excessive context size, follow the steps above for troubleshooting and resolution.
• Other Issues: If you encounter any other issues not listed here, please refer to the project documentation or contact the maintenance team for assistance.