Jinni

Jinni uses .contextfiles to include or exclude files and directories during context generation. These files use .gitignore-style (gitwildmatch) syntax.

Key Rules:

• Inclusion: By default, files are included unless matched by an exclusion pattern.
• Exclusion: Use ! at the start of a pattern to exclude a file or directory (e.g., !*.tmp).
• Anchoring: A leading / anchors the pattern to the directory containing the .contextfiles.
• Directories: A trailing / indicates the pattern applies only to directories (e.g., build/).
• Recursion: ** matches zero or more directories (e.g., src/**/*.py).
• Comments: Lines starting with # are ignored.

Rules are applied dynamically: Jinni searches for .contextfiles and .gitignore files from the project root down to the current directory being processed. Rules from higher-level directories are applied before rules in the current directory.

# Include all Python files in the src directory and subdirectories
src/**/*.py

# Include all Markdown files anywhere
*.md

# Exclude temporary files anywhere, even if they are .py or .md
!*.tmp

# Include the specific config file at the root of this context
/config.yaml

# Exclude the entire build directory relative to this file
build/

The ExclusionParser class converts high-level exclusion directives (like keywords or scoped rules) into pathspec patterns used for file traversal. It supports four main types of exclusions:

1. Global Exclusions (--not): Excludes files/directories based on keywords (e.g., tests, build, logs). If a keyword is recognized as a common module pattern, it expands to a set of standard patterns. If not recognized, it generates general patterns to match the keyword at various depths.
2. Scoped Exclusions (--not-in): Excludes specific keywords only within a defined scope (e.g., src:legacy excludes legacy patterns only inside the src/ directory).
3. File Pattern Exclusions (--not-files): Excludes specific file patterns (e.g., *.log). If no path separator is provided, the parser ensures the pattern matches at any depth.
4. Keep Only (--keep-only): The most restrictive mode. It excludes everything (!*) and then explicitly includes only the specified modules.

To use the parser during directory traversal, you must retain the ExclusionParser instance to call get_scoped_patterns for each directory encountered.

from jinni.exclusion_parser import create_exclusion_patterns

# Create patterns and the parser instance
patterns, parser = create_exclusion_patterns(
    not_keywords=["tests", "logs"],
    not_in_scoped=["src:experimental"],
    not_files=["*.tmp"]
)

# 'patterns' contains the global and file-based exclusion pathspecs
# 'parser' is used during traversal to handle scoped exclusions

Jinni provides an MCP (Model Context Protocol) server that exposes two primary tools to AI models (like Cursor or Claude): usage and read_context. These tools allow an AI to retrieve project documentation and read relevant code files to build context for development tasks.

usage tool

Returns the essential Jinni usage documentation, including rules and .contextfiles information. Use this when you are unsure of the rule syntax or how to configure Jinni.

read_context tool

Generates a concatenated view of relevant code files. It is designed to provide a 'canonical context' by focusing on files typically tracked in version control while respecting exclusions.

Key behaviors for AI models:

• Default Behavior: If rules is provided as an empty list [], Jinni uses sensible defaults (excluding .git, node_modules, etc.) and project-specific .contextfiles.
• Targeting: Providing a specific list of files in targets is more efficient than reading the entire project.
• Mandatory Arguments: project_root must be an absolute path.

// Example tool call for read_context
{
  "project_root": "/Users/username/projects/my-app",
  "targets": ["src/main.py", "README.md"],
  "rules": []
}

The jinni MCP Server provides the read_context tool to generate a concatenated view of relevant code files. This is useful for providing context to AI agents via the Model Context Protocol.

Input Parameters:

• project_root (string, required): Absolute path to the project root. Rule discovery and output paths are relative to this.
• targets (JSON array of strings, required): Paths within project_root to process (e.g., ["src/main.py", "docs/"]). An empty list [] processes the entire project_root.
• rules (JSON array of strings, required): Inline filtering rules (e.g., ["*.ts", "!*.test.ts"]). Note: If non-empty, these rules are used exclusively, ignoring built-in defaults and .contextfiles.
• list_only (boolean, optional): If true, only returns file paths.
• size_limit_mb (integer, optional): Overrides the default context size limit.
• debug_explain (boolean, optional): Enables debug logging to stderr.