Write assembly. Build kernels. Boot QEMU. Debug with GDB. Inspect binaries. All in one desktop workspace.
Get Started · Features · CLI · Documentation · Roadmap · Contributing
Low-level development often means switching between an editor, compiler, terminal, emulator, debugger, and binary inspection tools. PyxForge brings that workflow into one offline-first, native desktop environment built for bootloaders, kernels, and bare-metal projects.
PyxForge 3.0 uses Go + Fyne for its desktop workbench and embeds real Neovim, configured independently in Lua. The previous Tauri/VS Code-based 2.x implementation remains available in legacy/ while 3.0 moves toward feature parity.
Important
Pre-release software. The editor, builds, terminal, Git, and QEMU/GDB workflows are implemented and tested on Windows and Linux. Agents are not implemented. See current verified state and the roadmap before relying on PyxForge for production work.
| Workspace | Capabilities |
|---|---|
| 📝 Neovim editor | Embedded Neovim, Lua configuration, Tree-sitter, language-server support, tabs, diagnostics, and clipboard integration |
| 🏗️ Build system | pyxforge.toml profiles, dependency ordering, streaming output, cancellation, and compiler diagnostics |
| 🖥️ Integrated terminal | Named shell sessions in the project directory |
| 🌿 Git | Status, diffs, staging, commits, history, branches, stashes, fetch, pull and push, and merge conflicts |
| Build and boot images, view serial output, and issue QEMU monitor commands | |
| 🐛 GDB debugger | Breakpoints, instruction stepping, registers, flags, memory, and disassembly |
| 🔎 Binary inspector | Hex views, BIOS boot-sector mapping, signature checks, ELF sections, and symbols |
| 📸 Snapshots | Compare diagnostic snapshots or save/restore supported QEMU machine states |
| 🎨 Native workbench | Explorer, command palette, inspector, status bar, persistent workspace layout, and themes |
Source code / Assembly
│
▼
Embedded Neovim ──────► Build profiles (pyxforge.toml)
│
▼
Compiler / Assembler
│
▼
Boot image / ELF
│
┌────────────┴────────────┐
▼ ▼
QEMU boot Binary inspect
│
▼
GDB debugging
│
▼
Registers · Memory · Disasm
| Layer | Technology |
|---|---|
| Core application and CLI | Go 1.27.1+ |
| Native desktop interface | Fyne v2 |
| Editor | Neovim, Lua, Tree-sitter, language servers |
| Build configuration | TOML (pyxforge.toml) |
| Virtualization / emulation | QEMU |
| Debugging | GDB/MI |
| Source control | Git |
| Supported development platforms | Windows 11 x86-64; Linux x86-64 |
Windows: download PyxForge-Setup-<version>.exe from Releases and run it: no administrator rights, Go or Git needed, and Neovim is included. See the installation guide.
From source — Prerequisites: Go 1.27.1+ and a C compiler for Fyne/OpenGL. Additional tools such as Neovim, QEMU, GDB, NASM, and language servers enable their corresponding features. See the installation guide for platform-specific commands.
git clone https://github.com/obstinix/PyxForge.git
cd PyxForge
go build -o pyxforge ./cmd/pyxforgeCheck which development tools are available:
./pyxforge doctor
./pyxforge doctor --commandsOpen a project:
./pyxforge path/to/projectWindows: Run the built executable as
pyxforge.exe(for example,./pyxforge.exe doctorin PowerShell). The build output filename can be specified explicitly with-o pyxforge.exe.
To install the editor's pinned plugins and Tree-sitter parsers, run once while online:
./pyxforge setup editorPyxForge makes no network request on startup, requires no account, and sends no telemetry. Editor setup is the documented network-using operation.
The desktop application and CLI share project discovery and tool detection.
| Command | Purpose |
|---|---|
pyxforge help |
Show commands and options |
pyxforge version |
Show version, Go/Fyne versions, and source revision |
pyxforge doctor [--commands] |
Detect tools and show installation guidance |
pyxforge info [folder] |
Show project root, config, and Git checkout |
pyxforge build [profile] |
Execute a build profile and its dependencies |
pyxforge build --list |
List available build profiles |
pyxforge run [--debug] |
Build and boot in QEMU; optionally wait for GDB |
pyxforge inspect FILE [--disasm] |
Inspect boot sectors or ELF binaries |
pyxforge setup editor |
Install pinned editor dependencies |
Most commands support --json. Exit codes: 0 success, 1 detected problem, 2 invalid command line. Ctrl+C stops the command and its child tools.
Projects define build profiles and dependencies in pyxforge.toml. Build output streams into the workbench; recognized GCC, Clang, NASM, linker, rustc, Cargo, and MSVC-format diagnostics appear in Problems and the editor.
Try the included examples/boot-sector project: a complete 512-byte BIOS boot sector. For a larger example, see PyxisOS integration.
Run in QEMU builds the selected target and boots the configured image. The QEMU panel shows serial output and accepts monitor commands such as info registers. A project without a [qemu] table gets Set Up Machine… (Run menu, or the QEMU panel): choose the file to boot, the QEMU and the GDB port, and PyxForge writes the tables into pyxforge.toml.
Debug in QEMU starts the emulator paused and attaches GDB at the first instruction (for example, 0x7c00 for a BIOS boot sector or the entry point for an ELF kernel).
| Inspector view | What it shows |
|---|---|
| Registers | Current CPU registers and changed values |
| Flags | EFLAGS, bit by bit |
| Hex | Image bytes and boot-sector signature |
| Map | Boot-sector regions, padding, signature, and detected structures |
| Disasm | Instructions around the current address, including real-mode decoding |
| Memory | Stack contents or memory at a chosen address |
| Snapshots | Diagnostic comparisons and supported QEMU machine states |
Snapshot distinction: diagnostic snapshots compare paused machine observations but cannot restore execution. QEMU machine-state snapshots can restore supported machines; they require snapshots = true in [qemu] and qemu-img.
| Shortcut | Action |
|---|---|
Ctrl+O / Ctrl+P |
Open file / Go to file |
Ctrl+S / Ctrl+Shift+S |
Save / Save as |
Ctrl+W / Ctrl+Shift+W |
Close editor tab / close all tabs |
Ctrl+Tab / Ctrl+Shift+Tab |
Next / previous tab |
Ctrl+Shift+P |
Command palette |
Ctrl+Shift+E / J / I |
Toggle explorer / bottom panel / inspector |
Ctrl+Shift+B |
Build |
Ctrl+Shift+M |
Problems panel |
Ctrl+Shift+F8 / Ctrl+Shift+F7 |
Next / previous problem |
Ctrl+Shift+F9 |
Run the current file (Python, JavaScript, Go, Rust, C, C++, GNU assembly, Java, scripts; a NASM boot sector boots in QEMU; HTML in the browser); Run > Debug Current File starts it under GDB, pdb, node inspect or Delve, stopping at the breakpoints set with F9 |
Ctrl+Shift+R / D |
Run / debug in QEMU |
Ctrl+Shift+F2 |
Stop QEMU |
Ctrl+Shift+F5 / F10 / F11 |
Continue / step over / step instruction |
Ctrl+Shift+G |
Git panel |
Ctrl+Shift+ + ` |
New terminal |
Ctrl+Shift+, |
Settings |
The conventional keys above are PyxForge's in the editor; every other key goes to Neovim. In the terminal, plain Ctrl keys go to the shell, and only the Ctrl+Shift shortcuts and Ctrl+Tab are PyxForge's. "Toggle Neovim Keys in the Editor" in the palette gives the plain Ctrl keys back to Neovim (Cmd on macOS throughout). See the complete keymap.
PyxForge/
├── cmd/pyxforge/ # Desktop + CLI entry point
├── internal/
│ ├── ui/ # Fyne workbench and design system
│ ├── neovim/ # Embedded editor integration
│ ├── cli/ # Command-line interface
│ ├── build/ # Build orchestration and diagnostics
│ ├── config/ # TOML parsing and validation
│ ├── workspace/ # Project and session state
│ ├── git/ # Git operations
│ ├── qemu/ # Emulator control and snapshots
│ ├── gdb/ # Debugger integration
│ ├── inspect/ # Binary inspection
│ ├── snapshot/ # Diagnostic comparisons
│ ├── toolchain/ # Tool detection
│ └── ... # Process, commands, build info
├── nvim/ # Isolated Lua editor configuration
├── examples/boot-sector/ # Sample BIOS boot sector
├── tools/ # Checks, snapshots, release tooling
├── docs/ # Guides, architecture, roadmap
├── legacy/ # Previous 2.x implementation
└── go.mod
PyxForge isolates its editor configuration with NVIM_APPNAME=pyxforge; it does not read or overwrite your normal Neovim configuration. See developer setup and the design system.
| Platform | Status |
|---|---|
| Windows 11 (x86-64) | ✅ Supported and tested |
| Linux (x86-64, Ubuntu 24.04) | ✅ Supported and tested (CI / WSL2) |
| macOS |
go run ./tools/forbidcheck
gofmt -l .
go vet ./...
staticcheck ./...
go test -race ./...CI exercises Linux and Windows, compiles on macOS, and produces release builds. Integration tests use real Neovim, Git, QEMU, qemu-img, GDB, and NASM where installed; otherwise they report skips.
Read CONTRIBUTING.md before submitting changes.
Development progress is tracked in the roadmap, with verified implementation details in CURRENT_STATE.md.
Current limitations:
- Agents and Git worktrees are not available. Pull only fast-forwards: when a branch and its upstream have both moved, merging or rebasing them is left to the terminal (conflicts then show in the Git tab). PyxForge never force-pushes.
- PyxForge runs no program named in a repository's own Git configuration (a filter, merge driver or signing program, or an ssh, credential or upload program for fetch, pull and push): those operations are left to the terminal. A setting that repeats the user's own, as
git lfs install --localwrites, is not refused. - macOS support is not verified beyond CI compilation.
- Screen-reader access is not supported by the Fyne interface, although keyboard navigation is available.
- Machine-state snapshots are limited to
boot_imageprojects and are invalidated when the image is rebuilt. - MSVC-format diagnostics are tested with Clang's
-fdiagnostics-format=msvcand documentedcl/linklines, not with Microsoft's compiler itself.
Bug reports, documentation improvements, and code contributions are welcome. Start with the contribution guide, development setup, and design-system documentation.
Distributed under the Apache License 2.0. See LICENSE. Bundled fonts and icons have separate licenses documented in FONT_LICENSES.md.
PyxForge — from source code to the first instruction.