Code Mantra

Remind yourself of programming principles with customizable notifications in VS Code.

Code Mantra helps you build better coding habits by showing timely reminders of programming principles while you code. Whether you're a beginner learning best practices or an experienced developer who wants gentle nudges to maintain code quality, Code Mantra keeps important principles top of mind.

✨ Features

🔔 Multiple Trigger Types

Show notifications when you need them:

On Save (recommended) - Get reminders before committing changes
On Edit - Gentle nudges while coding with configurable debouncing
On Open - Start each file with a principle reminder
On Focus - Get refreshed when switching between files
On Idle - Encourage breaks or suggest different approaches after inactivity

⏰ Time-Based Notifications

Stay healthy and productive with periodic reminders:

Work Break Reminders - Regular intervals to step away from your screen
Pomodoro Timer - Built-in 25-minute work session support
Custom Timers - Create your own interval patterns
Auto-Reset - Optionally reset timers on file save or focus events

🎯 Smart Targeting

25+ Programming Languages - Support for all major languages
Glob Pattern Exclusions - Easily ignore node_modules, dist, and other directories
Custom File Patterns - Target specific file types with your own rules
Rate Limiting - Automatic spam prevention (minimum 3-second intervals)

🧭 Trigger Management Panel

Manage every reminder visually from the dedicated Code Mantra activity bar panel:

Tree View Overview - See all active triggers grouped by type at a glance
Inline Actions - Edit, enable/disable, reorder, or delete without leaving the panel
Quick Add - Use the ➕ button or command palette (Code Mantra: Add Trigger) to create new rules with guided validation
One-Click Refresh - Keep the list in sync after manual settings.json edits using the 🔄 action

📚 Built-in Wisdom

Pre-configured reminders from "The Pragmatic Programmer":

ETC - Easier To Change?
DRY - Don't Repeat Yourself
Add Your Own - Fully customizable message system

🚀 Quick Start

Install the extension from the VS Code Marketplace
Start coding - Code Mantra works out of the box with sensible defaults!
Customize (optional) - Open VS Code Settings (Ctrl/Cmd + ,) and search for "Code Mantra" to personalize your experience

First-Time Setup

By default, Code Mantra will show reminders when you save files in any supported programming language. This is the recommended setting for most users.

To enable additional features:

⏰ Enable time-based notifications for work break reminders
✏️ Enable edit triggers for real-time coding reminders
🎨 Customize messages to match your coding philosophy

🙌 Join the Community

⭐ Star the repo to help more developers discover Code Mantra
🐞 Report issues with reproduction steps so we can fix problems fast
💡 Request features or share workflows that would make the extension better
🤝 Open pull requests—we love collaborating on improvements
📝 Leave a Marketplace review once Code Mantra boosts your habits

Usage

Default Behavior

When you save a file, Code Mantra will randomly show one of the configured principle reminders:

"ETC? (Easier To Change?)" - Is your code easy to change?
"DRY? (Don't Repeat Yourself)" - Are you avoiding repetition?

Manage Triggers Visually

Open the Code Mantra item in the VS Code activity bar.
Use the Triggers tree view to see every configured rule and timer.
Hover over a trigger to reveal inline actions for edit, toggle, move, or delete.
Click the Add Trigger button to launch guided dialogs with input validation.

Run a Test Notification

Open the Command Palette and run Code Mantra: Test Notification to preview how toasts will appear in your editor.

🔔 Notification Priority and Suppression

Code Mantra uses smart notification suppression to prevent annoying duplicate notifications when multiple triggers fire at the same time.

Understanding the Suppression Rules

To help you build better coding habits without notification fatigue, Code Mantra implements the following rules:

Rule 1: File Creation Suppression (onCreate → onSave)

When you create a new file and immediately save it, you'll see one notification instead of two:

✓ File created notification
✗ Save notification (suppressed for 500ms)

Example:

Create a new file using File → New File
Type some code
Save the file immediately (within 0.5 seconds)

→ Result: Only "New file created" notification, no duplicate "saved" notification

Note: If you create a file, wait more than 0.5 seconds, then save, you'll see both notifications.

Rule 2: Edit Suppression (onSave → onEdit)

When you save a file, edit triggers are suppressed for 500ms to prevent notifications from overlapping:

✓ Save notification
✗ Edit notification (if within 500ms of save)

Example:

Edit code for 3 seconds
Save the file
If your onEdit trigger fires within 0.5 seconds of the save event, it will be suppressed

Rule 3: Save Operation Protection

During file saves (when formatters or other plugins are modifying the file), all change-based triggers are suppressed:

onLargeDelete notifications won't fire during save operations
onEdit notifications are suppressed while the file is being saved
This prevents false positives from formatter-induced changes (e.g., Prettier auto-formatting)

Trigger Types and When They Fire

Trigger	When it fires	Suppressed by
onCreate	When a new file is created in your workspace	(none)
onSave	When you save a file	onCreate (for 500ms after create)
onLargeDelete	When you delete 100+ lines in one operation	Save operations
onFileSizeExceeded	When a file crosses the line count threshold	Save operations
onEdit	After you stop editing for 5 seconds (configurable)	onSave (for 500ms after save)

Default Thresholds

Large Delete Threshold: 100 lines
File Size Threshold: 300 lines
Edit Debounce: 5 seconds
Suppression Window: 500ms

Customizing Suppression Behavior

(Future feature: Configuration support coming soon)

Currently, suppression rules are fixed. Future versions may allow customization through settings.

🔧 Technical Details: Suppression Timing

The suppression window is 500ms for onCreate→onSave and onSave→onEdit rules. This timing was chosen to handle:

Auto-formatting plugins (Prettier, Beautifier, etc.)
Rapid consecutive actions
Debounce completion timing for edit triggers

Configuration

Using VS Code Settings UI (Recommended)

Open VS Code Settings:
- Windows/Linux: Ctrl+, or File → Preferences → Settings
- macOS: Cmd+, or Code → Settings → Settings
Search for "Code Mantra" in the search box
Configure options using checkboxes, text inputs, and dropdowns:
- Enable/Disable: Toggle the main switch
- Triggers: Use checkboxes to enable/disable each trigger type
- Edit Delay: Adjust the delay slider (1000-10000ms)
- File Types: Add/remove language IDs from the list
- Exclude Patterns: Add glob patterns to exclude files

Using settings.json (Advanced)

Alternatively, you can edit settings.json directly:

Enable/Disable

{
  "codeMantra.enabled": true
}

Triggers

Configure when notifications should appear:

{
  "codeMantra.triggers": {
    "onSave": {
      "enabled": true
    },
    "onEdit": {
      "enabled": false,
      "delay": 5000
    },
    "onOpen": {
      "enabled": false
    },
    "onFocus": {
      "enabled": false
    }
  }
}

Available Triggers:

Trigger	When it fires	Recommended use
`onSave`	After saving a file	Best default option before committing changes.
`onEdit`	While editing (after a delay)	Gentle nudges without interrupting flow thanks to debouncing.
`onOpen`	As soon as a file opens	Kick off work with a reminder when you start editing.
`onFocus`	When the editor gains focus	Helpful when switching between files or windows.
`onWorkspaceOpen`	When VS Code starts	Show a reminder once at startup for workspace-wide principles
`onCreate`	When a new file is created	Ask clarifying questions about file naming and structure.
`onDelete`	When a file is deleted	Remind about dependencies and related cleanup tasks.
`onLargeDelete`	When deleting many lines at once	Alert when making significant deletions (configurable lines).
`onFileSizeExceeded`	When a file grows beyond threshold	Remind to refactor when files become too large.

File Types

Specify which programming languages to show notifications for:

{
  "codeMantra.fileTypes": [
    "typescript",
    "javascript",
    "python",
    "java",
    "go",
    "rust",
    "markdown"
  ]
}

Supported Language IDs:

Web: typescript, javascript, html, css, scss, vue, svelte
Systems: rust, go, c, cpp, csharp
Mobile: swift, kotlin, dart
General: python, java, ruby, php
Data: yaml, json
Docs: markdown, mdx

Exclude Patterns

Exclude specific files or directories from notifications:

{
  "codeMantra.excludePatterns": [
    "**/node_modules/**",
    "**/dist/**",
    "**/build/**",
    "**/.git/**"
  ]
}

Custom Rules

Add your own rules in settings.json:

{
  "codeMantra.rules": [
    {
      "trigger": "onSave",
      "message": "ETC? (Easier To Change?)",
      "filePattern": "**/*.{ts,js,tsx,jsx}"
    },
    {
      "trigger": "onWorkspaceOpen",
      "message": "Welcome! Remember to follow SOLID principles today."
    },
    {
      "trigger": "onCreate",
      "message": "Is the file name clear and descriptive?",
      "filePattern": "**/*.{ts,js}"
    },
    {
      "trigger": "onDelete",
      "message": "Have you checked related dependencies?",
      "filePattern": "**/*"
    },
    {
      "trigger": "onLargeDelete",
      "message": "Big deletion - Did you really want to remove all that?",
      "filePattern": "**/*.{ts,js,tsx,jsx}",
      "deletionThreshold": 100
    },
    {
      "trigger": "onFileSizeExceeded",
      "message": "This file is getting large - Consider refactoring.",
      "filePattern": "**/*.{ts,js,tsx,jsx}",
      "lineSizeThreshold": 300
    },
    {
      "trigger": "onIdle",
      "message": "You've been coding for a while - Take a break or try a different approach!",
      "idleDuration": 15
    }
  ]
}

Property	Purpose	Notes
`trigger`	Matches one of the available trigger types	Determines when the notification shows.
`message`	Text shown in the notification toast.	Keep it short and actionable.
`filePattern`	Optional glob to scope the rule.	Example: `*/.md` (defaults to all files when omitted).
`deletionThreshold`	For `onLargeDelete`: minimum number of lines to trigger (default: 100)	Range: 1-10000 lines
`lineSizeThreshold`	For `onFileSizeExceeded`: line count threshold to trigger notification (default: 300)	Range: 1-10000 lines
`idleDuration`	For `onIdle`: minutes of inactivity before notification (default: 15)	Range: 1-120 minutes

Note: If multiple onIdle rules are defined, only the first matching rule will trigger. To receive multiple idle notifications, use different idleDuration values with proper intervals.

Time-Based Notifications

Code Mantra can show notifications at regular time intervals to remind you to take breaks or follow the Pomodoro Technique:

{
  "codeMantra.timeBasedNotifications": {
    "enabled": true,
    "intervals": [
      {
        "duration": 50,
        "message": "💡 Time to take a break! Step away from your screen.",
        "type": "workBreak",
        "enabled": true
      },
      {
        "duration": 25,
        "message": "🍅 Pomodoro complete! Take a short break.",
        "type": "pomodoro",
        "enabled": false
      }
    ],
    "resetOn": ["save"]
  }
}

Features:

⏰ Multiple Timers: Run multiple independent timers simultaneously
🔄 Auto-Reset: Optionally reset timers on specific events (save, focus)
🍅 Pomodoro Support: Built-in support for Pomodoro Technique (25 min intervals)
💼 Work Break Reminders: Long-form work session reminders (50 min default)
🎨 Custom Intervals: Define your own timing patterns

Timer Types:

Type	Description	Typical Duration
`workBreak`	Standard work break reminder	50 minutes
`pomodoro`	Pomodoro Technique timer	25 minutes
`custom`	Your own custom interval pattern	1-120 minutes

Reset Events:

save: Reset all timers when you save a file (keeps you in flow)
focus: Reset all timers when the editor gains focus

Tip: Enable resetOn: ["save"] to avoid interruptions during deep work sessions. Your timers will automatically restart each time you save, keeping you in the zone!

Installation

Open VS Code
Go to Extensions (Ctrl+Shift+X or Cmd+Shift+X)
Search for "Code Mantra"
Click Install

🛠 Troubleshooting

Reset your settings

Open Preferences: Open Settings (JSON) from the Command Palette
Remove any codeMantra.* entries to return to the defaults
Save the file and reload VS Code (Developer: Reload Window)

Reinstall the extension

Uninstall Code Mantra from the Extensions view
Close all VS Code windows, then reinstall from the Marketplace listing

Still stuck? Open an issue

Create a new ticket at github.com/is0692vs/code-mantra/issues
Include your VS Code version, Code Mantra version, relevant settings.json snippet, and any log output

Development

# Install dependencies
npm install

# Run extension in debug mode
# Press F5 in VS Code

Publishing

This project uses GitHub Actions for automated releases and marketplace publishing.

Release Workflow (GitHub Release Only)

Triggered by v* tags (e.g., v0.1.0):

# 1. Update version in package.json and CHANGELOG.md
# 2. Commit changes
git add -A && git commit -m "Release v0.1.0"

# 3. Create and push tag (triggers release.yml)
git tag v0.1.0
git push origin v0.1.0

This creates a GitHub Release with the packaged VSIX file.

Publish Workflow (GitHub Release + Marketplace)

Triggered by v*-publish tags (e.g., v0.1.0-publish):

# After creating a GitHub Release with v0.1.0,
# trigger marketplace publish with:
git tag v0.1.0-publish
git push origin v0.1.0-publish

This creates a GitHub Release and publishes to VS Code Marketplace.

Workflows

release.yml: v* tags → GitHub Release (VSIX attached)
publish.yml: v*-publish tags → GitHub Release + Marketplace publish

🗺️ Roadmap

[x] Add extension icon (128x128 PNG)
[x] Time-based notifications with multiple timers
[x] Auto-reset timers on events
[ ] Add demo GIF to README
[ ] Support more file types
[ ] Custom notification sounds
[ ] Statistics dashboard (track your coding habits)
[ ] Dark/light mode icons
[ ] AI-powered principle suggestions

🤝 Contributing

Contributions are welcome! Here's how you can help:

Report Bugs - Open an issue with detailed information
Suggest Features - Share your ideas for new features or improvements
Submit Pull Requests - Fix bugs or implement new features

Development Setup

# Clone the repository
git clone https://github.com/is0692vs/code-mantra.git
cd code-mantra

# Install dependencies
npm install

# Run in debug mode
# Press F5 in VS Code to launch Extension Development Host

# Run tests
npm test

Guidelines

Follow the existing code style
Add tests for new features
Update documentation as needed
Keep commits atomic and well-described

📄 License

MIT License - see LICENSE for details

💡 Inspiration

Inspired by "The Pragmatic Programmer" by David Thomas and Andrew Hunt.

🙏 Acknowledgments

Thanks to all contributors who help make Code Mantra better
Special thanks to the VS Code extension community for best practices and guidance

Enjoying Code Mantra? Consider leaving a review or starring the repo! ⭐

Code Mantra

HirokiMukai

Code Mantra

✨ Features

🔔 Multiple Trigger Types

⏰ Time-Based Notifications

🎯 Smart Targeting

🧭 Trigger Management Panel

📚 Built-in Wisdom

🚀 Quick Start

First-Time Setup

🙌 Join the Community

Usage

Default Behavior

Manage Triggers Visually

Run a Test Notification

🔔 Notification Priority and Suppression

Understanding the Suppression Rules

Rule 1: File Creation Suppression (onCreate → onSave)

Rule 2: Edit Suppression (onSave → onEdit)

Rule 3: Save Operation Protection

Trigger Types and When They Fire

Default Thresholds

Customizing Suppression Behavior

Configuration

Using VS Code Settings UI (Recommended)

Using settings.json (Advanced)

Enable/Disable

Triggers

File Types

Exclude Patterns

Custom Rules

Time-Based Notifications

Installation

🛠 Troubleshooting

Development

Publishing

Release Workflow (GitHub Release Only)

Publish Workflow (GitHub Release + Marketplace)

Workflows

🗺️ Roadmap

🤝 Contributing

Development Setup

Guidelines

📄 License

💡 Inspiration

🙏 Acknowledgments