DOCSEARCHbyAlgolia
Submit Docs

Task Genius Documentation

repository·master·Indexed 20 days ago

https://github.com/taskgenius/taskgenius-plugin

A comprehensive task management plugin for Obsidian (version 9.14.0-beta.5) that provides Kanban, Gantt, Calendar, and List views. It features a dataflow architecture with QueryAPI and WriteAPI, habit tracking, automated onCompletion workflows, and calendar synchronization for Apple CalDAV, Google, and Outlook. The repository also includes esbuild-plugin-inline-worker for Web Worker inlining.

Tokens
24.7K
Snippets
64
Records
116
Agent score
69%

What's inside Task Genius

  1. Overview of Task Genius Core Features

    master

    Task Genius provides several specialized views and editor-based tools for task management within Obsidian:

    • Task Views: Visualize tasks using List, Kanban, Calendar, and Gantt charts.
    • Date & Priority: Supports recurring tasks, multiple date types, and visual priority indicators (View-based).
    • Workflows: Multi-stage workflows with automatic timestamping, templates, and process tracking (Editor-based).
    • Habit Tracking: Daily habits, streak tracking, visual calendar, and progress analytics (View-based).
    • Quick Capture: Global commands, templates, and automated task creation.
    • Filtering & Search: Advanced in-editor filtering, saved queries, and custom perspectives.
    • Gamification: Achievement rewards, custom milestones, and motivational feedback (View-based).

  2. Understand ICS/iCal and MCP integration privacy

    master

    ICS/iCal Calendar Integration

    When importing data via an ICS/iCal URL:

    • Data is fetched directly from the provided URL.
    • Data is cached locally in your vault.
    • No data is transmitted to third-party servers.

    MCP (Model Context Protocol) Integration

    If you enable MCP integration:

    • The MCP server runs locally on your computer.
    • Connections are authenticated using an App ID.
    • You maintain control over which AI clients are permitted to access your task data.

  3. Understand the Task Parsing and Data Flow

    master

    The system follows a structured pipeline to ensure high performance and data integrity:

    1. File Detection: fileTypeUtils.ts identifies if the file is Markdown (.md) or Canvas (.canvas).
    2. Parser Selection: TaskManager.ts routes the file to the appropriate parser (e.g., CanvasParser.ts for Canvas or ConfigurableTaskParser.ts for Markdown).
    3. Execution: Heavy parsing is delegated to a web worker pool managed by TaskWorkerManager.ts to keep the main thread responsive.
    4. Indexing: TaskIndexer.ts updates in-memory indexes (file-based, tag-based, date-based, etc.) for fast querying.
    5. Persistence: persister.ts handles local storage caching and data recovery.

  4. Understand how Task Genius handles your data

    master

    The Task Genius Plugin for Obsidian follows a privacy-first model where your core task data remains entirely within your local Obsidian vault. The plugin does not operate servers to collect or store your personal data.

    Data Storage Locations:

    • Task data: Stored as markdown files within your local vault.
    • Plugin settings: Stored in .obsidian/plugins/obsidian-task-genius/data.json.
    • Cache data: Temporary local cache used for performance optimization.

  5. Understand the Task Parsing and Management Architecture

    master

    The Task Parsing and Management Utilities use a modern, event-driven Dataflow Architecture designed for high performance and scalability. This architecture is organized into four distinct layers:

    1. API Layer: Provides the primary interface for interacting with tasks. It is split into QueryAPI (for read operations like getAllTasks()) and WriteAPI (for write operations like updateTask()).
    2. Orchestration Layer: Manages coordination via the DataflowOrchestrator (event coordination) and the WorkerOrchestrator (background processing).
    3. Events Layer: Handles real-time updates through Events.ts and various event emitters (e.g., CACHE_READY).
    4. Repository Layer: Manages data storage and fast lookups using Repository.ts (supporting synchronous cache) and Indexer.ts (optimized queries).

    Note: The legacy TaskManager-based architecture was removed in version 10.0.0.

    ┌─────────────────────────────────────────────────────────────┐
│                    API Layer                                │
├─────────────────────────────────────────────────────────────┤
│  QueryAPI                │  WriteAPI                        │
│  (Read Operations)       │  (Write Operations)              │
│  • getAllTasks()         │  • updateTask()                  │
│  • getAllTasksSync()     │  • createTask()                   │
│  • getTaskByIdSync()     │  • deleteTask()                   │
├─────────────────────────────────────────────────────────────┤
│                    Orchestration Layer                      │
├─────────────────────────────────────────────────────────────┤
│  DataflowOrchestrator    │  WorkerOrchestrator              │
│  (Event Coordination)    │  (Background Processing)         │
├─────────────────────────────────────────────────────────────┤
│                    Events Layer                             │
├─────────────────────────────────────────────────────────────┤
│  Events.ts               │  Event Emitters                  │
│  (CACHE_READY, etc.)     │  (Task/File Updates)             │
├─────────────────────────────────────────────────────────────┤
│                    Repository Layer                         │
├─────────────────────────────────────────────────────────────┤
│  Repository.ts           │  Indexer.ts                      │
│  (Data Storage)          │  (Fast Lookups)                  │
│  • Sync Cache Support    │  • Optimized Queries             │
└─────────────────────────────────────────────────────────────┘

  6. Understand the Task Genius project architecture

    master

    The project is organized into several functional directories within src/:

    • index.ts: The main plugin entrypoint responsible for registering views and commands.
    • components/: UI elements including views, settings tabs, modals, and widgets.
    • dataflow/: Handles task indexing and the repository layer.
    • editor-extensions/: CodeMirror extensions for filters, status, pickers, and timers.
    • mcp/: Implementation of the Model Context Protocol (MCP) server.
    • pages/: Specific views like TaskView, Bases views, and widgets.
    • managers/: High-level logic managers (e.g., onboarding, changelog).
    • utils/: Shared helper functions for dates, file operations, etc.
    src/
  index.ts            # Plugin entrypoint (registers views/commands)
  components/         # UI (views, settings tabs, modals, widgets)
  dataflow/           # Task indexing + repository
  editor-extensions/  # CodeMirror extensions (filter, status, pickers, timer)
  mcp/                # MCP server (Model Context Protocol)
  pages/              # Views (TaskView, Bases views, widgets)
  managers/           # Higher-level managers (onboarding, changelog, etc.)
  utils/              # Shared helpers (dates, file ops, etc.)

  8. Manage habit properties and reindexing

    master
    In version 9.8.0-beta.12, improvements were made to how habit properties are handled. Additionally, a new reindex command was introduced to allow users to manually trigger a reindexing of task data, which is useful if habit sync or progress visualization needs to be refreshed.

  9. Best practices for Task Genius data formatting

    master

    To ensure Task Genius views function correctly, follow these formatting conventions for your base properties:

    • Status Values: Use a space (" ") for tasks that are not started and 'x' for completed tasks.
    • Project Hierarchy: Use the / character to create nested projects (e.g., Development/Frontend/Components).
    • Date Formats: Use ISO format (YYYY-MM-DD) for all date fields.
    • Priority Scale: Use a numeric scale from 1 to 5, where 5 is the highest priority.
    • Tags Format: Use either a list format or comma-separated values.
    • Context Format: Use the @context format (e.g., @work, @home).

  10. Quick Start with Task Genius

    master

    To begin using Task Genius, you can follow the built-in onboarding process or manually start your workflow:

    Option 1: Onboarding

    1. Enable Plugin: Activate Task Genius in your plugin settings.
    2. Onboarding: Follow the guided setup process provided by the plugin.

    Option 2: Manual Workflow

    1. Open Task View: Click the ribbon icon or use the Command Palette to search for Open Task Genius View.
    2. Create First Task: Use the Quick Capture panel to create your first task.
    3. Explore Views: Switch between different views (List, Kanban, Calendar, Gantt) to find your preferred workflow.

  12. Follow the feature development workflow

    master

    When developing new features, follow this cycle to ensure code quality and proper integration:

    1. Branching: Create a feature branch using git checkout -b feature/your-feature-name.
    2. Development: Use pnpm run dev to run in watch mode for hot reloading.
    3. Verification: Run pnpm test to execute tests and pnpm run lint to check code style.
    4. Committing: Use Conventional Commits format: <type>(<scope>): <subject>.
      • feat: New feature
      • fix: Bug fix
      • docs: Documentation changes
      • style: Code style changes
      • refactor: Code refactoring
      • perf: Performance improvements
      • test: Test additions/changes
      • chore: Build/tooling changes
    5. Submission: Push to your fork and create a Pull Request against the master branch.
    # Make changes
pnpm run dev     # Watch mode

# Run tests
pnpm test

# Lint code
pnpm run lint