llms.txt

# CodeBox - Local PySide6 Desktop Code Editor

## Last-checked: 2026-09-23

> 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.

Part of the dev-bricks family. Python, MIT.

## Docs

- [README.md](https://github.com/dev-bricks/CodeBox/blob/main/README.md): Primary documentation, installation guide, system architecture flowchart, sequence diagram, capabilities table, comparative matrix, and features.
- [README_de.md](https://github.com/dev-bricks/CodeBox/blob/main/README_de.md): German entry point with localized architecture, workflow diagrams, setup, privacy, and status notes.
- [NOTICE](https://github.com/dev-bricks/CodeBox/blob/main/NOTICE): Copyright attribution and open-bricks umbrella metadata.
- [THIRD_PARTY_LICENSES.md](https://github.com/dev-bricks/CodeBox/blob/main/THIRD_PARTY_LICENSES.md): Level 1 Software Bill of Materials (SBOM) and governance invariants (`INV-LOCAL-01` to `INV-SLA-10`).
- [SECURITY.md](https://github.com/dev-bricks/CodeBox/blob/main/SECURITY.md): Bilingual security policy, supported versions, zero-egress invariants, and reporting protocols.
- [CHANGELOG.md](https://github.com/dev-bricks/CodeBox/blob/main/CHANGELOG.md): Project release history, version tags, and feature changelog.
- [DEVELOPMENT_PLAN.md](https://github.com/dev-bricks/CodeBox/blob/main/DEVELOPMENT_PLAN.md): Architectural roadmap and completed milestones.
- [LICENSE](https://github.com/dev-bricks/CodeBox/blob/main/LICENSE): MIT license text.

## Features & Architecture

- **Multi-Root Workspaces**: Load and manage multiple project folders simultaneously with portable `.codebox-workspace` files, dynamic tree switcher, cross-folder Quick Open, and per-root Git status.
- **Quick-Open & Command Palette**: Centralized keyboard-driven launcher (`Ctrl+P` for project file finder, `Ctrl+Shift+P` for interactive command palette).
- **Git Staging & Commit Dialog**: Dedicated staging (`git add`, `git restore --staged`), change discard, diff inspections, and commit workflow dialog (`Ctrl+Alt+C`, sidebar button, and context menu).
- **Split Editor Panes**: Horizontal (`Ctrl+\`) and vertical (`Ctrl+Shift+\`) multi-editor splits sharing underlying documents.
- **Multi-Cursor & Column Selection**: True multi-caret editing (`Alt+Click`, `Ctrl+Shift+L`, `Ctrl+Alt+Up/Down`, `Alt+Shift+Drag`).
- **Integrated Git Diff-Viewer**: Side-by-side and unified diffs directly in the IDE (`Ctrl+Alt+D`).
- **Multi-Language Highlighting**: Built-in providers for Python, JavaScript, TypeScript, C++, Rust, Go, and Java via state-machine-driven `UniversalHighlighter` supporting multi-line docstrings and block comments.
- **Smart Block Editing & Shortcuts**: Multi-line block indentation (`Tab`), dedentation (`Shift+Tab`), line comment toggling (`Ctrl+/`, `Ctrl+#`), line duplication (`Ctrl+D`), and line moving (`Alt+Up`, `Alt+Down`).
- **Extensible Plugin System**: Declarative JSON language plugins and Python-based plugins with auto-discovery and live reloading (`plugins/`, `~/.codebox/plugins/`).
- **LSP Diagnostics & Completion**: Full thread-safe Qt integration with local language servers (e.g. pylsp, typescript-language-server, rust-analyzer, clangd, gopls).
- **Linter & Problems Panel**: Asynchronous Ruff/flake8/ESLint execution on save with a centralized problems panel.
- **Integrated Terminal**: Native shell integration (`cmd`, `PowerShell`, `bash`) with dynamic encoding detection (cp1252 / utf-8) and directory sync.
- **Project Tree**: File tree with proxy filters, custom context menus, and Git status porcelain overlays.
- **Minimap & Code Navigation**: High-performance cached minimap code preview, bracket auto-closing, and precise go-to-line navigation.
- **Theme System**: Fusion palette combined with dynamic light/dark stylesheet configurations.

## Commands

- `python main.py`: Launches the CodeBox desktop interface.
- `python main.py --open <file>`: Launches and directly opens a target file path.
- `build_exe.bat`: Uses PyInstaller to bundle the application into a standalone executable (`dist/CodeBox.exe`).
- `pytest`: Runs the automated test suite (296 passed, 1 skipped, 100%).
- `ruff check .`: Runs the codebase linting suite.

## Related Projects (dev-bricks & ellmos family)

- [safe-start-for-codex](https://github.com/dev-bricks/safe-start-for-codex): Startup gating utility for local Codex automations.
- [companion-for-agy](https://github.com/dev-bricks/companion-for-agy): Node.js wrapper for the Antigravity TUI.
- [automation-master](https://github.com/dev-bricks/automation-master): Task orchestration and automation supervisor.
- [automizer-for-claude-desktop](https://github.com/dev-bricks/automizer-for-claude-desktop): Automation bridge for Claude Desktop.
- [ellmos-codecommander-mcp](https://github.com/ellmos-ai/ellmos-codecommander-mcp): Code analysis and AST processing MCP server.
- [ellmos-filecommander-mcp](https://github.com/ellmos-ai/ellmos-filecommander-mcp): Filesystem and process orchestration MCP server.
- [CleanMarkdown](https://github.com/doc-bricks/CleanMarkdown): Modern distraction-free Markdown desktop editor.
- [ExplorerPro](https://github.com/file-bricks/ExplorerPro): Multi-tab local desktop file manager.
- [open-bricks](https://github.com/open-bricks/.github): Umbrella open-source organization and standards.

## Audience & Personas

- **[PERSONA-01] Local-First & Offline Developers**: Developers requiring an air-gapped IDE with 100% zero-egress guarantee (`INV-LOCAL-01`).
- **[PERSONA-02] Desktop & Systems Engineers**: Engineers demanding sub-second cold starts (<1.0s) and native PySide6/Qt resource efficiency (`INV-PERF-02`).
- **[PERSONA-03] Security & Compliance Officers**: Organizations requiring Level 1 SBOM transparency, unprivileged user mode, zero copyleft bleed, and defined 48h response SLAs (`INV-SLA-10`).
- **[PERSONA-04] DSL & Tooling Authors**: Language tool creators building custom syntax highlighters and auto-pair rules via simple declarative JSON plugins (`INV-PLUG-07`).

## Search Phrases

```
dev-bricks CodeBox
CodeBox local PySide6 desktop IDE
local-first code editor Python Windows
PySide6 code editor with LSP diagnostics
lightweight IDE no cloud Python
CodeBox desktop editor tabs terminal
Python desktop IDE Language Server Protocol
CodeBox plugin system declarative language
dev-bricks editor dev tools
CodeBox local desktop IDE
```

## External Discovery Notes

- The primary disambiguators are `dev-bricks`, `PySide6`, `local-first`, `Windows desktop IDE`, `declarative language plugins`, and `Language Server Protocol`.
- All documentation is fully bilingual (EN/DE) with zero-egress privacy and non-elevation security guarantees.
- Statutory liability is limited to intent and gross negligence pursuant to § 521 BGB (Gefälligkeitsrecht).