Deutsch | English

CodeBox is a local-first desktop IDE for Windows, Linux, and macOS developers who want a lightweight PySide6 code editor with multi-tab workspace, project tree, integrated terminal, Git status porcelain indicators, syntax highlighting, Language Server Protocol (LSP) diagnostics, and an extensible JSON/Python language plugin architecture.

• Start Here
• System Architecture
• End-to-End Workflow Lifecycle
• Key Capabilities & Runtime Invariants
• Visual Showcase
• Features
• Installation & Quickstart
• Language Server Protocol (LSP) Setup
• Declarative Plugin System
• Local Windows Build
• Project Structure
• Sibling Ecosystem
• Search & Disambiguation
• Security & Privacy
• License & Liability

flowchart TD
    subgraph UI ["Desktop UI Layer (PySide6)"]
        MW["MainWindow (ui/main_window.py)"]
        TB["ToolBar & Action Dispatcher"]
        ST["StatusBar & Position/Encoding/Language"]
        MW --> TB
        MW --> ST
    end

    subgraph Core ["Editor Core & Tab Management"]
        Tabs["TabWidget (core/tabs.py)"]
        Ed["CodeEditor & UniversalHighlighter (core/highlighter.py)"]
        MM["Minimap Widget (core/minimap.py)"]
        BM["BracketMatcher (core/bracket_matcher.py)"]
        Tabs --> Ed
        Ed --> MM
        Ed --> BM
    end

    subgraph Workspace ["Workspace & Project Tree"]
        PT["ProjectTree & FilterProxy (features/project_tree.py)"]
        Git["Git Porcelain Status Resolver (features/git_status.py)"]
        PT --> Git
    end

    subgraph Diagnostics ["Language Server & Diagnostics Engine"]
        LSPMgr["LSPManager & Client Thread (features/lsp_manager.py)"]
        Linter["Background Linter (Ruff/flake8/ESLint) (features/linter.py)"]
        Prob["ProblemsPanel (ui/problems_panel.py)"]
        LSPMgr --> Prob
        Linter --> Prob
    end

    subgraph Runtime ["Execution & Extensibility"]
        Term["Integrated Terminal QProcess (features/terminal.py)"]
        Out["OutputPanel Process Runner (core/output.py)"]
        PluginMgr["PluginManager (features/plugin_manager.py)"]
        Decl["Declarative Providers (languages/declarative.py)"]
        Theme["ThemeManager (features/theme_manager.py)"]
        PluginMgr --> Decl
    end

    MW --> Tabs
    MW --> PT
    MW --> Diagnostics
    MW --> Term
    MW --> Out
    MW --> PluginMgr
    MW --> Theme

sequenceDiagram
    autonumber
    actor Dev as Developer
    participant UI as MainWindow
    participant Ed as CodeEditor (Tabs)
    participant Linter as Background Linter
    participant LSP as LSP Client Thread
    participant Prob as ProblemsPanel
    participant Term as Terminal / Runner

    Dev->>UI: Launch CodeBox & Open File
    UI->>Ed: Load Buffer & Attach UniversalHighlighter
    Ed-->>Dev: Render Syntax Highlighting & Line Numbers

    Dev->>Ed: Edit Code & Save (Ctrl+S)
    Ed->>Linter: Dispatch non-blocking lint trigger
    Ed->>LSP: Notify textDocument/didSave

    par Background Diagnostics
        Linter->>Linter: Execute Ruff / flake8 / ESLint (subprocess)
        Linter-->>Prob: Update Linter Diagnostics
    and Language Server Analysis
        LSP->>LSP: Query Language Server (pylsp / clangd / rust-analyzer)
        LSP-->>Prob: Update LSP Diagnostic Markers
    end

    Prob-->>UI: Aggregate Findings & Highlight Errors
    UI-->>Dev: Display in Problems Panel & Status Bar

    opt Run Code in Terminal / Output
        Dev->>UI: Trigger Run (F5)
        UI->>Term: Spawn QProcess (cmd/powershell/bash)
        Term-->>Dev: Stream Output & Error Codes
    end

Figure 1: CodeBox desktop interface featuring the project navigation tree, multi-tab editor with syntax highlighting, integrated terminal, and diagnostics panel.

• Rich Syntax Highlighting: Pre-configured highlighting for Python, JavaScript, TypeScript, C++, Rust, Go, and Java with punctuation-safe word boundary matching.
• Declarative Plugin Architecture: Create and extend language definitions in seconds using clean JSON schemas (plugins/, ~/.codebox/plugins/).
• Interactive Management Dialogs: Full GUI dialogs for managing language plugins (Ctrl+Shift+P) and reviewing keyboard shortcuts (F1).
• Integrated Terminal: Embedded native shell with command history, output streaming, and automatic directory synchronization.
• Project File Tree: Tree view with proxy search filtering, context actions, and Git porcelain status badges.
• Multi-Tab Workspace: Drag-and-drop tab reordering, save-failure protection, and absolute path tooltips.
• Minimap Preview & Navigation: Synchronized minimap overview, bracket auto-pairing, and go-to-line navigation (Ctrl+G).
• Dual Theme System: Seamless light/dark palette switching powered by features/theme_manager.py.
• LSP Diagnostics & Completion: Asynchronous background queries providing real-time diagnostics and code completions.
• Automated Linters: On-save Ruff, flake8, and ESLint integration piped directly to the unified Problems Panel.

# Clone the repository
git clone https://github.com/dev-bricks/CodeBox.git
cd CodeBox

# Install runtime dependencies
pip install -r requirements.txt

# Launch CodeBox
python main.py

On Windows, you can also launch CodeBox by double-clicking start.bat.

• Python: 3.10, 3.11, 3.12, or 3.13
• GUI Framework: PySide6 >= 6.5.0
• Operating Systems: Windows 10/11, POSIX Linux (Ubuntu, Debian, Fedora), macOS

CodeBox connects directly to standard Language Servers installed on your system:

CodeBox prioritizes servers on your system PATH and automatically falls back to python -m pylsp when running in virtual environments.

Define custom languages easily by placing a JSON file into plugins/ or ~/.codebox/plugins/:

{
  "name": "CustomLang",
  "version": "1.0.0",
  "extensions": [".custom", ".cst"],
  "keywords": ["function", "end", "if", "then", "else", "return"],
  "comment_style": ["#"],
  "auto_close_pairs": {
    "(": ")",
    "[": "]",
    "{": "}"
  }
}

Reload plugins at runtime via the Plugin Manager (Ctrl+Shift+P).

Compile a standalone, zero-dependency Windows executable:

build_exe.bat

The build script uses PyInstaller with CodeBox.spec to bundle application icons, default themes, and declarative plugins into dist\CodeBox.exe.

CodeBox/
├── main.py                  # Application entry point & CLI parameter parser
├── version.py               # Central version constants & window title formatter
├── pyproject.toml           # PEP 621 packaging metadata & pytest configuration
├── requirements.txt         # Production runtime dependencies (PySide6)
├── core/                    # Core editor tabs, highlighter, minimap, output panel
├── features/                # Terminal, project tree, LSP manager, linter, themes, plugins
├── languages/               # Language definitions, providers, and declarative parser
├── ui/                      # MainWindow layout, settings, shortcuts, and plugin dialogs
├── plugins/                 # Bundled declarative language plugins (JSON)
├── themes/                  # QSS stylesheets (dark.qss, light.qss)
├── assets/                  # High-resolution vector banners and desktop icons
├── tests/                   # Comprehensive automated test suite (115+ tests)
└── README/screenshots/      # Visual showcase assets

CodeBox integrates with the dev-bricks and ellmos-ai developer tooling ecosystem under the open-bricks umbrella:

When searching for CodeBox, use precise keywords to differentiate from older unrelated repositories:

• dev-bricks CodeBox
• CodeBox PySide6 desktop IDE
• local-first code editor Python Windows
• PySide6 code editor with LSP diagnostics
• lightweight offline code editor Python
• CodeBox declarative language plugin system

CodeBox adheres to strict security and privacy standards. Review SECURITY.md for full details:

• 100% Offline Runtime: No tracking, telemetry, or unsolicited cloud communication.
• Unprivileged Operation: Runs strictly within standard user permissions.
• Confidential Reporting: Vulnerabilities should be reported privately via GitHub Security Advisories or by emailing security@ellmos.ai and lukas@open-bricks.org.

This project is licensed under the MIT License.

This software is provided as an unpaid open-source contribution under Sections 516 et seq. of the German Civil Code (BGB). Pursuant to Section 521 BGB, liability is limited to intent and gross negligence. No warranty, availability guarantee, or fitness for any specific purpose is assumed.