OptionOS for VS Code

Lets OptionOS open your coding agents (Claude Code, Codex) in a VS Code terminal, paste the text you dictate, and show commits and Claude Code chats in VS Code.

What is OptionOS and where do I get it?

OptionOS is a macOS menu bar app. Its Agents panel shows your coding agents and opens new ones. Get it at optionos.app.

What do I need to do now?

Nothing. The extension starts by itself when VS Code opens. It adds no settings.

The first time OptionOS opens an agent in VS Code, VS Code asks "Allow 'OptionOS' extension to open this URI?". Press Open. Tick Do not ask me again for this extension if you do not want VS Code to ask on every new agent.

Do I need OptionOS?

Yes. Every feature below starts from OptionOS: it opens the agent, it sends the dictated text, it sends the commit and chat links. Without OptionOS the extension waits and does nothing visible.

What does it do?

• Opens an agent in a terminal. When you pick Claude Code or Codex in the OptionOS Agents panel and VS Code is where your agents run, OptionOS sends VS Code a vscode://optionos.optionos-agent/launch/… link. The extension opens a new terminal named Agent in the folder you chose and runs the agent's command there.
• Pastes dictated text. If you dictate with OptionOS while VS Code is in front, press the F19 key in an editor or a terminal and the text goes there. In a terminal it is pasted, not run: nothing is sent with Enter.
• Opens a commit. When OptionOS sends a commit link (one commit or several, and the repository folder), the extension shows the commit in VS Code's diff view. If you open a commit link file in VS Code, it opens the commit the file names and closes the link file.
• Shows a Claude Code chat. When OptionOS sends a chat link, the extension shows that part of a Claude Code conversation as a Markdown preview. A live chat link keeps the preview updated while the conversation grows, and stops when you close the tab.

Can a web page make it run a command?

No. A launch link carries a one-time key. Before it sends the link, OptionOS writes that key as a file in ~/Library/Application Support/app.optionos/vscode/launch-keys/, readable only by your Mac user. The extension runs the command only if that file exists, and deletes the file before it runs anything, so the same link never works twice. A web page can open a vscode:// link but cannot write that file, so its link is refused, even if you ticked Do not ask me again.

What can OptionOS ask the extension?

OptionOS talks to the extension through a socket file on your Mac. Through it OptionOS can:

• check that the extension is running and which version it is,
• paste dictated text into the editor or terminal in front,
• read the text you have selected in the editor,
• list your open editor tabs (their names and file paths) and bring one of them to the front,
• reload the VS Code window.

The extension answers only these requests and nothing else.

What does it read?

• Your VS Code terminals: their names, process numbers, folders and which one is in front.
• The file you are editing: its name and path, the selected and visible line numbers, whether it has unsaved changes, the workspace name, whether the window is in front.
• The text you have selected in the editor, only when OptionOS asks for it.
• The names and file paths of your open editor tabs, only when OptionOS asks for them.
• The commit a commit link names, from that repository, to show its changes.
• The Claude Code conversation a chat link names, from Claude Code's own conversation files on your Mac (~/.claude/projects/).

It does not read the contents of your other files.

Does it type into my terminal?

Only in two cases, both started from OptionOS:

• Opening an agent. It opens a new terminal named Agent and runs there the agent command OptionOS sent (for example claude). It does not type into any other terminal.
• Dictated text. When you press F19 in a terminal, it pastes the dictated text into the terminal in front. The text is pasted, not run: nothing is sent with Enter.

What does it write on my Mac?

• A list of your VS Code terminals (name, process number, folder, which one is in front) in ~/Library/Application Support/app.optionos/vscode/terminals/, one file per VS Code window. OptionOS reads it to find the terminal an agent runs in.
• A small file about the file you are editing (its name and path, the selected and visible line numbers, whether it has unsaved changes, the workspace name, whether the window is in front) in your Mac's temporary folder, under app.optionos.vscode/focus/. OptionOS reads it to know what you are looking at.
• The socket file OptionOS talks through, in ~/Library/Application Support/app.optionos/vscode/hosts/.
• One line for each commit link and each chat link you open (the time and the link), in ~/Library/Application Support/app.optionos.vscode-commit/opens.jsonl and ~/Library/Application Support/app.optionos.vscode-chat/opens.jsonl.

The terminal list, the file about the file you are editing and the socket are readable only by you, and are deleted when the VS Code window closes. The two link lists stay.

Does it send anything over the internet?

No. The only connection it opens is the socket file on your own Mac.

Does it slow VS Code down?

Not measured yet.

Something doesn't work. Where do I look?

How do I turn it off or remove it?

In the Extensions view, choose Disable or Uninstall. When the extension stops, it deletes the terminal list, the file about the file you are editing, and its socket file. The two link lists (opens.jsonl under app.optionos.vscode-commit and app.optionos.vscode-chat) stay; delete them if you want.

Is it free? Is it open source?

The extension has no payment code and asks for no account. Its license is not an open source license: the package is published as UNLICENSED. OptionOS itself is a separate app; see optionos.app for its terms.

Which systems does it run on?

macOS only. It is published for Mac (Apple silicon and Intel), so VS Code on Windows or Linux does not offer it.