PythonDebugger
A minimal browser-based Python debugger and light editor in the app/ package.
Completely offline, with local HTML, CSS, and JavaScript in app/ui.py.
Standard library only (Python 3.8+): no pip installs, frontend build, CDNs, remote
fonts, telemetry, or internet requests. Built on bdb, the engine behind pdb.
The browser and debug worker communicate only over loopback on your computer;
the UI's Content Security Policy blocks external resources and connections.
python -m app [FOLDER] [--script path/to/script.py] [--port 8765] [--no-browser] [--settings FILE]
It prints a URL containing a random token (localhost only); open it in Chrome.
Run from the repository/distribution root. python debugger.py remains a
compatibility launcher; python app/debugger.py also works. Copy the app/
folder with the launcher when distributing the debugger; the root launcher is
no longer a standalone application file.
Project layout
| Folder |
Responsibility |
Status |
app/ |
Python debugger, tracing worker, settings, and debugger browser UI |
Implemented |
webapp/ |
ChatGPT-like local web chat interface |
Guidance scaffold |
cli/ |
Terminal coding-agent interface |
Implemented |
llm/ |
Shared BaseLLM API and llama.cpp backend |
Implemented |
coding_tools/ |
Provider-independent file, search, Git and command tools |
Implemented |
mcp_local/ |
Local stdio MCP server, client and registry adapter |
Implemented |
harness/ |
Versioned coding loop, planning, approvals and isolated subagents |
Implemented |
tests/ |
Automated runtime, editor, layout, and guidance checks |
Implemented |
evaluations/ |
Opt-in assessment scenarios and reports |
Guidance scaffold |
docs/ |
Architecture and design documents |
Implemented |
memory/ |
Current plan, session history, and learned facts |
Implemented |
Each maintained folder has an AGENTS.md index. Applications will share LLM
contracts through llm/; the debugger remains usable without an LLM server.
The first local coding agent is available with an already running llama.cpp
server. Its default model is unsloth/Qwen3.5-4B-GGUF:UD-Q3_K_XL on numeric
loopback port 9931:
python3 -m cli --root . "Read AGENTS.md and summarize the project"
See coding-agent usage and customization,
tool and MCP inventory, and
Deep Agents research. Writes require
--allow-write; host commands require --allow-execute. No LangChain or MCP
packages are installed or needed. The ChatGPT-like web chat UI remains planned.
Using it
- Pick a folder (Open / Browse…). Click a
.py file to open it; double-click it to make it the Script to run
(the first file you open is chosen automatically).
- Click the gutter to set breakpoints (accent-colored dot), then Run.
- Continue F8 · Step Over F10 · Step Into F11 · Step Out Shift+F11. The editor follows
execution into other files. Click a call-stack row to inspect that frame.
- Variables: expand lists, dicts, sets, enums, objects, numpy arrays, DataFrames/Series
(
view button opens a paged table). Values that changed since the last stop are outlined.
- Terminal (bottom): while paused, type Python to run in the selected frame, e.g.
enabled = True to fix a variable, or p x / pp x. While the script is running, the
same box feeds the script's stdin.
- Watch expressions re-evaluate at every stop.
- Uncaught exceptions pause the program (post-mortem) so you can inspect the failing frames.
- Breakpoints can be added or removed at any time, also while paused; Continue honors them (other files too).
- Hover (while paused) on a name: signature, docstring,
file:line (click to open), and for classes/methods the
full inheritance chain (MRO) with the defining class marked; Ctrl/Cmd+click jumps to the definition.
Hover never runs your code (properties and __getattr__ are not evaluated).
- Just my code skips the standard library and site-packages when stepping.
Editing & settings. Click the code to edit it (Ctrl+S saves, CRLF preserved, Tab/auto-indent, breakpoints
follow your edits). The ⚙ Settings menu sets font, themes, custom colors and environment variables;
A− / A+ or Ctrl++/-/0 zoom only the text (not the layout). Everything is saved to
debugger_settings.json in the distribution root, next to the compatibility
launcher (git-ignored), and restored on the next start, together with your
last folder, script, args, breakpoints and watches. Don't put secrets in it.
The editor has its own toolbar, per-tab undo/redo history, cursor/selection status,
automatic bracket and quote pairing, and these shortcuts (use Cmd instead of Ctrl
on Mac, except Ctrl+Space):
| Action |
Shortcut |
| Save / Save all modified tabs |
Ctrl+S / Ctrl+Shift+S |
| Undo / Redo |
Ctrl+Z / Ctrl+Shift+Z or Ctrl+Y |
| Find / Replace in current file |
Ctrl+F / Ctrl+H |
| Next / previous match |
F3 / Shift+F3; Enter / Shift+Enter in the find field |
| Go to line or line:column |
Ctrl+G |
| Toggle comments |
Ctrl+/ |
| Indent / outdent selected lines |
Tab / Shift+Tab |
| Move lines up / down |
Alt+Up / Alt+Down |
| Duplicate lines |
Alt+Shift+Down |
| Local word suggestions |
Ctrl+Space, then arrows and Enter/Tab |
Find supports case-sensitive, whole-word, and JavaScript regex searches with match
highlighting. Regex replacements accept captures such as $1; literal mode keeps
dollar signs unchanged. Empty regex matches are skipped. At most 5,000 matches are
highlighted; Replace all processes every nonempty match in the current file and can
be undone in one step.
Word suggestions use names from the current file, Python keywords, and common
built-ins. They work entirely offline and do not perform type analysis. Cursor
positions and bounded undo histories survive tab switching and saving; they stay
in memory and are lost when a tab is closed or the page is reloaded. Save edits
before Run/Restart; editing a running program does not change its loaded code.
Themes & styles. Choose Daylight, Graphite, Midnight, Parchment,
Forest, or High contrast for the workspace. The Viewer / editor can
match the workspace or use a separate theme. Customize background, text, syntax
colors, and gutter with the color pickers and live preview. Choosing an editor
preset clears its custom color overrides; Reset editor colors restores just
that palette, and Reset appearance to defaults restores all appearance settings.
Export style… saves a local pythondebugger-style.json; Import style…
loads it without accessing the internet. Only appearance settings are exported,
excluding environment variables, file paths, and code. Imports accept validated
JSON settings rather than arbitrary CSS or JavaScript. Style files can also be
edited in a text editor; use hex colors such as #243047:
{
"format": "pythondebugger-style",
"version": 1,
"prefs": {
"theme": "midnight",
"editor_theme": "sepia",
"editor_colors": {"keyword": "#8055a5"}
}
}
Palette IDs are light, dark, midnight, sepia, forest, and contrast;
editor_theme also accepts match. Color keys are background, text, keyword,
string, comment, number, and gutter. Appearance settings persist across restarts.
The script runs with the selected folder as its working directory, sys.path[0] set to the
script's directory, and the Python field as interpreter (default: the one running the server).
The debugger does not restrict the script's own network access; it runs trusted
local code. Optional NumPy/pandas inspection uses packages already loaded by that
script and never installs or imports them on the debugger's behalf.
Limits: no semantic autocomplete, multi-cursor, or code folding; main thread only (threads/multiprocessing are not traced); stepping is slower than
native because bdb is a pure-Python tracer (~0.7 µs per function call).
Tests
python -m unittest discover -s tests -v
End-to-end: they start the real server and a real debuggee and drive it over HTTP.
Coverage includes style persistence/validation, embedded assets and the browser
content policy, and a copy of the app/ package running with site packages
disabled and non-loopback server connections rejected by a test audit hook.
Optional editor logic checks use Node's built-in test runner (no npm packages):
node --test tests/editor.test.cjs
These execute the local debugger JavaScript from app/ui.py against a small DOM test double,
covering editing commands, search/replacement, history, completion, and save races.
They do not verify browser rendering. Node is only a developer test tool; running
the debugger still requires just Python and a browser.
Working with Codex
Open this repository in Codex. AGENTS.md supplies the project
instructions, commands, and behavior to preserve, using Codex's
repository instruction convention.
Architecture and code map explains the server, worker,
browser, and their protocols. No dependency installation or frontend build is needed.
For a development session with separate settings:
python3 -m app examples --script demo.py --no-browser --settings /tmp/pythondebugger-settings.json
Open the printed URL, set a breakpoint, and press Run. The tests require
localhost sockets and subprocesses; the pandas table test skips if pandas is not
installed. Browser interactions need a separate manual check.