🌟 About

CodeContext AI is a powerful desktop tool for preparing your codebase to work with Large Language Models (LLMs). It scans project folders, analyzes structure, builds dependency graphs, and generates a single, perfectly structured prompt — optimized for token consumption and architectural clarity.

❓ Why?

When working with AI, developers face context window token limits — LLMs "lose" architectural coherence when code is copied in parts. CodeContext AI solves this: collect your entire project into one structured prompt in a few clicks, saving up to 80% on tokens.

---

🚀 Features

Feature	CodeContext AI	Manual
🗜️ Minify	Up to 80% token reduction — strips whitespace & blank lines	Manual copy-paste
🧩 LLM Patcher	Preview & apply JSON patches	Not available
✅ LLM Checker	Auto-verify code before saving	Not available
🔗 AST dependency graph	Python, JS/TS, Vue	File listing only
🖱️ Context menu	Windows / Linux / macOS	None
🎨 Themes	Apple, Modern, custom JSON	Fixed UI
⚙️ UI customization (v1.14+)	Premiere Pro-style	Fixed UI
🌐 i18n (v1.17+)	15 languages, system auto-detect	Single language
♻️ Dedup (v1.23+)	Detects & skips files with identical content	Manual check
⚡ Aggressive minify (v1.23+)	Extra compression — eliminates trailing whitespace on every line	Manual delete
📌 Checkpoints (v1.23+)	Save before/after snapshots for debugging	Not available
👁️ Auto-Watch (v1.23+)	Watches files & re-processes on change	Not available
🔌 Plugin System (v1.25+)	Extend with Python plugins — custom tabs, actions, and i18n	Not available
🚦 CI/CD Integration	GitHub Actions & GitLab CI — auto-generate PR context via --git-base	Not available
🌳 Monorepo Support (v1.25+)	Lerna, NX, Turborepo, pnpm workspaces — cross-package imports, root config discovery	Not available

---

📥 Installation

Prerequisites: Python 3.10+, Git

git clone https://github.com/NIKIRIKI7/CodeContext.git
cd CodeContext
python -m venv venv
# Windows:
venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate
pip install -r requirements.txt

PyPI (pip)

pip install codecontext-ai

# Then launch:
codecontext

Windows .exe

pip install pyinstaller
pyinstaller --windowed --onefile --icon=assets/images/logo.ico --name "CodeContext AI" main.py

Arch Linux (AUR)

Action	Command
Install	yay -S codecontext-ai
Search	yay -Ss codecontext
Update	yay -Syu
Remove	sudo pacman -Rns codecontext-ai

If yay is not installed:

sudo pacman -S --needed git base-devel
git clone https://aur.archlinux.org/yay.git
cd yay && makepkg -si

Alternative: paru -S codecontext-ai

---

💻 GUI Mode

python main.py

1. Interface Overview

The window is split into three zones:

• Left sidebar (tabs) — scan settings, filters, prompts, LLM config, themes
• Center area — folder list, file tree, token analytics
• Top action bar — Minify/No Comments/Skeleton toggles, output format, action buttons

2. Adding a Project

Action	How
Drag & drop	Just drag a project folder into the window
Browse dialog	Click "+ Папка ПК" on the Sources tab
GitHub repo	Click "+ GitHub / PR" — paste a repo or Pull Request URL
Save config	Click "💾 Save config" — creates .codecontextrc

GitHub loading modes:

• Save permanently — clones to a folder on your disk
• Temporary — clones to a temp folder (deleted on app close)

3. Scan Configuration

Sources Tab

Option	Description
☑ Git Changes Only	Include only files changed in the last commit
☑ Respect .gitignore	Auto-exclude files from .gitignore
🔍 Scan Files	Build the file tree with metadata

Filters Tab

Option	Description
Extension presets	Quick switch between language sets (Python, Web, Golang, Rust, C#, etc.)
Extensions	Custom file extension whitelist
Ignored paths	Skip folders/files (node_modules, .git, build, dist, etc.)
☑ Include file tree	Prepends folder structure to the prompt
☑ Include dependency map	AST-based import analysis for Python/JS/TS
☑ Include Mermaid graph	Architecture diagram in Mermaid format

💡 Saving custom presets: configure filters, click 💾, enter a name.

Prompts Tab

Option	Description
Prompt presets	Quick change of system prompt (Code Review, Bug Hunter, Refactoring, etc.)
System prompt	Custom prompt — sent to LLM as system context
🧩 Apply JSON patch	Paste LLM JSON response — preview diff and apply to disk

Using JSON patches:

1. Ask LLM for a JSON array: [{"action": "replace", "file": "main.py", "search": "...", "content": "..."}]
2. Paste JSON, click "Next" → Safety Diff Viewer opens
3. Check/uncheck files, optionally click "🤖 Check via LLM"
4. Click "💾 Save selected to disk"

4. Output Format Settings

Option	Description
☑ Minify	Trims leading/trailing whitespace on every line, removes blank lines — safe baseline compression for everyday use
☑ Aggressive	Extra minification pass — strips trailing whitespace aggressively on every line. Combine with Minify for maximum token savings when context is tight
☑ No Comments	Removes all comments from code
☑ No Secrets	Masks API keys, passwords, tokens
☑ Skeleton ☠️	Strips function bodies — maximum token savings
☑ Dedup	Scans all files and excludes duplicates with identical content — eliminates redundant context from repeated files
☑ Checkpoints	Saves intermediate processing snapshots (before/after) to disk — useful for debugging pipeline stages or comparing outputs
☑ Auto-Watch	Watches project files for changes and automatically reprocesses — keeps your prompt up-to-date during active development
Format	Markdown, XML, Plain, JSONL Chunks, Custom (Jinja2)
📁 template	Jinja2 template picker

Skeleton Mode: removes function implementations (def func_name(...): # ... implementation ...), preserving all classes — lets LLM understand massive projects with minimal tokens.

Minify vs Aggressive: Minify strips leading/trailing whitespace and removes blank lines — safe for any codebase, reduces tokens without affecting readability. Aggressive adds an extra pass that eliminates trailing whitespace on every line for maximum compression. Combine both when you need to fit more code into a limited context window.

Dedup: automatically detects files with identical content across your project and excludes duplicates from the output — prevents LLM from seeing the same code twice and wasting tokens.

Checkpoints: saves intermediate results at each pipeline stage (before cleanup, after minification, etc.) to checkpoints/ folder. Useful for debugging what each processing step does or comparing outputs side by side.

Auto-Watch: monitors your project files for changes using the OS file watcher. When a file is saved, the pipeline automatically re-runs — ideal during active development when you need continuous prompt updates.

5. Action Buttons

Button	Action
👀 Preview	Advanced Preview Dialog — "Final Prompt" + "Before/After" tabs
📋 Copy to Clipboard	Copy result — paste into ChatGPT / Claude
🚀 Send to ChatGPT / Claude	Opens web chat and pastes context
💻 Open in Editor	Opens in VS Code / Cursor
💾 Save to File	Save result to disk

6. Advanced Preview Dialog

"📝 Final Prompt" tab: file list (left) + full text with highlighting (right). Copy All / Copy File.

"🔍 Before/After" tab: colored diff between original and optimized. Counter: Before: 1500 → After: 300 (80%).

7. LLM & OS

LLM Checker
☑ Enable verification	Auto LLM patch verification before applying
URL / Key / Model	API endpoint (default OpenAI), key, model
🦙 Ollama	http://localhost:11434/v1 / llama3
🖥 LM Studio	http://localhost:1234/v1 / local-model

OS Integration
Install context menu	"Open with CodeContext AI" in right-click menu (Windows / Linux / macOS)
Add to PATH	Global codecontext CLI command
Editor	code, cursor, idea, vim

8. Themes

• Theme: Apple, Modern — Mode: light / dark
• 📂 Open themes folder / ➕ Import theme (.json)

9. 📊 Token Analytics

Table: file path, tokens (tiktoken), compression, savings %, cost for model.

10. 🎛️ UI Customization (v1.14+)

Click ⚙ next to version — "Interface Settings (Premiere Pro style)" dialog. Toggle tabs (Sources, Filters, Prompts, LLM & OS, Themes) and action buttons (Preview, Clipboard, ChatGPT, Editor, File).

11. Command Palette

Ctrl+Shift+P — mouse-free access to all actions.

12. 🔌 Plugin System (v1.25+)

CodeContext AI supports a Python plugin system that lets you extend the app with custom functionality.

📁 Plugin Structure

my_plugin/
├── manifest.json          # Plugin metadata
├── requirements.txt       # (Optional) pip dependencies
├── locales/
│   ├── en.json            # English translations
│   └── ru.json            # Russian translations
└── plugin.py              # Entry point

📄 manifest.json

{
  "id": "my_plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "description": "Does something useful",
  "entry_point": "plugin"
}

🐍 plugin.py (Example)

from src.services.plugin_manager import IPlugin
class MyPlugin(IPlugin):
id = "my_plugin"
name = "My Plugin"
version = "1.0.0"
def on_init(self, controller: MainController) -> None:
    # Add translations from locales/ folder (auto-loaded)
    # Register a sidebar tab
    api.ui.register_sidebar_tab(
        "my_tab", "My Tab",
        lambda: QLabel("Hello from plugin!")
    )
    # Register an action button
    api.ui.register_action_button(
        "my_action", "My Action",
        lambda: api.add_log("Plugin action clicked")
    )
    api.add_log("My Plugin initialized")

def on_shutdown(self) -> None:
    pass</pre>

🔐 Security

Plugins get full Python access — only install from trusted sources
On first load, a security dialog asks your approval before enabling a plugin
If requirements.txt exists, you'll see a live pip install log before loading
Approved plugins are remembered in settings (approved_plugins)

🛠 Plugin API

Property / Method
Description

api.ui.register_sidebar_tab(id, label, factory)
Add a tab to the left sidebar
api.ui.register_action_button(id, label, callback)
Add a button to the "Plugins 🔽" dropdown
api.add_log(message)
Write to the app log panel


⚙️ Visibility
Plugin tabs and action buttons can be toggled via ⚙ UI Customization — they appear alongside built-in tabs/actions with their own checkboxes.

💻 CLI Mode
python main.py --cli --path /path/to/project [options]
python main.py --help

Parameter
Type
Description
Example

--cli
flag
CLI mode (no GUI)
--cli
--path
list
Project path
--path ./app
--ext
str
Extensions
--ext ".py .js"
--ignore
str
Ignored paths
--ignore "node_modules"
--mode
enum
none / default / shallow / deep
--mode deep
--format
enum
markdown / xml / plain / jsonl_chunk
--format xml
--minify
flag
Enable minification
--minify
--no-comments
flag
Strip comments
--no-comments
--no-secrets
flag
Mask secrets
--no-secrets
--skeleton
flag
Skeleton mode
--skeleton
--output
str
Output file
--output out.txt
--stdout
flag
Print to stdout
--stdout
--git
flag
Git changes only
--git
--git-base
str
Base branch for git diff in CI/CD
--git-base origin/main
--gitignore
flag
Respect .gitignore
--gitignore
--tree
flag
File tree
--tree
--mermaid
flag
Mermaid graph
--mermaid
--dependencies
flag
Dependency map
--dependencies
--patch
str
LLM JSON patch
--patch patch.json
--template
str
Jinja2 template
--template my.j2
--system-prompt
str
Custom system prompt
--system-prompt "Review"


Examples
# Minimal run
python main.py --cli --path ./myapp --stdout
Full analysis with XML
python main.py --cli --path ./myapp --ext ".py .js .ts" --ignore "node_modules,.git,pycache" --mode deep --mermaid --tree --dependencies --minify --no-comments --skeleton --format xml --output analysis.xml
Git diff
python main.py --cli --path ./myapp --git --gitignore --stdout
LLM JSON patch
python main.py --cli --path ./myapp --patch llm_response.json
Custom Jinja2 template
python main.py --cli --path ./myapp --template my.j2 --stdout
Mermaid diagram
python main.py --cli --path ./myapp --mode deep --mermaid --output with_mermaid.md
Multiple paths
python main.py --cli --path ./frontend ./backend --format xml --output combined.xml
CI/CD — diff against base branch
python main.py --cli --path . --git --git-base origin/main --minify true --stdout


🚦 CI/CD Integration
CodeContext AI can be integrated into your CI/CD pipelines to automatically generate a lean context of the files changed in a Pull/Merge Request and post it as a PR comment — no more manual copy-pasting for code review.
How it works
Normally --git runs git diff HEAD, which is useless in CI (HEAD is a merge commit).

The --git-base flag tells CodeContext to diff against a real branch instead:
git diff origin/main --name-only
Only the files modified in the PR are scanned, minified, and assembled into a prompt.
GitHub Actions
Create .github/workflows/codecontext-pr.yml:
name: 🧠 Generate PR Context
on:
pull_request:
types: [opened, synchronize, reopened]
permissions:
pull-requests: write
contents: read
jobs:
codecontext-analysis:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-python@v5
with:
python-version: "3.11"
- name: Install CodeContext AI
run: pip install codecontext-ai
- name: Generate PR Context
run: |
codecontext --cli --path . --git 

--git-base "origin/${{ github.base_ref }}" 

--format markdown --minify true 

--no-comments true --stdout > pr_context.md
- name: Comment on PR
if: hashFiles('pr_context.md') != ''
uses: actions/github-script@v7
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
script: |
const fs = require('fs');
let ctx = fs.readFileSync('pr_context.md', 'utf8').slice(0, 60000);
await github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: &lt;details&gt;\n&lt;summary&gt;&lt;b&gt;CodeContext AI: PR Context&lt;/b&gt;&lt;/summary&gt;\n\n\``markdown\n${ctx}\n```\n</details>`
});

GitLab CI
Add to .gitlab-ci.yml. Requires a GITLAB_API_TOKEN variable with api scope.
codecontext_pr_analysis:
  stage: test
  image: python:3.11-slim
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  before_script:
    - apt-get update && apt-get install -y git curl jq
    - pip install codecontext-ai
    - git fetch origin $CI_MERGE_REQUEST_TARGET_BRANCH_NAME
  script:
    - codecontext --cli --path . --git
        --git-base "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
        --format markdown --minify true --no-comments true --stdout > mr_context.md
    - |
      CONTENT=$(cat mr_context.md | sed 's/\\/\\\\/g' | sed 's/"/\\"/g' | awk '{printf "%s\\n", $0}')
      JSON=$(jq -n --arg body "<details><summary><b>CodeContext AI: PR Context</b></summary>\n\n\`\`\`markdown\n${CONTENT}\n\`\`\`\n</details>" '{body: $body}')
      curl --request POST --header "PRIVATE-TOKEN: $GITLAB_API_TOKEN" \
           --header "Content-Type: application/json" --data "$JSON" \
           "$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes"
See docs/CI_CD.md for detailed setup instructions.

🏗️ Tech Stack

Component
Technology

Language
Python 3.10+
GUI Framework
PySide6 (Qt 6)
Architecture
Clean Architecture
Tokenization
tiktoken (OpenAI)
Templating
jinja2 (11 built-in)
AST parsers
ast (Python), tree-sitter (JS/TS/Go/Rust)
Distribution
PyInstaller, AUR



🗺️ Roadmap

📚 RAG (Retrieval-Augmented Generation) mode — indexing massive codebases using local vector DB (Chroma/FAISS).
🚫 Deep .gitignore parsing — support for nested .gitignore files & global ~/.gitignore.
☁️ Cloud Sync — sync presets & configurations via GitHub Gists.
🌳 Multi-root Workspaces — improved monorepo support (Lerna, NX, Turborepo). ✅
🚀 CI/CD Pipelines — GitHub Actions & GitLab CI plugins for automated PR context generation.
🤖 Direct OpenAI/Anthropic API integration — complete the bridge from prompt generation to direct output.
🔌 Plugin system ✅


👨‍💻 Team
Developer: mcniki · VK: gor_niki · Issues & PRs on GitHub

🤝 Contributing

Fork the repository
Branch: git checkout -b feature/AmazingFeature
Commit: git commit -m 'Add AmazingFeature'
Push: git push origin feature/AmazingFeature
Pull Request

Follow SOLID principles (see docs/ARCHITECTURE.md).

📄 License
MIT. See LICENSE for details.