Welcome to the CodeChat Editor

The CodeChat Editor is a GUI-based programmer's word processor / Jupyter for software developers. This document describes its basic features and use. In contrast, the style guide provides strategies for effectively employing the CodeChat Editor to improve the software development process.

<iframe title="YouTube video player" src="https://www.youtube.com/embed/videoseries?si=QNrYCiTLVCpxpAbD&list=PLOJAqFa3UI2FJncc-OBRPhh17NJXQP6ve" width="560" height="315" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen="allowfullscreen" referrerpolicy="strict-origin-when-cross-origin"></iframe>

Full manual

Read the manual rendered using the CodeChat Editor, since this documentation doesn't correctly render on GitHub.

Installation

Install the CodeChat Editor extension for Visual Studio code. For developers, see building from source.

Research capture

The VS Code extension can record dissertation study capture events when a participant explicitly opts in. A participant first registers in the capture portal, which emails a capture token. In VS Code, run Manage CodeChat Editor Capture or CodeChat Editor: Enter Capture Token from the command palette, paste the token, then turn on consent and recording from the same capture manager.

The token is imported through the VS Code UI and persisted only in VS Code SecretStorage. It is never written to workspace settings, repository files, or a JSON configuration file. The extension asks CaptureWebService for token status; the status item and capture manager show whether the token is accepted, rejected, unavailable, or disabled by the portal. The participant ID used in events comes from that status response, not from the token text.

CodeChat no longer connects directly to the remote capture database and no longer reads or stores database credentials. The old local JSON database-secret configuration path has been removed. Capture events now leave CodeChat only by calling CaptureWebService with the portal-issued bearer token; any database writer role remains inside the service deployment.

Events are sanitized, written to a durable local FIFO spool in VS Code's global extension storage, then uploaded to CaptureWebService. Spooled events carry only a non-secret token hash/service identity so events from an old token are not uploaded under a new token. Offline recording is allowed only after the same token and service URL have previously been verified as capture-enabled; a token disabled by the portal remains disabled while the service is unavailable. If the network or service is unavailable after the token has been accepted at least once, queued events remain in the spool and upload as soon as the matching token and service are available again. The capture service endpoint can be changed in the user-level CodeChatEditor.Capture.ServiceBaseUrl setting; workspace values are ignored for this token-bearing endpoint. Token-bearing requests require HTTPS except for localhost development endpoints.

Structure

The CodeChat Editor divides source code into code blocks and documentation (doc) blocks. These blocks are separated by newlines; the image below shows the style guide on the left in the Visual Studio Code (VSCode) text editor, while the right pane shows the same text from style guide in the CodeChat Editor (using the VSCode extension). Specifically, this screenshot shows:

• ❶: a doc block. Doc blocks must have one space after the comment delimiter.
• ❷: a code block. Comments on the same line as code are not interpreted as doc blocks.
• ❸: varying indents before a doc block.
• ❹: Markdown in a doc block; see a brief overview of Markdown.

See the style guide for more examples.

Editing

Edits may be made either in the IDE hosting the CodeChat Editor, or within the CodeChat Editor window itself. Edits made in one place are transferred to the other after a short delay.

Navigation

Switching documents in the IDE likewise switches the document shown in the CodeChat Editor. Likewise, following hyperlinks in the CodeChat Editor to a local file loads that file in the IDE, as well as showing it in the Editor.

References to other files

The CodeChat Editor supports hyperlinks to any recognized file type; to refer to another source file, simply insert a hyperlink to it. For example,

Source	Rendered
[docs/style_guide.cpp](docs/style_guide.cpp)	Style guide
[LICENSE.md](LICENSE.md)	License

As usual, hyperlinks are relative to the current file; to refer to the style guide, use docs/style_guide.cpp, since this file resides in the docs/ subdirectory:

README.md (this file)
LICENSE.md
docs/
  style_guide.cpp
  monitor.png

Images

Likewise, the path to local images is relative to the current file's location (see the preceding diagram for the location of monitor.png). For example [1],

Source	Rendered


The CodeChat Editor disallows drag-and-drop of images, the result is a mess -- the image data is embedded directly in the source file. Avoid this; instead, place images in a separate file, then reference them as shown above.

Projects

The CodeChat Editor can either display a single file, or a project. In a project, the table of contents is displayed on the left, while a file within the project is displayed on the right. To create a project, simply place a file named toc.md at the root of your project [2]; its contents define the table of contents. See the new project template for a simple example.

Mathematics

The CodeChat Editor uses MathJax to support typeset mathematics. Place the delimiters $ immediately before and after in-line mathematics; place $$ immediately before and after displayed mathematics. For example,

Source	Rendered
$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$	$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$
$$a^2$$	$$a^2$$

See Latex Mathematics for the syntax used to write mathematics expressions.

Diagrams

Mermaid

The CodeChat Editor supports diagrams created by Mermaid. For example,

Source	Rendered
```mermaid graph TD; A --> B; ```	graph TD; A --> B; Loading

The Mermaid live editor provide an focused environment for creating Mermaid chart.

Graphviz

The CodeChat Editor supports diagrams created by Graphviz. For example,

Source	Rendered
```graphviz digraph { A -> B } ```	digraph { A -> B }

Several on-line tools, such as Edotor, provide a focused editing experience.

PlantUML

PlantUML transforms a hyperlink to a user-defined diagram directly to an SVG; for example,

Source	Rendered


To edit these diagrams, paste the URL into the PlantUML web server, click Decode URL, edit, then copy and paste the SVG URL back to this file.

Drawing programs

Images files produced by drawing programs can be included, as long as they can be saved in a web-compatible format (PNG, SVG, JPG, GIF, etc.). For example, the draw.io editor embeds source data into the resulting image, so the image below can be directly edited by that package:

Supported languages

• C/C++
• C#
• CSS
• Go
• HTML
• Java/Kotlin
• JavaScript/ECMAScript and TypeScript
• JSON with comments (JSON5)
• Markdown
• MATLAB
• Python
• Rust
• Shell scripts (.sh)
• SQL
• Swift
• TOML
• VHDL
• Verilog/SystemVerilog
• Vlang
• YAML

Issues and feature requests

Please report issues and provide suggestions for improvement using the Github page for this project. Contributions to the code are welcome and encouraged!

License

Copyright (C) 2025 Bryan A. Jones.

This file is part of the CodeChat Editor.

The CodeChat Editor is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

The CodeChat Editor is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with the CodeChat Editor. If not, see https://www.gnu.org/licenses/.

Notes

1. The image used comes from Monitor icons created by prettycons - Flaticon.
2. Note that the filename for the table of contents is lowercase; while the acronym is TOC, requiring upper-case naming can cause confusion when moving files between case-insensitive filesystems (Windows) and case-sensitive filesystems (Linux/OS X).