VS Code Extension

The VS Code Extension brings full editor support for the CodeCharter DSL. When you write custom .ccr rules, you get syntax highlighting, snippets, and auto-completion for schema properties.

Installation

The extension requires VS Code 1.85 or later. Downloading from the portal requires a signed-in account with an active subscription.

1. Get codecharter-X.Y.Z.vsix from the portal downloads.
2. In VS Code: Command Palette → "Extensions: Install from VSIX..." → select the downloaded file.

Note: VS Code will show a security prompt about an unverified publisher when installing a VSIX file that is not from the Marketplace. This is expected. Confirm to proceed with the installation.

Alternatively via CLI:

code --install-extension codecharter-X.Y.Z.vsix

The Windows installer offers this as a pre-selected setup option when it detects a VS Code installation.

The extension requires the CodeCharter CLI for all language features: the language server is provided by the CLI itself. If no CLI is found, the extension shows an error on activation and completion and validation do not work. The CLI is auto-detected on the PATH (executable names codecharter, CodeCharter.Cli, or CodeCharter.Cli.exe) or configured via codecharter.serverPath.

Features

• Syntax highlighting for .ccr files with a dedicated tokenizer.
• Snippets for common rule skeletons.
• Auto-completion for schema properties (TypeModel, MethodModel, and others) via a language server provided by the CodeCharter CLI.
• Inline validation of rule syntax. Typos in property names are flagged immediately in the editor.
• Spec testing with CodeLens actions: "Run spec" and "Scaffold spec" appear on .ccr and .spec.md files; failing cases show up in the Problems panel.

When your codecharter.yml declares portal profiles, the extension runs codecharter restore on activation, shows the active rule set in the status bar, and warns when codecharter.lock.json is newer than the rule cache.

The extension also receives rule drafts from the portal: Open in VSCode in the portal rule editor pulls the current draft into VS Code, and CodeCharter: Push to portal sends it back as a draft. The full round trip is described under Editing rules in VS Code.

Commands in the Command Palette

• CodeCharter: Validate current rule file
• CodeCharter: Analyze workspace (.sln/.csproj)
• CodeCharter: Test rule spec
• CodeCharter: Test all specs
• CodeCharter: Scaffold spec for current rule
• CodeCharter: Restart language server
• CodeCharter: Show language server output

Analyze workspace runs the CodeCharter CLI on the solution or project in the VS Code terminal. Findings appear there as console output.

Configuration

Settings under codecharter.* in VS Code settings:

Setting	Default	Description
codecharter.serverPath	empty	Path to the CodeCharter CLI. Empty = auto-detect from PATH. Supports ${workspaceFolder} and ${userHome}.
codecharter.analyze.rulesDirectory	empty	Rules directory for Analyze workspace. Empty = the CLI's default resolution: ./rules in the workspace, otherwise the rule set shipped with the CLI.
codecharter.trace.server	off	Trace LSP communication (off, messages, verbose).
codecharter.portalBaseUrl	https://codecharter.tools	Portal address for the rule-draft handoff, see Editing rules in VS Code.

Other editors

The language server is not tied to VS Code. The CLI command

codecharter lsp

starts the CodeCharter DSL language server speaking the Language Server Protocol over stdio (stdin/stdout). Any LSP-capable editor can attach it to .ccr files: configure your editor to launch codecharter lsp as a stdio language server for the .ccr file extension; how to wire up a stdio server is described in your editor's LSP documentation.

The server provides:

• Diagnostics, published when a file is opened or changed.
• Completion for schema properties, triggered by @, ., and space.
• Hover information.
• Semantic tokens (full document) for syntax highlighting.
• Code actions for reported diagnostics.

Document sync is full-document; the server does not support incremental sync. Like every CLI command, codecharter lsp runs the license check on startup and accepts --license to point at a specific codecharter.license file.

Note that VS-Code-specific features described above (snippets, CodeLens spec actions, codecharter restore on activation, status bar) come from the extension, not from the language server, and are not available in other editors.

Troubleshooting

If the language server does not start:

1. Open the Output panel (View → Output) and select CodeCharter in the dropdown.
2. Check the CLI path. If the CLI is not on the PATH, set codecharter.serverPath explicitly to the full path.
3. Check permissions on Linux and macOS. The binary must be executable (chmod +x codecharter).
4. Enable LSP tracing for detailed diagnostics: set codecharter.trace.server to messages or verbose in VS Code settings. Reset to off when done.

More under VS Code Extension hangs.