LangClarity

LangClarity is a preview VS Code extension that gives source-code files a persistent, editable structured-English representation. Code and English are ordinary workspace files; synchronization runs only when you choose a direction.

Features

• Interprets supported source-code files into structured Markdown at .langclarity/<source-path>.md.
• Keeps English paired on rename/move; orphans deleted sources to .langclarity/.orphaned/.
• Opens an interpretation pane with editable English Code and read-only summaries.
• Detects whether code, English, or both changed since the last sync.
• Code → English refreshes English from code.
• English → Code proposes code from edited English, shows the diff, validates syntax, and waits for approval.
• Preserves both files when a request fails or is cancelled.

When both sides changed independently, pick which is authoritative—LangClarity does not auto-merge.

Status and scope

LangClarity is a concept preview. It explores whether a persistent, editable English representation can work as a second surface alongside source code; it is not tuned for accuracy, speed, or cost. Interpretations are model-generated and may be incomplete or wrong, so review every English claim and every proposed diff before applying it.

Not affiliated with, endorsed by, or sponsored by OpenAI. Codex and ChatGPT are trademarks of OpenAI. LangClarity drives the Codex CLI you already have installed, under your own account.

Requirements

• VS Code 1.75.0+
• Trusted workspace with a saved supported source file
• Codex 0.148 or newer, already signed in via ChatGPT (codex login). Current stable releases qualify; check with codex --version.

Runs on macOS, Windows, and Linux. LangClarity looks for Codex in this order:

1. langclarity.codexExecutablePath, when set
2. The ChatGPT app's bundled Codex on macOS
3. codex on PATH — including codex.exe and npm's codex.cmd shim on Windows
4. The official installer locations: %LOCALAPPDATA%\Programs\OpenAI\Codex\bin\codex.exe on Windows, ~/.local/bin/codex on Linux and macOS

Step 4 matters because the installers extend your shell profile or user PATH, which VS Code does not always inherit — a desktop-launched window on Linux often misses ~/.local/bin. If Codex lives somewhere else entirely, set langclarity.codexExecutablePath to its absolute path.

When Codex is not signed in, LangClarity offers Sign In to Codex, which opens a terminal running codex login. Complete the browser flow, then retry the operation. The command is also available from the Command Palette.

The recorded protocol proof used macOS and Codex CLI 0.148.0-alpha.15. Windows and Linux use the same code paths and are covered by automated tests. Fresh-profile macOS acceptance and Windows/Linux certification remain release-owner checks.

Getting started

1. Open a trusted workspace and a saved supported source-code file.
2. Right-click the source in the editor or Explorer → LangClarity.
3. Choose Interpret File to create the English pair and open the interpretation pane. If a pair already exists, choose Open Interpretation instead.
4. Review the provider disclosure on first use, then edit English or sync.

The source and interpretation pane open side by side. English Code is editable with source line numbers in a gutter; Overview, Structure, and Effects are read-only summaries. Sync state appears in the pane and status bar. The pane separately marks generated repository context as current or out of date; refreshing that context is local and does not call Codex.

Right-click → LangClarity is the main entry point for interpretation, sync, and Select Codex Model and Reasoning. When only one sync action applies, the pane also shows a suggested-action button. Click the status bar when it offers a sync command (for example, when both sides changed). Open Markdown in the pane opens the raw .langclarity file beside the source.

The Command Palette exposes the same commands when they apply to the active file; use it if you prefer keyboard-driven workflows.

Supported source files

LangClarity supports JavaScript/JSX, TypeScript/TSX, Python, Java, C/C++, C#, Go, Rust, Ruby, PHP, Swift, Kotlin, Objective-C, Dart, Scala, Lua, Perl, R, Julia, Elixir, Erlang, Haskell, Clojure, F#, OCaml, Groovy, Zig, shell scripts, PowerShell, batch, SQL, Vue, Svelte, Astro, Solidity, assembly, Terraform/HCL, Nix, Makefile, and Dockerfile files.

Both the filename or extension and VS Code language mode must match the allowlist. JSON, environment files, plain text, data, general configuration, markup, Markdown, and stylesheets are not supported.

Synchronization

No AI request runs on open, save, idle, or keystroke.

Privacy and storage

Before the first model operation, LangClarity discloses that requested source and English are sent to Codex/OpenAI under your account's policies and reminds you to review files for credentials. There is no LangClarity backend.

Before each model workflow, LangClarity scans the selected content locally for common credential patterns and suspicious secret-related paths. Private-key material blocks the request. Other findings show only categories and line numbers, default to cancellation, and require an explicit Interpret Anyway choice. Detection is best-effort and never replaces reviewing the file yourself. Terraform variable (.tfvars) files are not supported.

LangClarity does not collect product telemetry, store API keys, or log source, prompts, or full paths. Codex runs in an isolated temp root; the extension requests a read-only, no-approval session, disables its known tool feature/config surfaces, and aborts when listed tool item types appear in protocol notifications. Interpretations live as ordinary Markdown in the workspace.

After the first interpretation, LangClarity can add /.langclarity/ to .gitignore—only if you choose Add to .gitignore. Decide with your team whether to commit .langclarity/ (it may contain source-derived content).

Sign-in details: OpenAI authentication guide.

MVP limits

• Source: up to 75 KiB and 2,000 lines per model operation
• English: up to 256 KiB where applicable
• Existing pairs remain openable locally even when over limits
• One operation per file, two globally; 3-minute timeout

Comments are not interpreted: a line holding only a comment gets a blank English row, while a line mixing code with a trailing comment is explained as its code alone.

AI output may be incomplete or incorrect—review English claims and every proposed diff. Related files lists direct imports only. No auto-sync, conflict merging, or multi-hop related files in this MVP.

Troubleshooting

Output: View: Toggle Output → LangClarity (redacted operational events, failure categories where applicable, and base filenames where applicable).

To build a VSIX from the repository, run npm run package:vsix.