Chroma Workspace - VS Code Extension

A comprehensive workspace management extension for Visual Studio Code that combines rich note-taking with Natural Language Highlighting, visual Kanban boards, task scheduling, and productivity analytics. Designed for professionals who need powerful project management capabilities directly in their development environment - all data stored locally on your device.

Extension Overview

Chroma Workspace brings together the best features of modern project management into VS Code:

• ** Notes with Natural Language Highlighting** - Intelligent syntax highlighting for natural language based on parts of speech
• ** Kanban Boards** - Visual task management with customizable columns and cards
• ** Task Scheduling** - Schedule tasks with recurrence patterns and time-based automation
• ** Tag System** - Organize cards and tasks with flexible tagging
• ** Accomplishments Export** - Export completed tasks for performance reviews
• ** Global Search** - Search across all notes, cards, and projects instantly
• ** 100% Local Storage** - All data stored on device using SQLite - no cloud dependencies

Perfect for professionals working in secured environments where cloud-based tools are restricted.

Key Features

Notes with Natural Language Highlighting (NLH)

Built on the proven notesnlh extension foundation with enhanced workspace integration:

• Real-time Part-of-Speech Highlighting: Automatically colorizes text based on grammar:

  • Nouns - Entities and types
  • Verbs - Actions and functions
  • Adjectives - Descriptive words
  • Adverbs - Modifiers
  • Numbers - Numeric values
  • Proper Nouns - Names and places

• Customizable Colors: Configure highlighting colors per part of speech

• Per-Note Toggle: Enable/disable NLH for individual notes

• Rich Text Support: Format notes with TODO lists, links, and cross-references

• File Format: Uses .notesnlh files for seamless compatibility

NLP Engine: Uses the Compromise NLP library for intelligent text analysis.

Kanban Board Management

Visual task tracking with full VS Code integration:

• Custom Columns: Create workflow stages (To Do, In Progress, Done, etc.)
• Two Card Types:
  • Simple Cards: Standalone tasks with rich descriptions
  • Linked Cards: Cards connected to existing notes
• Command-Based Movement: Move cards with VS Code commands
• Tag Support: Organize cards with flexible tagging

Task Scheduling & Automation

Advanced scheduling capabilities for recurring and time-based tasks:

• Scheduled Tasks View: Dedicated TreeView showing overdue, today, this week, and all tasks
• Recurrence Patterns: Daily, weekdays, weekly, bi-weekly, monthly, custom
• Time-Based Activation: Set specific times for tasks to appear on your board
• Status Bar Integration: Quick view of upcoming tasks
• Notifications: Reminders for due tasks
• Board Assignment: Tasks can be targeted to a specific board; you'll be prompted to pick a board when multiple boards exist, one board is auto-selected, and a default board+column is created if none exist.

Accomplishments Export (FUTURE FEATURE)

Performance review made easy with intelligent task aggregation:

• CSV Export: Download completed tasks in spreadsheet format
• Date Range Selection: Last 3/6/12 months or custom range
• Smart Grouping: Recurring tasks automatically grouped together
• LLM-Ready Format: CSV output optimized for AI summarization

See full documentation below for detailed feature descriptions.

Installation

Option 1: From Pre-built VSIX (Recommended)

If you have the .vsix file:

1. Open VS Code
2. Go to Extensions view (Ctrl+Shift+X)
3. Click ... menu > Install from VSIX...
4. Select chroma-workspace-0.0.1.vsix
5. Reload VS Code when prompted

Or via command line:

code --install-extension chroma-workspace-0.0.1.vsix

Option 2: Build from Source

For the complete build process, see BUILD.md.

Quick steps:

# 1. Install dependencies
npm install

# 2. Compile TypeScript
npm run compile

# 3. Bundle with esbuild
node esbuild.js

# 4. Package as VSIX (requires vsce)
npm install -g @vscode/vsce
vsce package

# 5. Install the generated .vsix file (see Option 1 above)

Option 3: Development Mode

Run without installing (for development/testing):

1. Open this folder in VS Code
2. Press F5 to launch Extension Development Host
3. Test the extension in the new window

Quick Start

1. Open a workspace folder in VS Code
2. Extension auto-creates .chroma/chroma.db
3. Create first note: Ctrl+Shift+P Chroma: New Note
4. Set up Kanban board from sidebar view

Configuration

Chroma Workspace can be extensively customized through VS Code settings. Access settings via:

• File > Preferences > Settings (Windows/Linux)
• Code > Preferences > Settings (macOS)
• Or search for "Chroma" in the settings

Natural Language Highlighting Settings

Control how notes are highlighted:

{
  "chroma.nlh.enabled": true,
  "chroma.nlh.colors.nouns": "#569CD6",
  "chroma.nlh.colors.verbs": "#4EC9B0",
  "chroma.nlh.colors.adjectives": "#C586C0",
  "chroma.nlh.colors.adverbs": "#DCDCAA",
  "chroma.nlh.colors.numbers": "#B5CEA8",
  "chroma.nlh.colors.properNouns": "#4FC1FF"
}

• chroma.nlh.enabled: Enable/disable Natural Language Highlighting (default: true)
• chroma.nlh.colors.*: Customize colors for each part of speech (hex format)

Task & Notification Settings

Control task notifications and status bar display:

{
  "chroma.tasks.enableNotifications": true,
  "chroma.tasks.notificationFrequency": "once",
  "chroma.tasks.showInStatusBar": true
}

• chroma.tasks.enableNotifications: Show notifications for due tasks (default: true)
• chroma.tasks.notificationFrequency: How often to notify about overdue tasks
  • "once": Show notification only once per task (default)
  • "hourly": Remind every hour
  • "daily": Remind once per day
• chroma.tasks.showInStatusBar: Display task count in status bar (default: true)

Export Settings

Configure accomplishments export defaults:

{
  "chroma.export.defaultDateRangeMonths": 6,
  "chroma.export.includeDescriptions": true,
  "chroma.export.groupRecurringTasks": true
}

• chroma.export.defaultDateRangeMonths: Default time range for exports (default: 6, range: 1-60)
• chroma.export.includeDescriptions: Include task descriptions in CSV export (default: true)
• chroma.export.groupRecurringTasks: Group multiple completions of recurring tasks (default: true)

Database Settings

Configure where your data is stored:

{
  "chroma.database.path": ".chroma/chroma.db"
}

• chroma.database.path: Relative path to SQLite database within workspace (default: ".chroma/chroma.db")
  • Must be a path ending in .db. You can use a relative path (default) for per-workspace databases or an absolute path (e.g. C:\\Users\\You\\shared-chroma.db or /home/you/chroma-shared.db) to share a database across multiple workspaces.
  • After changing this setting, reload the VS Code window (Developer: Reload Window) or restart VS Code for the new database location to take effect.

Local-First Architecture

• SQLite Database: All data in .chroma/chroma.db
• No Cloud Dependencies: Works completely offline
• Git-Friendly: Commit .chroma/ for version control
• Portable: Copy folder to sync manually across machines

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

License

MIT License

Acknowledgments

• notesnlh Extension: Foundation by canadaduane
• Chroma Parse Notes: Feature inspiration lilfetz22
• Compromise.js: NLP library by Spencer Kelly

Your workspace. Your data. Your device.

Releasing and Versioning

This repo uses semantic-release to automate versioning, changelog generation, GitHub releases, and VSIX packaging/publishing based on Conventional Commits.

Commit Message Format

Use the format: type(scope): subject

Common types:

• feat: New feature (triggers minor version bump: 1.0.0 → 1.1.0)
• fix: Bug fix (triggers patch version bump: 1.0.0 → 1.0.1)
• docs: Documentation changes (no version bump)
• refactor: Code refactoring (no version bump)
• perf: Performance improvements (triggers patch bump)
• test: Test additions/changes (no version bump)
• chore: Build process or auxiliary tool changes (no version bump)

Breaking changes (triggers major version bump: 1.0.0 → 2.0.0):

• Add ! after type/scope: feat(api)!: remove deprecated methods
• OR include footer: BREAKING CHANGE: description

Examples:

feat(kanban): add swimlanes to board
fix(tasks): correct timezone logic for daily schedule
fix(build): externalize bindings module in esbuild config
chore: update dependencies
feat(search)!: change search API to async

Development Workflow

1. Make changes to code
2. Build and test: npm run build && npm test
3. Stage changes: git add <files>
4. Commit with conventional format:

   git commit -m "fix(build): externalize native module dependencies"
   

5. Push to main:

   git push origin master
   

Automated Release Process (CI/CD)

When you push to master, GitHub Actions automatically:

1. Analyzes commits since the last release
2. Determines version bump (major/minor/patch) based on commit types
3. Updates package.json version
4. Generates CHANGELOG.md with all changes
5. Creates GitHub release with release notes
6. Packages VSIX file
7. Publishes to VS Code Marketplace (if VSCE_PAT repository secret is configured)

Manual Release (Optional)

For local testing or manual releases:

npm run build
npm run release

Requirements:

• GITHUB_TOKEN environment variable (for GitHub release)
• VSCE_PAT environment variable (optional, for marketplace publishing)

Note: Normally releases are performed automatically via GitHub Actions. Manual releases are only needed for testing the release process locally.

Marketplace Publishing Setup

To enable automatic publishing to the VS Code Marketplace:

1. Create a Personal Access Token (PAT) at https://dev.azure.com/
   • Organization: All accessible organizations
   • Scopes: Marketplace (Acquire, Manage)
2. Add the PAT as a repository secret named VSCE_PAT in GitHub Settings → Secrets
3. Push commits to master - extension will auto-publish on release