ChapterWise Codex Extension

Transform .codex.yaml and .codex.json editing into a Scrivener-like writing experience with tree navigation, distraction-free prose editing, powerful transformation commands, and format validation.

Features

📚 Codex Navigator (Tree View)

A sidebar tree view showing all nodes in your Codex file:

• Hierarchical view of your document structure
• Filter by type (chapters, characters, locations, etc.)
• Click to navigate directly to any node in the file
• Include directive support — shows referenced file paths
• Context menu with Go to YAML and Copy ID
• Auto-refresh when files are saved

✍️ Writer View

Distraction-free prose editing:

• Serif typography for comfortable reading
• Dark theme matching Cursor/VS Code
• Auto-save on blur or after 2 seconds of inactivity
• Word count and character count
• Keyboard shortcuts (Ctrl+S to save)

✅ Validation & Diagnostics

Real-time format checking:

• Schema validation for Codex V1.0 and V1.1
• Problems panel integration
• Inline squiggly underlines for errors
• Quick fixes for common issues:
  • Add missing metadata
  • Add formatVersion
  • Generate UUIDs for missing IDs
  • Convert from legacy format

💥 Explode Codex

Extract child nodes into separate files for modular organization:

• Filter by type — only extract specific node types (characters, locations, etc.)
• Custom output folder — choose where extracted files are saved
• Dry run mode — preview changes before executing
• Include directives — automatically replaces extracted nodes with include: references
• Git-friendly — perfect for version control and collaboration

Command: ChapterWise Codex: Explode Codex

🔄 Implode Codex

Merge included files back into the parent document:

• Recursive processing — follows includes within included files
• Backup creation — optionally save a backup before modifying
• Source file cleanup — delete original files after merging
• Empty folder removal — cleans up folders that become empty
• Dry run mode — preview what will be merged

Command: ChapterWise Codex: Implode Codex (Merge Included Files)

📊 Update Word Count

Track word counts across your manuscript:

• Counts body fields — tallies words in all body content
• Updates attributes — adds/updates word_count attribute on each node
• Recursive counting — processes all children
• Include support — optionally count words in included files

Command: ChapterWise Codex: Update Word Count

🏷️ Generate Tags

AI-powered tag extraction from your content:

• NLP-based analysis — extracts meaningful terms and phrases
• Unigrams and bigrams — captures both single words and two-word phrases
• Heading boost — terms in markdown headings get extra weight
• Stopword filtering — removes common words automatically
• Two output formats:
  • Simple — array of tag strings
  • Detailed — objects with name and count fields
• Configurable options:
  • Max tags (1-100)
  • Min occurrences threshold
  • Follow includes

Command: ChapterWise Codex: Generate Tags

📝 Snippets

Quick templates for common node types:

Getting Started

1. Install the extension from VSIX or marketplace
2. Open a .codex.yaml file (or create one using snippets)
3. Click the Codex icon in the activity bar to open the Navigator
4. Click any node to navigate to it in the editor
5. Use commands via the Command Palette (Cmd+Shift+P / Ctrl+Shift+P)

Commands

Access all commands via the Command Palette:

Keyboard Shortcuts

Codex Format

This extension supports the ChapterWise Codex Format V1.1.

Minimal Example

metadata:
  formatVersion: "1.1"

id: "my-book"
type: book
name: "My Novel"
summary: |
  A brief description of my book.

children:
  - id: "ch-1"
    type: chapter
    name: "Chapter 1"
    body: |
      The story begins...

Include Directives

Modularize your codex with includes:

children:
  - include: "./characters/protagonist.codex.yaml"
  - include: "./chapters/chapter-01.codex.yaml"
  - include: "./locations/castle.codex.yaml"

Tags (Simple Format)

tags:
  - protagonist
  - roman-era
  - awakened

Tags (Detailed Format)

tags:
  - name: Roman
    count: 15
  - name: Awakening
    count: 8
  - name: Senate
    count: 5

File Support

Compatibility

Works with both:

• Visual Studio Code — Version 1.85.0 or later
• Cursor — All versions supported

Development

Setup

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Watch for changes
npm run watch

Testing in Cursor/VS Code

1. Run npm run watch in terminal
2. Press F5 or run "Developer: Reload Window" to test changes
3. Open Developer Tools to see console logs

Building VSIX

# Full build and package
npm run compile
npm run package

# Install in VS Code
code --install-extension chapterwise-codex-0.1.0.vsix --force

# Install in Cursor
cursor --install-extension chapterwise-codex-0.1.0.vsix --force

Documentation

Full documentation available at:

• VS Code Extension Guide
• Installation Instructions
• Feature Reference
• Codex Format Specification

License

MIT

Made with ❤️ for storytellers