OpenConsole for VS Code

A terminal in the panel of VS Code that shows Arabic and Hebrew correctly: connected letters, words in the right order, diacritics, and mixed Arabic + English lines.

VS Code's own terminal (xterm.js) draws every character on its own, from left to right, so Arabic letters are not connected and phrases read backwards. This extension adds a tab OpenConsole next to Terminal in the panel. It runs a real shell (PowerShell by default) in a Windows pseudo console and draws the rows that contain right-to-left text with the same layout that the OpenConsole console window uses (the project this extension belongs to).

العربية

Install

Windows 10 (1809) or later, VS Code 1.90 or later.

From the Marketplace (easiest): open the Extensions view in VS Code (Ctrl+Shift+X), search for OpenConsole and install it, or run code --install-extension openconsole.openconsole. Then reload the window.

With the installer: download OpenConsole-x64.zip from the Releases page of the OpenConsole project, extract it, and double-click Install.cmd (it installs the OpenConsole console and, when it finds VS Code, this extension) or Install-VSCode.cmd (only this extension). Then reload the VS Code windows that are open.

With the .vsix file alone (openconsole-<version>.vsix, from the Releases page, or build it: below):

1. Install it:

   code --install-extension openconsole-<version>.vsix
   

   or, in VS Code: Extensions view, ... menu, Install from VSIX...

2. Reload the window (Developer: Reload Window).

3. Open the panel (Ctrl+J) and choose the OpenConsole tab, or run OpenConsole: Focus Terminal from the Command Palette.

To remove it: Install-VSCode.cmd -Uninstall, or code --uninstall-extension openconsole.openconsole. (Version 0.1.0 was called openconsole.openconsole-terminal; the installer removes it.)

Why an extension, and not just a setting

VS Code draws its terminal itself (xterm.js), so a console program such as OpenConsole cannot draw inside it. The closest setting is terminal.integrated.gpuAcceleration = off (the DOM renderer): letters inside a word join, but the words stay in left-to-right order (the first word of "السلام عليكم" ends up on the left), and programs that reorder right-to-left text themselves, such as Claude Code, come out wrong. (Checked with the xterm.js that ships with VS Code 1.139.) The extension handles both.

If you would rather have the real console window than a tab, a terminal profile can open it from the + list of the terminal; see the README of the OpenConsole project ("The console window from VS Code").

What you get

• Connected Arabic letters and the right order. A phrase such as "السلام عليكم" starts on the right, letters join, numbers keep their own order, and box drawing characters end a run, so tables and text user interfaces are not swapped.
• The cursor follows the text. While you type Arabic, the cursor stays at the end where the next letter appears.
• Programs that reorder the text themselves, such as Claude Code, are detected automatically (claude.exe runs under the shell) and drawn correctly. The list is a setting.
• Screenshots with Ctrl+V. Take a screenshot and press Ctrl+V: the image is saved as a PNG file in %TEMP%\OpenConsole and its path is pasted, as when you drag a file into a console. Programs that read images by path, such as Claude Code, pick it up. The terminal draws a small [Image #1] over the long path, so the line stays readable. The text is still there: the program receives the real path, and copying the line gives it back.
• Icons. Set openconsole.iconFont to a Nerd Font to draw the icons of tools such as starship, lazygit or pi.
• Copy and paste. Ctrl+C copies when text is selected (otherwise it is sent to the program), Ctrl+Shift+C always copies, Ctrl+V, Ctrl+Shift+V and Shift+Insert paste. They work on an Arabic keyboard layout too, and pasting an item from the clipboard history of Windows (Win+V) works as well (Windows sends that paste as a Ctrl+V without a scan code).
• It follows the colours and the font of VS Code.
• Several terminals. The + in the toolbar adds another terminal to the panel, each with its own shell. As in the built-in terminal, a list appears on the right as soon as there is more than one: click a name to switch, and the x on it kills that terminal (the last one starts again instead). Restart and Clear in the toolbar act on the terminal that is shown in the panel, even when you used a terminal in an editor tab last. Clear also clears the pseudo console, so the lines you cleared do not come back when the panel is resized (that needs the conpty.dll that VS Code ships, see openconsole.useVSCodeConpty).
• OpenConsole: New Terminal in Editor (Command Palette, or the ... menu of the view) opens a terminal in an editor tab.

Rows without right-to-left text are drawn by xterm.js exactly as in the terminal of VS Code.

Settings

The cursor style, the blinking, the scrollback and the line height are taken from terminal.integrated.*.

How it works

• bin/conpty-bridge.exe (source in native/) starts the shell in a Windows pseudo console and exchanges the input, the output, the size and the list of running programs with the extension through a small binary protocol on its standard streams.
• The page in the webview is xterm.js (DOM renderer) plus two files: media/arabic-layout.js decides, with the Unicode Bidirectional Algorithm (bidi-js), which columns form right-to-left runs and where each run is drawn (mirrored inside the columns it occupies), and media/row-patcher.js rebuilds only the rows with right-to-left text: each run is one box that the browser shapes as a whole (this joins the letters) and fits into its columns.
• The design is the one of the renderer of the OpenConsole console window (src/renderer/atlas in this repository).

Limits

• Windows only (x64). The shell needs a pseudo console, so Windows 10 version 1809 or later.
• This is not the built-in terminal: no splits, links, shell integration, quick fixes, terminal profiles or task terminals. Some keys go to VS Code instead of the shell when they are not handled by the terminal.
• With an Arabic keyboard layout active, PSReadLine (the command line editor of PowerShell) types the Arabic letter of the key for shortcuts such as Ctrl+L, Ctrl+A or Ctrl+E, instead of running them. We saw this with the shortcut arriving correctly at the pseudo console, so it is how PSReadLine reads it, and it is not specific to this extension. Switch to the English layout for these shortcuts. Pasting (Ctrl+V, also from the clipboard history of Windows, Win+V) and copying a selection with Ctrl+C work in any layout.
• Selecting part of an Arabic run with the mouse highlights columns that do not line up with the letters (copying gives the right text).
• The DOM renderer is slower than the GPU renderer when a program writes very fast.
• Tested with VS Code 1.139 on Windows 11 with PowerShell 5.1, and with a stand-in for Claude Code. Hebrew uses the same code as Arabic.

Build it yourself

You need Node.js and, for the helper program, the Visual Studio C++ build tools (as for the console window).

cd vscode-extension
npm install
npm run build          # copies xterm.js and bidi-js into media/vendor
npm run build:native   # builds bin/conpty-bridge.exe
npm test               # layout, session and helper tests
npm run package        # writes openconsole-<version>.vsix

To try it without installing, open this folder in VS Code and press F5 (Extension Development Host).

test/e2e has scripts that start a separate VS Code with the extension and take screenshots of it through the debugging port (run.ps1, send.ps1, cdp.js); they were used to check the extension.

License

MIT, see the file LICENSE. xterm.js and bidi-js are MIT licensed as well (texts in media/vendor/LICENSES.txt).

Who made this

I'm yousef0688, and I work at Software House for System Development (Arabic: دار البرمجيات لتطوير الأنظمة), a Jordanian software company based in Amman. The source code, and the console window that this extension belongs to, are at github.com/yousef0688/OpenConsole-Arabic-Terminal.

code --install-extension openconsole.openconsole