contextr

Name	contextr JSON
Version	1.1.0 JSON
	download
home_page	None
Summary	Share your codebase with LLMs - codebase export tool for AI conversations
upload_time	2025-07-26 00:58:22
maintainer	None
docs_url	None
author	None
requires_python	>=3.12
license	MIT
keywords	llm ai codebase clipboard context
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # contextr (ctxr)

A streamlined command-line tool designed for developers to easily share their codebase with Large Language Models (LLMs). contextr helps you monitor specific files and directories, intelligently handles ignore patterns, and lets you instantly export formatted code context to your clipboard - perfect for pasting into ChatGPT, Claude, or other AI chat interfaces.

Think of it as "git add" but for AI conversations - select the files you want your AI assistant to see, and export them in a Markdown format optimized for LLM comprehension.

## Features

- **🔍 Smart File Selection**: Watch specific file patterns and automatically track changes
- **🚫 Git-Style Ignores**: Full support for ignore patterns including negation with `!`
- **📋 One-Click Export**: Sync changes and copy formatted context to clipboard instantly
- **🎨 LLM-Optimized Output**: Markdown formatting with syntax highlighting for 40+ languages
- **💾 Context Profiles**: Save and instantly switch between different context configurations
- **🔄 Auto-Sync**: Automatically detect when watched files are added or removed
- **🌐 Cross-Platform**: Works seamlessly on Linux, macOS, and Windows
- **🔗 Path Intelligence**: Handles symlinks, `~` expansion, and environment variables
- **🤖 Modern Development**: Type-safe code with 62% test coverage and strict linting

## Installation

### Method 1: Install from PyPI (Recommended)

The easiest way to install (requires Python 3.12+):

```bash
pip install contextr
```

This makes both `ctxr` (short alias) and `contextr` commands available globally.

### Method 2: Install from source

```bash
# Clone the repository
git clone https://github.com/your-username/contextr.git
cd contextr

# Install using uv (recommended for development)
uv sync --extra dev

# Or install with pip
pip install -e .
```

## Quick Start

```bash
# Initialize contextr in your project
ctxr init

# Add files to watch (supports glob patterns)
ctxr watch "src/**/*.py" "docs/*.md" "*.yaml"

# Ignore test files and build artifacts
ctxr ignore "**/__pycache__/**" "**/node_modules/**" "*.pyc"

# Sync watched files and copy to clipboard
ctxr sync

# Paste into your favorite LLM and start coding!
```

## Core Commands

### File Selection & Monitoring

- **`watch <patterns>`** - Add file patterns to monitor
  ```bash
  ctxr watch "src/**/*.py" "tests/**/*.py" "*.md"
  ```

- **`unwatch <patterns>`** - Remove patterns from watch list
  ```bash
  ctxr unwatch "tests/**"
  ```

- **`watch-list`** - Display all watched patterns
  ```bash
  ctxr watch-list
  ```

- **`list`** - Show current file context as a tree
  ```bash
  ctxr list
  ```

### Context Management

- **`sync`** - Refresh context from watched files and export to clipboard
  ```bash
  ctxr sync
  ```

- **`init`** - Initialize contextr in current directory
  ```bash
  ctxr init
  ```

### Ignore Patterns

- **`ignore <pattern>`** - Add pattern to ignore list
  ```bash
  ctxr ignore "**/*.log" "build/**"
  ```

- **`unignore <pattern>`** - Remove pattern from ignore list
  ```bash
  ctxr unignore "**/*.log"
  ```

- **`ignore-list`** - Show all ignored patterns
  ```bash
  ctxr ignore-list
  ```

- **`gitignore-sync`** - Import patterns from .gitignore
  ```bash
  ctxr gitignore-sync
  ```

## Advanced Usage

### Pattern Examples

contextr supports standard glob patterns and git-style ignore syntax:

```bash
# Watch all Python files
ctxr watch "**/*.py"

# Watch specific directories
ctxr watch "src/" "lib/" "tests/"

# Watch with multiple extensions
ctxr watch "**/*.{js,jsx,ts,tsx}"

# Ignore patterns with negation
ctxr ignore "**/*.test.py"    # Ignore all test files
ctxr ignore "!important.test.py"  # But include this specific test
```

### Context Profiles

Save and instantly switch between different context configurations:

```bash
# Save current context as a profile
ctxr profile save backend --description "Backend API development"

# Load a saved profile
ctxr profile load backend

# List all saved profiles
ctxr profile list

# Delete a profile
ctxr profile delete backend
```

## Output Format

contextr generates clean, LLM-friendly Markdown output:

```markdown
# Project Context: your-project
Files selected: 5

## File Structure
```
src/
├── main.py
├── utils/
│   ├── helpers.py
│   └── config.py
└── models/
    └── user.py
README.md
```

## File Contents

### src/main.py
```python
# Your code here with proper syntax highlighting
```

### src/utils/helpers.py
```python
# More code with language detection
```
```

## How It Works

1. **Pattern Matching**: Uses glob patterns to match files, with full support for `**` recursive matching
2. **Ignore System**: Implements git-style ignore rules including directory-specific patterns and negation
3. **File Detection**: Automatically detects programming languages for syntax highlighting
4. **Smart Formatting**: Escapes code blocks properly to prevent Markdown rendering issues
5. **Clipboard Integration**: Uses pyperclip for cross-platform clipboard support

## Configuration

contextr stores its configuration in a `.contextr/` directory in your project:

- `.contextr/state.json` - Current context state and watched patterns
- `.contextr/.ignore` - Custom ignore patterns
- `.contextr/states/` - Saved named states (coming soon)

## Development

```bash
# Install development dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Type checking
uv run pyright

# Linting and formatting
uv run ruff check .
uv run ruff format .
```

## Why Use contextr?

**For Developers:**
- 🚀 Save time by automating code context preparation
- 🎯 Ensure you include all relevant files for LLM understanding
- 🔄 Keep context updated as your code changes
- 📦 Manage different contexts for different features/discussions

**For LLMs:**
- 📝 Consistent, well-formatted code presentation
- 🗂️ Clear file structure visualization
- 🏷️ Proper syntax highlighting for better comprehension
- 📍 Complete file paths for precise references

## Requirements

- Python >= 3.12
- Cross-platform: Linux, macOS, Windows

## License

MIT License

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Roadmap

- [x] Context Profiles - Save and switch between different contexts
- [ ] Profile templates for common project types
- [ ] Interactive file selection mode
- [ ] Custom output templates
- [ ] Integration with popular IDEs
- [ ] Direct LLM API integration
- [ ] Context size optimization
- [ ] Team profile sharing

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "contextr",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.12",
    "maintainer_email": null,
    "keywords": "llm, ai, codebase, clipboard, context",
    "author": null,
    "author_email": "Nathan Luo <nathanluo13@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/95/d6/39b798f88aaf9856d04205a94519421b72512879d6efea72eed1e67155f4/contextr-1.1.0.tar.gz",
    "platform": null,
    "description": "# contextr (ctxr)\n\nA streamlined command-line tool designed for developers to easily share their codebase with Large Language Models (LLMs). contextr helps you monitor specific files and directories, intelligently handles ignore patterns, and lets you instantly export formatted code context to your clipboard - perfect for pasting into ChatGPT, Claude, or other AI chat interfaces.\n\nThink of it as \"git add\" but for AI conversations - select the files you want your AI assistant to see, and export them in a Markdown format optimized for LLM comprehension.\n\n## Features\n\n- **\ud83d\udd0d Smart File Selection**: Watch specific file patterns and automatically track changes\n- **\ud83d\udeab Git-Style Ignores**: Full support for ignore patterns including negation with `!`\n- **\ud83d\udccb One-Click Export**: Sync changes and copy formatted context to clipboard instantly\n- **\ud83c\udfa8 LLM-Optimized Output**: Markdown formatting with syntax highlighting for 40+ languages\n- **\ud83d\udcbe Context Profiles**: Save and instantly switch between different context configurations\n- **\ud83d\udd04 Auto-Sync**: Automatically detect when watched files are added or removed\n- **\ud83c\udf10 Cross-Platform**: Works seamlessly on Linux, macOS, and Windows\n- **\ud83d\udd17 Path Intelligence**: Handles symlinks, `~` expansion, and environment variables\n- **\ud83e\udd16 Modern Development**: Type-safe code with 62% test coverage and strict linting\n\n## Installation\n\n### Method 1: Install from PyPI (Recommended)\n\nThe easiest way to install (requires Python 3.12+):\n\n```bash\npip install contextr\n```\n\nThis makes both `ctxr` (short alias) and `contextr` commands available globally.\n\n### Method 2: Install from source\n\n```bash\n# Clone the repository\ngit clone https://github.com/your-username/contextr.git\ncd contextr\n\n# Install using uv (recommended for development)\nuv sync --extra dev\n\n# Or install with pip\npip install -e .\n```\n\n## Quick Start\n\n```bash\n# Initialize contextr in your project\nctxr init\n\n# Add files to watch (supports glob patterns)\nctxr watch \"src/**/*.py\" \"docs/*.md\" \"*.yaml\"\n\n# Ignore test files and build artifacts\nctxr ignore \"**/__pycache__/**\" \"**/node_modules/**\" \"*.pyc\"\n\n# Sync watched files and copy to clipboard\nctxr sync\n\n# Paste into your favorite LLM and start coding!\n```\n\n## Core Commands\n\n### File Selection & Monitoring\n\n- **`watch <patterns>`** - Add file patterns to monitor\n  ```bash\n  ctxr watch \"src/**/*.py\" \"tests/**/*.py\" \"*.md\"\n  ```\n\n- **`unwatch <patterns>`** - Remove patterns from watch list\n  ```bash\n  ctxr unwatch \"tests/**\"\n  ```\n\n- **`watch-list`** - Display all watched patterns\n  ```bash\n  ctxr watch-list\n  ```\n\n- **`list`** - Show current file context as a tree\n  ```bash\n  ctxr list\n  ```\n\n### Context Management\n\n- **`sync`** - Refresh context from watched files and export to clipboard\n  ```bash\n  ctxr sync\n  ```\n\n- **`init`** - Initialize contextr in current directory\n  ```bash\n  ctxr init\n  ```\n\n### Ignore Patterns\n\n- **`ignore <pattern>`** - Add pattern to ignore list\n  ```bash\n  ctxr ignore \"**/*.log\" \"build/**\"\n  ```\n\n- **`unignore <pattern>`** - Remove pattern from ignore list\n  ```bash\n  ctxr unignore \"**/*.log\"\n  ```\n\n- **`ignore-list`** - Show all ignored patterns\n  ```bash\n  ctxr ignore-list\n  ```\n\n- **`gitignore-sync`** - Import patterns from .gitignore\n  ```bash\n  ctxr gitignore-sync\n  ```\n\n## Advanced Usage\n\n### Pattern Examples\n\ncontextr supports standard glob patterns and git-style ignore syntax:\n\n```bash\n# Watch all Python files\nctxr watch \"**/*.py\"\n\n# Watch specific directories\nctxr watch \"src/\" \"lib/\" \"tests/\"\n\n# Watch with multiple extensions\nctxr watch \"**/*.{js,jsx,ts,tsx}\"\n\n# Ignore patterns with negation\nctxr ignore \"**/*.test.py\"    # Ignore all test files\nctxr ignore \"!important.test.py\"  # But include this specific test\n```\n\n### Context Profiles\n\nSave and instantly switch between different context configurations:\n\n```bash\n# Save current context as a profile\nctxr profile save backend --description \"Backend API development\"\n\n# Load a saved profile\nctxr profile load backend\n\n# List all saved profiles\nctxr profile list\n\n# Delete a profile\nctxr profile delete backend\n```\n\n## Output Format\n\ncontextr generates clean, LLM-friendly Markdown output:\n\n```markdown\n# Project Context: your-project\nFiles selected: 5\n\n## File Structure\n```\nsrc/\n\u251c\u2500\u2500 main.py\n\u251c\u2500\u2500 utils/\n\u2502   \u251c\u2500\u2500 helpers.py\n\u2502   \u2514\u2500\u2500 config.py\n\u2514\u2500\u2500 models/\n    \u2514\u2500\u2500 user.py\nREADME.md\n```\n\n## File Contents\n\n### src/main.py\n```python\n# Your code here with proper syntax highlighting\n```\n\n### src/utils/helpers.py\n```python\n# More code with language detection\n```\n```\n\n## How It Works\n\n1. **Pattern Matching**: Uses glob patterns to match files, with full support for `**` recursive matching\n2. **Ignore System**: Implements git-style ignore rules including directory-specific patterns and negation\n3. **File Detection**: Automatically detects programming languages for syntax highlighting\n4. **Smart Formatting**: Escapes code blocks properly to prevent Markdown rendering issues\n5. **Clipboard Integration**: Uses pyperclip for cross-platform clipboard support\n\n## Configuration\n\ncontextr stores its configuration in a `.contextr/` directory in your project:\n\n- `.contextr/state.json` - Current context state and watched patterns\n- `.contextr/.ignore` - Custom ignore patterns\n- `.contextr/states/` - Saved named states (coming soon)\n\n## Development\n\n```bash\n# Install development dependencies\nuv sync --extra dev\n\n# Run tests\nuv run pytest\n\n# Type checking\nuv run pyright\n\n# Linting and formatting\nuv run ruff check .\nuv run ruff format .\n```\n\n## Why Use contextr?\n\n**For Developers:**\n- \ud83d\ude80 Save time by automating code context preparation\n- \ud83c\udfaf Ensure you include all relevant files for LLM understanding\n- \ud83d\udd04 Keep context updated as your code changes\n- \ud83d\udce6 Manage different contexts for different features/discussions\n\n**For LLMs:**\n- \ud83d\udcdd Consistent, well-formatted code presentation\n- \ud83d\uddc2\ufe0f Clear file structure visualization\n- \ud83c\udff7\ufe0f Proper syntax highlighting for better comprehension\n- \ud83d\udccd Complete file paths for precise references\n\n## Requirements\n\n- Python >= 3.12\n- Cross-platform: Linux, macOS, Windows\n\n## License\n\nMIT License\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Roadmap\n\n- [x] Context Profiles - Save and switch between different contexts\n- [ ] Profile templates for common project types\n- [ ] Interactive file selection mode\n- [ ] Custom output templates\n- [ ] Integration with popular IDEs\n- [ ] Direct LLM API integration\n- [ ] Context size optimization\n- [ ] Team profile sharing\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Share your codebase with LLMs - codebase export tool for AI conversations",
    "version": "1.1.0",
    "project_urls": {
        "Bug Tracker": "https://github.com/nathan-luo/contextr/issues",
        "Homepage": "https://github.com/nathan-luo/contextr"
    },
    "split_keywords": [
        "llm",
        " ai",
        " codebase",
        " clipboard",
        " context"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "8b04f1408af32e7b00394393a5a11848f8d60ab2b108288368ee4509fa0a750d",
                "md5": "5948718f7c83be36412254d41ac4c372",
                "sha256": "abeb7d5f3b13cc94922897c9a2595f612fddba38b653d244767c6b2d8b94032e"
            },
            "downloads": -1,
            "filename": "contextr-1.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "5948718f7c83be36412254d41ac4c372",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.12",
            "size": 23639,
            "upload_time": "2025-07-26T00:58:21",
            "upload_time_iso_8601": "2025-07-26T00:58:21.704750Z",
            "url": "https://files.pythonhosted.org/packages/8b/04/f1408af32e7b00394393a5a11848f8d60ab2b108288368ee4509fa0a750d/contextr-1.1.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "95d639b798f88aaf9856d04205a94519421b72512879d6efea72eed1e67155f4",
                "md5": "d86f61b888cc687139489632d4385b5c",
                "sha256": "99da113db1030a55c0ddd43aa669e407fad29f29046edd6d4ca6b6c7dc0a7e35"
            },
            "downloads": -1,
            "filename": "contextr-1.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "d86f61b888cc687139489632d4385b5c",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.12",
            "size": 22632,
            "upload_time": "2025-07-26T00:58:22",
            "upload_time_iso_8601": "2025-07-26T00:58:22.735451Z",
            "url": "https://files.pythonhosted.org/packages/95/d6/39b798f88aaf9856d04205a94519421b72512879d6efea72eed1e67155f4/contextr-1.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-26 00:58:22",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "nathan-luo",
    "github_project": "contextr",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "contextr"
}