Codex Note Helper

日本語

Fill selected Markdown sections with research, general, or job-search notes generated by Codex CLI. Review a structurally validated VS Code diff and choose Apply or Discard—no generated change is applied automatically.

Animated capture of Codex Note Helper running in an isolated VS Code window with synthetic note data: Markdown editing and preview, generation progress, diff review, explicit Apply, and the unsaved result.

Captured in an isolated VS Code profile with fixed synthetic note and proposal data. Recording does not invoke Codex or include account, host-specific path, or provider data.

Install from the VS Code Marketplace

code --install-extension trinitrotorol.codex-note-helper

The extension itself is free. Running Codex can consume included or purchased plan usage and, depending on the configured CLI provider, can incur provider charges. Codex authentication and provider terms still apply. Codex Note Helper does not require or store a separate API key.

60-second quick start

Install and sign in to a compatible Codex CLI on the local or remote VS Code extension host. Alternatively, install the official OpenAI VS Code extension and explicitly select its bundled CLI.
Install Codex Note Helper and run Codex Notes: Choose Codex CLI Source.
Run Codex Notes: Run Diagnostics. Diagnostics checks the executable and required CLI flags; it does not send note content or submit a note-generation request.
Open a saved Markdown file in a trusted window and add a heading:
```
# Hamiltonian simulation
```
Run Codex Notes: Generate and Review Target Heading Updates.
Inspect the diff, then explicitly Apply or Discard it. If the notification hides, use the persistent status-bar item or any of the pending-review commands—reopening a review does not run Codex again.

Codex Note Helper intentionally provides no default keyboard shortcut, avoiding conflicts with VS Code and other extensions. Assign one from Keyboard Shortcuts if desired.

What it does

The extension finds sections at one configured Markdown heading level and asks Codex CLI for a structured proposal. It supports three generation modes:

research: concise research notes; references are included only when they can be verified, and web search remains opt-in.
general: concise explanatory notes without mandatory references.
jobHunting: company, role-fit, selection, and interview-preparation notes.

Target policies let you update only empty sections, empty or source-bullet-only sections, or every matching section. Existing human text is preserved; generated blocks are isolated with extension-owned markers.

Safety at a glance

Target heading titles, the current Markdown for every selected section, and generation preferences are sent to the configured Codex CLI. Workspace and file paths plus unselected note text are not placed in the prompt. If the target policy selects every matching section, the combined selected content can contain most of the note.
Codex runs from extension-owned storage in a read-only, ephemeral sandbox; repository rules are ignored, approval mode is fixed to never, and shell, app, hook, and multi-agent tools are disabled.
Web search is off by default. Enabling it, or enabling Codex user configuration, forces a confirmation on every run.
Every event and structured update is bounded and checked. A successful process exit alone never authorizes an edit.
The same open document instance, version, and text are rechecked before apply. A stale, closed, or reopened document invalidates the proposal.
A diff and explicit decision are mandatory. A hidden or cleared notification leaves the proposal pending; it is not treated as Discard.

Structural validation does not guarantee factual correctness. Review generated content and sources. Do not use confidential notes until the configured Codex provider and its retention policy are acceptable. See Security for the complete threat model and controls.

Codex Note Helper itself sends no separate analytics or usage telemetry. VS Code, the Codex CLI, and the configured provider have their own policies and settings.

Requirements

VS Code 1.85.0 or newer.
A trusted VS Code window and a saved local or remote Markdown file.
A compatible Codex CLI available from PATH, an explicitly configured absolute path, or an explicitly enabled bundle from the official OpenAI VS Code extension.
Codex authentication on the extension host. For Remote SSH, WSL, Dev Containers, and Codespaces, install and authenticate the CLI remotely.

Only file and vscode-remote documents are accepted. Untitled documents, Git/diff documents, virtual workspaces, and untrusted workspaces are rejected.

Commands

Command	Purpose
Generate and Review Target Heading Updates	Generate, validate, and open a mandatory diff.
Review Pending Changes	Reopen an existing diff without another Codex request.
Apply Pending Changes	Apply the active validated proposal after a fresh snapshot check.
Discard Pending Changes	Explicitly discard the active proposal.
Cancel Active Run	Cancel generation or invalidate a pending review.
Choose Codex CLI Source	Choose `PATH`, an available official bundle, or open the absolute-path setting.
Run Diagnostics	Verify storage, trust, executable permission, CLI version, and required flags.
List Target Headings	Preview sections selected by the current heading level and policy.
Set Generation Mode	Select research, general, or job-hunting notes.
Set Target Policy	Select which heading sections are eligible.
Delete Diagnostic Log	Delete only the extension-owned failure log.

Settings

Setting	Default	Purpose
`codexNoteHelper.mode`	`research`	Generation profile.
`codexNoteHelper.fillPolicy`	`emptyOnly`	Eligible heading sections.
`codexNoteHelper.researchField`	empty	Optional research context.
`codexNoteHelper.outputLanguage`	English or Japanese UI default	Requested output language.
`codexNoteHelper.noteStyle`	empty	Optional style instruction.
`codexNoteHelper.headingLevel`	`1`	Exact target heading level, H1–H6.
`codexNoteHelper.codexCommand`	`codex`	Machine-scoped executable name or absolute path.
`codexNoteHelper.allowBundledCodexFromOpenAIExtension`	`false`	Allow the official extension bundle only after explicit opt-in.
`codexNoteHelper.enableWebSearch`	`false`	Allow additional network search for source verification.
`codexNoteHelper.showCodexProgress`	`true`	Show bounded fixed-stage progress.
`codexNoteHelper.timeoutSeconds`	`300`	Stop after 30–1800 seconds.
`codexNoteHelper.maxTargetHeadings`	`25`	Maximum targets in one run.
`codexNoteHelper.maxInputCharacters`	`500000`	Maximum active-document size.
`codexNoteHelper.maxOutputBytes`	`1048576`	Maximum captured CLI output.
`codexNoteHelper.confirmBeforeRun`	`appendAlways`	Control routine target-summary confirmations.
`codexNoteHelper.ignoreCodexUserConfiguration`	`true`	Run with `--ignore-user-config` while retaining CLI authentication.
`codexNoteHelper.applySaveBehavior`	`leaveUnsaved`	Leave applied edits unsaved, or save only if the note was clean immediately before Apply. VS Code Auto Save still applies.

English VS Code uses English as the output-language default; the Japanese catalog uses Japanese. An explicit user or workspace setting always wins.

Troubleshooting

Codex CLI was not found

Run Choose Codex CLI Source. PATH is recommended. When the official OpenAI extension contains a bundled CLI, the error action can open its dedicated setting; the extension never enables that fallback automatically. Every source still goes through real-path checks, SHA-256 fingerprint consent, and a compatibility probe.

Apply or Discard disappeared

The proposal remains pending. Use the status-bar item, Review Pending Changes, Apply Pending Changes, or Discard Pending Changes. Editing, closing, or reopening the source note invalidates the proposal instead of applying stale content.

Diagnostics failed

The Diagnostics output shows a bounded reason code and remediation without raw paths, note text, prompts, model output, stdout, stderr, or stack traces. The extension-owned failure log can be opened from the error action and deleted with Delete Diagnostic Log.

Documentation and support

When reporting a bug, never attach note content, prompts, full paths, raw process output, credentials, or tokens. Use GitHub Security Advisories when private reporting is available; otherwise open a minimal issue without sensitive data.

License

MIT