12: Power Tools Deep Dive - transcript
Liam: The QUILL Cast, episode twelve. I'm Liam. Today is the power tools deep dive, the helpers that earn their keep once the basic editing grammar is in your hands: macros, the clipboard history, the regex helper, the snippet gallery, the developer console, and a few quiet toggles that change how the editor itself behaves.
Jessica: I'm Jessica. In episode eleven, we built the foundation, find, replace, navigate, with F3 for the next hit, control H for replace, and Search in Files for the cross-folder lens. We also walked past regular expressions, which I said are a search pattern with wildcards, and promised more regex love in a future episode. Today, we are going to fold a tiny taste of regex back into the power tools tour, because the regex helper lives right next to macros in the menu, and the two pair well.
Liam: Quick housekeeping for the calendar. The series is fifty-four episodes in total. We are mid-pack, with the format and language family still ahead, plus the rest of the structured writing and the build-your-own-Quillin arc. That puts us roughly a third of the way through. Pace yourself, the back third of this course gets dense and the rest of episode twelve is one of the dense ones.
Jessica: Frame for today. Power tools is a broad catch-all term. In QUILL's actual menu, the family lives under Tools, then the submenu labeled Advanced. The label matters: in the code the group is registered as power_tools, in the menus.md Phase 4 recirculation it was repackaged and surfaced as the Advanced submenu, but the commands it contains are the same regardless of which name you see in the changelog. So if you remember it as Tools plus Advanced, you are remembering the current label. If you remember it as Power Tools, you are remembering the older name. Both refer to the same set of commands.
Jessica: Do this now, before the hands-on walkthrough. Open QUILL with any document on screen, even a blank one. Press alt T to land in the Tools menu, arrow down to Advanced, and press right arrow to open the submenu. Just listen to it. Read the items. The very first group is the cohesive power-tools command set, the second group is Macros, then Developer Console, then a few singletons: Regular Expression Helper, External Tools and Format Support, YAML Structure Editor, and a Document Intake submenu. Get a feel for how the Advanced submenu is organized, because the rest of this episode is going to walk through that same shape.
Liam: That is the menu that, in the changelog and the developer manifest, is referred to as the power-tools group. If you read older blog posts or early release notes that mention Tools, then Power Tools, that is what they meant, and the rename to Advanced is a labeling change, not a content change. The commands, the command ids, the help text, all unchanged.
Jessica: Back out of the menu and let's start with the first big tool: macros. A macro, in QUILL's specific sense, is a saved list of command ids, in the order they were performed, captured live while you work. The file on disk is macros.json inside your QUILL data directory, and the module that owns it is quill.core.macros. The MacroManager dataclass holds the recorded set, the active recording name, the last-played name, and a playing-back flag so recordings do not recurse into themselves.
Liam: Recording is the easy half. Open the Tools, Advanced, Macros submenu, and pick Start Recording. A dialog titled Start Macro Recording opens with a single text field, default value My Macro, asking for a name. Type something useful, like format-headings-and-save, and press enter. From that moment, every command you fire that has a registered command id, except the four macro-control commands themselves, is appended to the active macro's steps list. Format a heading, indent, move a line, run an AI rewrite, all recorded. When you are done, pick Stop Recording. The status bar says Saved macro, name, with N step or steps. That is your macro, persisted, ready to play.
Jessica: And the four macro-control commands that the recorder deliberately ignores are the ones that would create an infinite loop. They live in the constant _MACRO_CONTROL_COMMANDS in the macro handling code: start macro recording, stop macro recording, play last macro, and manage macros. If the recorder did not skip them, pressing Stop Recording would itself be appended, and the next time you played the macro, you would trigger an infinite re-record. That is the kind of thing we sweat so you do not have to.
Liam: Playing back. Two ways. The simplest is Play Last Macro, also in the Macros submenu. That is one keystroke, the command runs the most recently recorded or played macro, and the status bar announces the name. The other is the Manage Macros dialog, titled Manage Macros, which lists every macro you have ever recorded, lets you inspect its step list in a read-only multi-line text box, and offers buttons to play, rename, or delete. There is no editing of individual steps, by design, you re-record if a step changed, which keeps the model simple and the file human-readable.
Jessica: A quick reality check from the code. The Manage Macros dialog is intentionally minimal: a list box on the left, a details pane on the right, no fuzzy search, no tag system. If you build up a hundred macros, you will scroll. The system is built for a working set of five to ten named sequences, not a personal library. If your needs grow past that, the next episode's spell-check-adjacent tools are not the answer either. The honest answer is: keep your macro names short and obvious, and prune.
Liam: What is recorded, exactly, is the string command id, like format.heading_1, edit.indent, view.toggle_soft_wrap. The list is saved verbatim into the JSON. On playback, MacroManager iterates the steps and calls a runner with each id. The runner in the live app is self.commands.run, the same command dispatcher the keymap uses. That means: a macro plays back as if you had pressed the right key for each step. Anything that respects the command pipeline, keymap remapping, undo grouping, AI rewrites, plays back the same way.
Jessica: And because it uses the same dispatcher, the macro participates in the global undo contract from episode eleven. If your macro is five steps that build one heading, those five steps still undo as one chunk, not as five separate undos. Some keymap changes might change what a given id does, that is on you when you customize, and the macro just follows.
Liam: Important behavior note. Macros are not portable across QUILL versions. A macro stored in a 0.9 macros.json file references command ids that may have been renamed in 1.0. The loader does not fail loudly on unknown ids. It just plays back what it can and skips the rest. So treat your macro collection as something to review after a major version bump. The community hub for sharing macros is the keyboard pack system, covered in episode ten, and the macro export is a near-future feature that will let you save a single macro to a portable .json snippet, distinct from the user-global file.
Jessica: A honest correction. The user guide we shipped with 0.9 says macros can be exported individually from the Manage Macros dialog. That was the design, and it is not in the shipped dialog yet. The dialog exposes Play, Rename, and Delete, no export button. The single-macro export will land alongside the macro library in a later release. We will call it out again in the episode that walks the macro library. For now, the only export path is a hand-copy of the macros.json file.
Liam: Next power tool: the Regular Expression Helper, a singleton command under the Advanced submenu. A regular expression is a search pattern with wildcards, and we walked the basics in episode eleven. The helper is the place to compose a pattern in safety, against a sandbox of your own text, before you let it loose in Find or Replace in Files. Open it, paste a chunk of your document, type a pattern in the top field, and the lower pane shows you the matches in real time, numbered, with surrounding context, no false positives, no guessing about whether backslash D matches what you think it does.
Jessica: Why it matters. Episode eleven introduced regex with a shrug, you do not need to master it, you need to know it exists. The helper is the spot where the second half of that sentence becomes true. You do not need to know regex cold. You paste your text, type the pattern someone on the internet shared, watch it light up, fix your pattern with the live feedback, and copy the working pattern into Find or Replace in Files. The helper is a workbench, not a textbook. It is for the one percent of edits where literal Find is not enough and the cross-file lens of Search in Files would be too broad.
Liam: A side note about the regex flavor. QUILL uses the standard Python re module, with regex as an optional accelerator when present. That means two practical things. First, character classes like backslash D plus any digit, dot any character, plus one or more, work the same way they do on the regex cheatsheet you have bookmarked. Second, the timeout safety: when the regex package is available, the linter and the search paths apply a half-second per-pattern timeout so a pathological pattern can never freeze the editor. You will never notice it on real text. It is there so a typo in a quantifier cannot lock the UI.
Jessica: The other regex touchpoint worth knowing is in the snippet gallery, coming up, where the matching macros are listed alongside the power tools for discoverability. And in the developer console, where you can test a pattern against live data. But the helper is the friendly one. Use it first.
Liam: The Macros submenu sits between the macros themselves and the next power-tier feature: the Developer Console. A small submenu with four items. Open Python Console. Open TypeScript Console. Copy Diagnostic Summary. Restart TypeScript Worker. The two consoles are in-process REPLs: the Python console runs against the same Python interpreter QUILL is running on, with the same module path and the same wx available, so you can poke at the live model. The TypeScript console runs against the TypeScript-side worker that powers the snippet gallery, the language profiles, and the inline notes, with its own restart button so a broken script never wedges the editor.
Jessica: For the listener who never opens a console, the honest summary is: the consoles are here for the curious and the contributor. You do not need them. The power tools that affect your writing day-to-day are macros, the regex helper, the snippet gallery, the document intake tools, and the YAML structure editor. The developer console is a niche tool. Knowing it exists is the win. Knowing how to use it is its own episode, the stability power-user episode at the end of the series.
Liam: Copy Diagnostic Summary is a one-click way to put a plain-text snapshot of the current state of QUILL into the clipboard, settings summary, recent file list, feature flags, error counters, last three log lines. It is what the help team asks for when you file a bug. Paste it into the support form. We do not have a way to read it back, only you do, and pasting it into a private channel keeps the diagnostic data in your hands. It does not phone home.
Jessica: And the TypeScript worker restart. The TypeScript side handles a small set of optional features. If one of them misbehaves, restart the worker. The cost is a one-second reload. The benefit is that a stuck worker never has to escalate to a full QUILL restart. Episode fifty-three, the accessibility power user episode, covers when to reach for the worker restart versus a full restart, and when to just file a bug.
Liam: The Document Intake submenu is the second submenu under Advanced. Three items: Document Intake Report, Review Extraction Quality, Report Bad Extraction. Document Intake is the umbrella for the conversion pipeline that brings PDF, image, and Office documents into QUILL, runs them through local OCR when needed, and lands a clean text draft in front of you. The report gives you a per-document rundown of what was done, how many pages, what confidence, what fallback OCR engines were tried. Review Extraction Quality opens a side-by-side of the original and the extracted text, lets you step through low-confidence regions, and report the worst one back to us. Report Bad Extraction is the lightweight option when you spot one bad paragraph, no deep review, just a flag.
Jessica: Why this lives in Advanced and not in File plus Import is a design choice. The import commands get you to a draft. The intake submenu is for the after-state, the did it work, where are the holes, and how do I report them. It pairs with the OCR and Document Conversion submenu under Reading and Dictation, which is the how do I import a PDF or image entry point. The flow is: import lands a document, intake reports on it, review walks it, report flags problems. It is the trust layer of the conversion pipeline.
Liam: The two singletons beside the submenus round out Advanced. External Tools and Format Support opens a single dialog that lists every optional third-party engine QUILL knows about, with a button to download or update each one. Faster Whisper for offline speech, Tesseract for local OCR, FFmpeg for audio and video, Pandoc for format conversion, MarkItDown for office and PDF text extraction, the LibreOffice bridge for round-tripping complex Word documents. Each row shows the version installed, the version available, and the path. If a feature is silently unavailable because a tool is missing, this is the dialog that explains why.
Jessica: And the YAML Structure Editor. A small structured editor for YAML files, the same engine the settings system uses internally. Most listeners will never open it. Power users who hand-edit settings files or author document templates in YAML will love it. It validates as you type, with a status bar that reports where the YAML is broken, and the visible structure is the same tree the settings system reads. If you are writing a structured template for a series of similar letters or reports, the YAML editor is the right tool. If you are not, you can ignore it forever.
Liam: Now the second big feature after macros: the Snippet Gallery. A snippet is a named, parameterized block of text or markup that you insert from a menu or by typing a trigger abbreviation. The gallery is a single dialog, a searchable list of every snippet you have installed, every Quillin-bundled snippet, plus a preview pane showing the rendered text with the current parameter values filled in. Open it from Insert, Snippet Gallery, or from the command palette. The same dialog. Same contents.
Jessica: Snippets versus macros, because the question comes up. A snippet is text with placeholders. It is plain text plus a tiny template language. A macro is a sequence of commands, with all the side effects of running those commands. Use a snippet when the goal is the inserted text. Use a macro when the goal is the action chain. They overlap on the case where the action is just type this text, and there, snippet is the simpler tool. There is a related set of features, abbreviations, that fires when you type a trigger and press the expansion key. That is in the abbreviation family, which is part of the editing power tools tour we did not cover today, and we will see it in a focused episode later in the series.
Liam: A code-verified claim about the gallery. The dialog is a wx.Dialog, with a search box, a list, and a preview area. The bundled snippets include date, time, date and time, and a few Markdown structural snippets, all from the bundled insert-tools Quillin. New snippets land in the gallery as soon as the Quillin that contributes them is enabled, no restart. The gallery reads from the same registry the Insert menu reads, so the two views stay in sync.
Jessica: And the honest correction. The release notes for 0.9 said the Snippet Gallery has drag-to-reorder, which is a common feature in other snippet managers. It does not. The gallery lists, previews, and inserts. Reorder is not there. The internal data model supports ordering, the dialog does not yet expose a UI for it. This is a tracked follow-up, and we will say so again when the reordering ships.
Liam: Now the quiet toggles, the items in the power-tools group that change how the editor itself behaves. Toggle Read-Only Guard, Toggle Clipboard Collector, Collect Clipboard Now, Toggle Key Describer, Toggle Indentation Announcements, Infer Indentation, Line Statistics, Describe Character at Cursor, Describe Image at Cursor. Each is a one-line description. Together they are the personalization layer of power tools.
Jessica: The Read-Only Guard, when on, asks for confirmation before saving a file that the OS or the file extension marks read-only. Most users will not need it, but the person who keeps overwriting a shared network drive's locked-down settings file will thank it. The Clipboard Collector, when on, keeps a rolling history of your last several copies. Collect Clipboard Now grabs the current clipboard text into the history. The Toggle Key Describer flips a teaching mode on, where every keystroke is announced, gold for training a new keyboard user or for diagnosing your own muscle-memory mistakes. The Indentation Announcements toggle adds a spoken depth cue on tab and shift tab, so you can hear how deep you are in a list or a code block.
Liam: Infer Indentation is a one-shot command: you put the cursor in a document, and QUILL samples the indentation style of the surrounding text, tabs or spaces, how many, and applies it to the rest of the document. It is a fast unjammifier for code pasted from a stranger's editor. Line Statistics, on the cursor's paragraph, gives you a spoken report of the line, the paragraph, the document: line count, average line length, longest line, empty lines. It is a structural snapshot for the visually-focused writer who wants to know if the rhythm of their prose is consistent.
Jessica: Describe Character at Cursor and Describe Image at Cursor. Two of the most useful single-keystroke tools in QUILL. Describe Character is the one Jessica loves. Put the cursor on a mystery character, run the command, and QUILL reads off the Unicode name, the code point, the category, the decomposition if it has one. Non-breaking space, zero-width joiner, soft hyphen, smart quote pretending to be plain, all named in plain English. Describe Image at Cursor reads the alt text of the image, falls back to the image URL, falls back to a placeholder, and never silently fails. The two together cover the two most common accessibility mysteries, mystery characters and mystery images.
Liam: A practical integration question: how do power tools play with the rest of QUILL? The honest answer is: the same way everything else does, through the command registry, through the keymap, through the dialog inventory. Macros play back via the command dispatcher, so any command you can keybind you can record. The snippet gallery is reachable from the Insert menu, the command palette, and the search bar, all the same dialog. The regex helper is reachable from Tools, Advanced, and from the command palette. The developer console is reachable from the same place, and from the keymap if you want to bind a key. The intake submenu is reachable from Tools, Advanced, and from the OCR and Document Conversion submenu under Reading and Dictation, which is where the import step lives.
Jessica: A pattern worth calling out. The power tools are organized around outcomes, not menus. Macros group around automation. The regex helper groups around pattern composition. The snippet gallery groups around reusable text. The intake submenu groups around document conversion trust. The developer console groups around debugging. The YAML editor groups around structured authoring. Once you see the grouping, the menu structure stops being a list and starts being a map. You know where to go when you have a problem because the menu home matches the problem shape.
Liam: One more honest correction. Episode eight of the series, the moving-through-text episode, made a passing reference to macros playing back key presses. They do not. Macros play back command ids, which is a much more robust layer. If a future keymap remaps the same command to a new key, the macro still works. The keypress model is a common metaphor, and we used it because most listeners come from editors that do it that way, but the truth is more flexible. The macro survives keymap changes. It does not survive command renames.
Jessica: That distinction matters. If you have a heavy macro, and the next major QUILL version renames the command it depends on, your macro will skip that step silently on playback. There is no warning. The way to defend against it is: keep macro names descriptive, keep step counts small, and re-record yearly. We do not have a built-in migration tool, and that is an open piece of work.
Liam: Now a small but useful topic: safety with macros. A macro that runs formatting commands is safe. A macro that calls an AI rewrite is a recorded network round-trip with the same consent rules as if you had clicked the AI menu manually. The same key applies: every AI step in a macro asks for consent the first time the macro plays back, in the same way the first manual AI call would. A macro that runs shell integration commands, the Install Shell Integration and Remove Shell Integration items live in Advanced, not in Macros, by design. You cannot record them. The shell integration is its own consent flow, with its own dialog, and it does not enter the macro pipeline.
Jessica: A safety note on the clipboard collector. When the collector is on, it keeps a history of the last several copies in memory, and optionally, in a small rolling log in your data directory. The collector never sends the history off the machine. It is local history. If you copy something sensitive, you can turn the collector off, clear the history, or just stop using the clipboard for that one moment. The collector is opt-in, the default is off, and the setting lives in Preferences under Privacy.
Liam: A note on the regex helper and the developer console. Both can interact with text in ways that surprise you. The regex helper never modifies your document, it is read-only against the sandbox. The developer console can do anything the user can do, and is gated behind a confirmation in the launch. The console is for the people who already know what they are doing. If you are not sure, the regex helper is the safe tool, the console is the powerful tool, and you will know when you have crossed the line.
Jessica: Putting the day in context. We have walked the Tools, Advanced submenu, the macro recording and playback lifecycle, the regex helper as a regex workbench, the snippet gallery as the home for reusable text, the developer console as the contributor and power-user tool, the document intake submenu as the conversion trust layer, the External Tools and Format Support dialog as the engine inventory, the YAML Structure Editor as the structured-authoring niche tool, and the quiet toggles that personalize the editor. Macros are the big win. The rest are the supporting cast. Together, they are the toolbox that turns a writer into a power user.
Liam: Now the homework. Four small steps to make the power tools stick. Step one: open Tools, Advanced, Macros, Start Recording, type a name like, double-space-after-period, and then perform five real actions in a real document, maybe toggle case on a few words, indent a paragraph, move a line up, change a heading level, save. Stop recording. Look at the macro in the Manage Macros dialog. Notice the step list. That is your first macro.
Jessica: Step two: play the macro back in a different document, or in the same document after some changes, and watch the same five actions run. Notice that the undo chain un-does the whole macro as one step. Notice that if you have a keymap rebind for one of those commands, the macro follows the rebind.
Liam: Step three: open the Regular Expression Helper from Tools, Advanced, and paste a paragraph of your own writing. Type backslash D plus in the pattern field. See all the numbers light up. Try a more interesting pattern, like backslash b capital letter, backslash w plus, backslash b, to find every capitalized word. Read the matches aloud, with the numbers, and learn the rhythm of how regex feels when it works.
Jessica: Step four: open the Snippet Gallery from Insert, Snippet Gallery, or the command palette. Search for date. Find the date snippet. Insert it. Notice the cursor is now positioned where the next parameter goes, if there is one. Close the gallery, then re-open it, search for something else. Get a feel for the rhythm. That gallery is going to be a home you return to.
Liam: A reading note. The user guide has a chapter on power tools, but it lags the code by a release or two. The macros export and the snippet drag-to-reorder items in the user guide are not in the shipped dialog. When you find a guide claim that does not match what you see in the menu, trust the menu, and tell us. The bug-report channel is in the Help menu, Report Bug, and we read every report.
Jessica: Next episode: spelling and word tools. The dictionary, the misspelling list, the spell-check navigation, the thesaurus, and the word-count tools. We will also touch the AI grammar and spell-check family, which is a different animal from the offline dictionary. Episode thirteen closes the writing-and-language arc and sets us up for the format conversion tour that follows.
Liam: The series total is fifty-four episodes. We are at twelve. The next forty-two cover formatting, conversion, accessibility, AI, the vault, the Quillins, the build-your-own arc, and the power-user arc. We have time, and the rest of the series gets denser, but never faster. Same pace, deeper tools.
Jessica: I'm Jessica.
Liam: I'm Liam. Power tools, recorded one command at a time, played back at the speed of thought.