vb6-project

VB6 Project Development

How It Works — Encoding Protection

VB6 source files (.bas, .cls, .frm, .rc) are ANSI encoded (Big5, Shift-JIS, GBK, etc.) with CRLF line endings. Claude Code's Edit and Write tools output UTF-8, which would destroy these files.

This plugin uses a hook-based transparent conversion system to make Read/Edit/Write all safe:

 Read VB6 file          Edit/Write VB6 file    After Edit/Write
 ┌─────────────┐       ┌──────────────┐       ┌──────────────┐
 │ PreToolUse   │       │ Tool runs    │       │ PostToolUse  │
 │ (Read hook)  │       │ normally on  │       │ (Edit/Write  │
 │              │       │ UTF-8 content│       │  hook)       │
 │ ANSI → UTF-8 │  ──>  │ Claude Code  │  ──>  │ UTF-8 → ANSI │
 │ on disk      │       │ shows native │       │ + CRLF       │
 │              │       │ diff UI      │       │ on disk      │
 └─────────────┘       └──────────────┘       └──────────────┘

1. PreToolUse(Read) — Converts ANSI→UTF-8 on disk so Read can display readable content. File stays UTF-8 until Edit restores it.
2. Edit runs normally — File is UTF-8, so Edit can find/replace text. Claude Code displays native diff UI.
3. PostToolUse(Edit) — Restores UTF-8→ANSI+CRLF after Edit completes.
4. PostToolUse(Write) — Converts newly written files from UTF-8 to ANSI+CRLF. Also auto-fixes .frm format issues.

Encoding configuration

The encoding is read from .vb6-encoding in the project root (one line, e.g., big5). Supported values:

Value	Language
big5	繁體中文 (default)
shift_jis	日本語
gbk	简体中文
euc-kr	한국어
cp1252	Western European

Auto-setup on SessionStart

The plugin's SessionStart hook (session_init.py) automatically creates these files if they don't exist:

File	Purpose
.vb6-encoding	Encoding config (default: big5)
.gitattributes	CRLF line ending enforcement for VB6 files
.git/hooks/pre-commit	Safety net — restores pending files before commit

No manual setup is needed.

Safety nets

If a file is Read but never Edited (left in UTF-8), these safety nets restore it:

• SessionEnd hook — restores all UTF-8 VB6 files when session ends
• git pre-commit hook — blocks commit if UTF-8 VB6 files found
• compile.bat — restores before compiling

Important: Do not run VB6 IDE while Claude Code is editing VB6 files. The temporary UTF-8 state on disk would corrupt VB6 IDE's view of the files.

Critical Rules

1. Edit and Write tools are SAFE for VB6 files (hooks protect them)

The hooks automatically handle encoding conversion:

• Edit — Use normally for modifications. Claude Code displays native diff UI.
• Write — Use normally for creating new files. PostToolUse hook converts to native encoding + CRLF.
• Read — PreToolUse hook converts to UTF-8 so content is readable.

2. Forbidden tools (no hook protection)

Tool	Problem
sed -i	Strips CR from CRLF on Git Bash
iconv	Stops on first unconvertible char, truncates file

Creating New VB6 Files

Use the Write tool directly. The PostToolUse(Write) hook automatically converts to native encoding + CRLF.

Creating .frm files — format auto-fixed by hook

.frm files have strict format requirements. The PostToolUse(Write) hook automatically fixes these common issues:

• Begin trailing space — Begin VB.Form MyForm → Begin VB.Form MyForm (auto-added)
• Object line quoting — Object={GUID}#ver; name.OCX → Object = "{GUID}#ver"; "name.OCX" (auto-fixed)

You only need to get the content structure right (correct control nesting, property names, values). The hook handles the format quirks. For full .frm format details, consult references/frm-format.md.

Verify encoding

file Source/modified_file.bas

• Correct: ISO-8859 text, with CRLF line terminators (ANSI encodings show as ISO-8859)
• Wrong: Unicode text, UTF-8 text, with CRLF line terminators
• Wrong: ISO-8859 text (missing CRLF — line endings were stripped)

Compiling

Use the plugin's bundled compile.bat:

cmd.exe //c "cd /d <PROJECT_DIR> && ${CLAUDE_PLUGIN_ROOT}\scripts\compile.bat <PROJECT>.vbp"

• compile.bat automatically restores any pending encoding files before compiling.
• VB6 command-line compilation shows OCX loading warnings (e.g., "無法載入 '0'") — these are normal and do not affect the build result.
• Check for [OK] Compile succeeded. at the end.
• If [FAIL], read the compile.log and .log files next to the failing .frm.

Compile error line numbers

VB6 compile errors report line numbers relative to the code section of .frm files, not the absolute file line. For .frm files, the code section starts after the Attribute VB_Exposed line. To find the actual file line:

1. Find the Attribute VB_Exposed line number (e.g., line 163)
2. Add the reported error line number (e.g., 152)
3. Result = actual file line (e.g., 163 + 152 ≈ line 315)

For .bas and .cls files, the line number is counted from Attribute VB_Name (line 1 of the file), so it matches the file line directly.

Resource Files (.rc → .RES)

VB6 uses .rc resource files (STRINGTABLE) for UI strings, compiled into .RES binary. The .rc files are also ANSI encoded — Edit tool works safely on them (protected by hooks).

Auto-compile rule: If the .vbp contains a ResFile32= entry, check whether the referenced .RES file is missing or older than its corresponding .rc source. If so, compile the .rc before compiling the .vbp. VB6 links the .RES at compile time — a stale or missing .RES means the binary will have outdated or missing resource strings.

To compile .rc files:

cmd.exe //c "${CLAUDE_PLUGIN_ROOT}\scripts\compile_rc.bat \"<PROJECT_DIR>\Source\Resource\<main>.rc\""

For full details on string ID ranges, file structure, and troubleshooting, consult references/resource-compilation.md.

Registering New Files in .vbp

After creating new .bas or .frm files, add entries to the .vbp project file. The .vbp is ASCII-safe, so the Edit tool is acceptable for this file.

• Module: Module=ModuleName; Source\filename.bas
• Form: Form=Source\filename.frm

Additional Resources

All paths relative to ${CLAUDE_PLUGIN_ROOT}:

Scripts

• scripts/compile.bat — VB6 command-line compiler wrapper (auto-restores pending files)
• scripts/compile_rc.bat — Resource compiler wrapper (.rc → .RES)
• scripts/git-pre-commit — Git pre-commit hook (auto-installed by SessionStart)

Hooks (auto-registered via hooks/hooks.json)

• hooks/scripts/session_init.py — SessionStart: creates .vb6-encoding, .gitattributes, installs git hook
• hooks/scripts/vb6_config.py — Shared config: reads .vb6-encoding, detects encoding
• hooks/scripts/vb6_pre_read.py — PreToolUse(Read): ANSI→UTF-8, file stays UTF-8 until Edit restores
• hooks/scripts/vb6_post_edit.py — PostToolUse(Edit): UTF-8→ANSI+CRLF restore
• hooks/scripts/vb6_post_write.py — PostToolUse(Write): UTF-8→ANSI+CRLF + .frm format auto-fix
• hooks/scripts/vb6_restore.py — Safety net: SessionEnd + git pre-commit + compile.bat

References

• references/frm-format.md — VB6 .frm file format specification and common mistakes
• references/resource-compilation.md — Resource file workflow, string ID ranges, troubleshooting