Auto Status Plugin for Obsidian

Automatically manages task-related frontmatter properties (a pending-tasks boolean and optional pending/total counts) based on checkbox state in your notes.

Features

• 🔍 Automatic Detection: Monitors all your notes for task checkboxes
• ⚡ Real-time Updates: Updates frontmatter automatically when you check/uncheck tasks
• 🔢 Task Counts: Optionally writes numeric Pending tasks count and Total tasks count properties
• 🌳 Root-only Mode: Optionally count only top-level tasks, ignoring subtasks nested under other tasks
• 🎛️ Configurable: Customize property names, folders, and behavior
• 📁 Folder Control: Include/exclude specific folders from processing
• 🔧 Manual Processing: Process individual notes or all notes at once
• 🚫 Smart Cleanup: Removes managed properties when all tasks are completed or no tasks exist

How It Works

The plugin automatically scans your notes for task checkboxes and manages a boolean frontmatter property:

• Pending tasks exist (- [ ]): Sets the property to true
• All tasks completed (- [x]) or no tasks: Removes the property entirely

Supported Task Formats

The plugin recognizes these checkbox formats:

• - [ ] and - [x] (standard Obsidian tasks)
• * [ ] and * [x] (asterisk bullets)
• + [ ] and + [x] (plus bullets)
• Both lowercase and uppercase X: [x] and [X]

Installation

Manual Installation

1. Download the latest release files (main.js, manifest.json)
2. Create a folder called auto-status in your vault's .obsidian/plugins/ directory
3. Place the downloaded files in this folder
4. Reload Obsidian and enable the plugin in Community Plugins settings

Development Installation

1. Clone this repository into your vault's .obsidian/plugins/ directory
2. Run bun install to install dependencies
3. Run bun run build to build the plugin
4. Reload Obsidian and enable the plugin

Development Setup

Prerequisites

• Bun (v1.0 or later)

Development Commands

# Install dependencies
bun install

# Start development with hot reload (watch mode)
bun run dev

# Build for production
bun run build

# Run tests
bun run test

# Run linter (format check + eslint + tsc)
bun run lint

# Auto-fix lint and formatting issues
bun run lint:fix

# Install plugin to vault (build + copy)
OBSIDIAN_VAULT=/path/to/vault bun run vault:install

# Symlink dist/ into vault for live development
OBSIDIAN_VAULT=/path/to/vault bun run vault:install-symlink

Project Structure

obsidian-auto-status/
├── .editorconfig          # Editor consistency settings
├── .github/workflows/     # CI and release workflows
├── .gitignore             # Git ignore patterns
├── .husky/                # Git hooks (pre-commit lint)
├── .prettierrc            # Prettier configuration
├── esbuild.config.mjs     # Build configuration
├── eslint.config.mjs      # ESLint flat config
├── jest.config.js         # Test configuration
├── manifest.json          # Plugin manifest
├── package.json           # Dependencies and scripts
├── scripts/               # Vault management scripts
├── src/main.ts            # Main plugin source
├── styles.css             # Plugin styles
├── test/                  # Test files
│   ├── mock_obsidian.ts   # Obsidian API mock
│   ├── setup.ts           # Test setup
│   └── *.test.ts          # Test files
└── tsconfig.json          # TypeScript configuration

Development Workflow

1. Setup: Clone the repo and run bun install
2. Development: Use bun run dev for hot reloading (watch mode)
3. Testing: Run bun run test to ensure quality
4. Linting: Run bun run lint to check code style
5. Building: Run bun run build for a production build
6. Deployment: Use bun run vault:install-symlink for live development in your vault

Code Quality

The project includes comprehensive tooling for code quality:

• TypeScript: Full type safety and modern JavaScript features
• ESLint: v9 flat config with typescript-eslint v8
• Prettier: Consistent code formatting
• Husky: Pre-commit hook enforces bun run lint
• Jest: Unit testing with jsdom environment and coverage reporting

Testing

The plugin includes a comprehensive test suite covering:

• Task detection logic with various formats
• File processing and frontmatter management
• Settings management and validation
• Error handling and edge cases

Run tests with:

bun run test                    # Run once
bun run test --watch            # Watch mode
bun run test --coverage         # With coverage report

Usage

Automatic Mode (Default)

The plugin works automatically once enabled. Just create tasks in your notes:

---
title: My Daily Note
---

## Tasks for Today

- [ ] Review project proposal
- [x] Complete morning routine
- [ ] Call the client

## Completed Tasks

- [x] Buy groceries
- [x] Send email to team

The plugin will automatically add Pending tasks: true to the frontmatter because there are unchecked tasks.

Manual Processing

Use the command palette (Ctrl/Cmd + P) to access manual commands:

• Process current note for task status: Process the currently active note
• Process all notes for task status: Process all notes in your vault

Example Frontmatter Updates

Before (note with pending tasks):

---
title: Project Planning
---

After (automatically updated):

---
title: Project Planning
Pending tasks: true
---

When all tasks completed (property removed):

---
title: Project Planning
---

Configuration

Access plugin settings through Settings → Community Plugins → Auto Status.

Available Settings

• Property Name: The frontmatter property name for the pending-tasks boolean (default: "Pending tasks")
• Enable Auto Processing: Automatically process files when modified
• Debounce Delay: Delay in milliseconds before processing file changes (default: 500ms)
• Include Folders: Only process files in specified folders (leave empty for all)
• Exclude Folders: Never process files in specified folders
• Enable task count properties: Write numeric frontmatter properties for pending/total task counts (default: off)
• Pending tasks count property name: Name of the frontmatter field for the pending count (default: "Pending tasks count")
• Total tasks count property name: Name of the frontmatter field for the total count (default: "Total tasks count")
• Count root tasks only: When enabled, subtasks nested under another task are excluded from both the boolean and the counts (default: off)

Task Counts

When Enable task count properties is on, each processed note gets two numeric frontmatter fields:

---
Pending tasks: true
Pending tasks count: 3
Total tasks count: 6
---

These update on every edit (debounced), and are removed when the note has no tasks or when the feature is turned off.

Root Task Semantics

When Count root tasks only is on, a task is considered a "root task" if its immediate list parent is not itself a task. This correctly handles outlines that group tasks under non-task bullets:

- **Action items**:        ← non-task bullet
  - [ ] Ship release       ← ROOT (parent is non-task)
  - [ ] Write changelog    ← ROOT (parent is non-task)
- [ ] Standalone task      ← ROOT (no parent)
  - [ ] Subtask            ← NOT root (parent is a task)

This structural detection walks the list tree, so Ship release counts as a top-level task even though it's indented under **Action items**:.

Folder Management Examples

Include specific folders only:

Daily Notes, Projects, Work

Exclude template and archive folders:

Templates, Archive, .trash

Integration Examples

Dataview Integration

Use with Dataview plugin to create powerful task overviews:

TABLE file.link as "Note", "Pending tasks" as "Has Pending Tasks"
FROM ""
WHERE "Pending tasks" = true
SORT file.mtime DESC

Templater Integration

Create templates that leverage the auto-status:

---
title: <% tp.file.title %>
date: <% tp.date.now() %>
<% if (tp.frontmatter["Pending tasks"]) { %>status: in-progress<% } else { %>status: completed<% } %>
---

Troubleshooting

Plugin Not Working

1. Check that the plugin is enabled in Community Plugins
2. Verify auto processing is enabled in settings
3. Ensure files are in included folders (if specified)
4. Check that files are markdown (.md) format

Frontmatter Not Updating

1. Try manually processing with the command palette
2. Check console for error messages (Ctrl/Cmd + Shift + I)
3. Verify task format matches supported patterns
4. Ensure file is not in excluded folders

Performance Issues

1. Increase debounce delay in settings
2. Use folder include/exclude to limit processing
3. Disable auto processing and use manual commands

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Follow the existing code style and patterns
4. Add tests for new functionality
5. Ensure all tests pass (bun run test)
6. Run the linter (bun run lint)
7. Submit a pull request

Architecture

Core Components

• AutoStatusPlugin: Main plugin class handling lifecycle and events
• Task Detection: Regex-based parsing of various checkbox formats
• Frontmatter Management: Safe atomic updates using Obsidian's API
• Settings Management: Configurable behavior with UI
• Event Handling: Debounced file monitoring for performance

Key Design Decisions

• Atomic Updates: Uses app.fileManager.processFrontMatter() for safe frontmatter modification
• Performance: Debounced processing to avoid excessive updates
• Flexibility: Configurable property names and folder inclusion/exclusion
• Standards Compliance: Follows official Obsidian plugin development practices

License

MIT License - see LICENSE file for details.

Changelog

Version 0.1.0

• Initial release
• Automatic task detection and frontmatter management
• Configurable settings and folder control
• Manual processing commands
• Optional pending/total task count properties
• Structural root-task detection (count tasks under non-task bullets as roots)
• Comprehensive test suite
• Development tooling matching official Obsidian standards