✅ Key Concepts

* TODO Write report
SCHEDULED: <2026-01-15 Wed>

✅ Native/File-Based Agenda

• Scans org files on-demand

• Works immediately without indexing

• Provides tree view in sidebar

• Commands: scimax.agenda.*

• Best for: Quick views, smaller document sets

✅ Database-Backed Agenda

• Uses indexed data for fast queries

• Requires indexing files first

• Integrates with search and filtering

• Commands: scimax.db.agenda, scimax.db.deadlines

• Best for: Large document collections, complex queries

Both systems can be used together - choose based on your needs.

✅ Day Agenda

Shows items for a single day.

The day view displays:

• Scheduled items for the day

• Deadlines due today

• Overdue items

• Time-of-day for timed entries

Today (Wednesday, Jan 15, 2026)
──────────────────────────────

  09:00  TODO [#A] Team standup                    :work:
  14:00  TODO Client presentation                  :important:
         TODO DEADLINE: Submit timesheet            (TODAY)
         TODO Review pull requests                 :code:

✅ Week Agenda

Shows a 7-day view starting from today.

Groups items by date, making it easy to plan your week:

Week Agenda (Jan 15-21, 2026)
─────────────────────────────

Wednesday, Jan 15
  09:00  TODO Team standup
  14:00  TODO Client meeting

Thursday, Jan 16
  TODO Code review
  DEADLINE: Deploy feature    (in 1 day)

Friday, Jan 17
  TODO Weekly review

✅ Fortnight Agenda

Shows the next 14 days.

Useful for medium-term planning and catching upcoming deadlines.

✅ Month Agenda

Shows the next 30 days.

Good for long-term planning and ensuring nothing falls through the cracks.

✅ Custom Time Ranges

The database-backed agenda supports custom time ranges:

; Next 2 weeks
Command: scimax.db.agenda → "Next 2 weeks"

; Next month
Command: scimax.db.agenda → "Next month"

; Next 3 months
Command: scimax.db.agenda → "Next 3 months"

; All items (no time limit)
Command: scimax.db.agenda → "All items"

✅ Grouping by State

TODOs are grouped by their keyword state:

TODO List (45 items)
───────────────────

TODO (32 items)
  [#A] Fix critical bug                           :urgent:
  Write documentation                             :docs:
  Review code changes                             :review:

NEXT (8 items)
  [#A] Implement login feature                    :feature:
  Deploy to staging                               :deploy:

WAITING (5 items)
  Approval from manager                           :blocked:
  Design feedback                                 :design:

✅ Filtering TODO List

Filter by state when viewing TODOs:

Command: scimax.db.showTodos
→ Select filter: "All TODOs", "TODO", "NEXT", "WAITING", etc.

Shows only items in the selected state.

✅ Upcoming Deadlines

Displays deadlines with time-until indicators:

Upcoming Deadlines (8 items)
────────────────────────────

  ⚠  TODO Submit proposal                         (2 days overdue)
  🔔 TODO Complete Q1 report                      (TODAY)
  🔔 TODO Review contract                         (in 1 day)
  🔔 TODO File taxes                              (in 14 days)

✅ Deadline Display

Deadlines show:

• Overdue indicator (⚠) if past due

• Days until/overdue count

• Priority and tags

• File location

✅ Warning Periods

Deadlines with warning periods appear in the agenda before they're due:

* TODO Annual review
DEADLINE: <2026-01-31 Fri -7d>

This appears 7 days early (January 24) with "in 7 days" indicator.

✅ Repeating Items

Recurring tasks with repeater syntax appear in the agenda:

* TODO Daily standup
SCHEDULED: <2026-01-15 Wed 09:00 +1d>

* TODO Weekly review
SCHEDULED: <2026-01-19 Sun +1w>

* TODO Monthly report
DEADLINE: <2026-01-31 Fri +1m>

See Timestamps for more on repeaters.

✅ Group By Options

Today
  Item 1
  Item 2

Tomorrow
  Item 3
  Item 4

Work
  Project A tasks
  Project B tasks

Personal
  Home tasks
  Errands

Priority A
  [#A] Critical bug
  [#A] Important meeting

Priority B
  [#B] Code review
  [#B] Documentation

No Priority
  Regular tasks

TODO
  Task 1
  Task 2

NEXT
  Task 3

WAITING
  Task 4

✅ Changing Grouping

Tree view groups update immediately.

✅ Sort Options

Items within groups are sorted by:

1. Time - Default, chronological order

2. Priority - High to low (A → B → C)

3. Category - Alphabetical by category

4. TODO state - By keyword

5. Tag - By first tag alphabetically

✅ Filter by Tag

Show only items with a specific tag.

Workflow:

1. Run command

2. Select a tag from the list

3. See only items with that tag

Command: scimax.agenda.filterByTag
→ Select tag: "urgent"

Items with :urgent: (7 items)
────────────────────────────

  TODO [#A] Fix production bug                    :urgent:work:
  TODO Submit incident report                     :urgent:admin:

✅ Filter by Priority

Database filtering supports priority:

Query: priority:A
Shows: Only [#A] priority items

✅ Filter by TODO State

Show only specific TODO states:

Command: [[cmd:scimax.db.showTodos]]
→ Select: "NEXT"
Shows: Only NEXT items

✅ Filter by Date Range

Combine time ranges with other filters:

Command: [[cmd:scimax.db.agenda]]
→ Select: "Next 2 weeks"
Shows: Items in next 14 days only

✅ Combining Filters

Database queries support multiple filters:

Show TODOs:
  - With tag :work:
  - Priority A or B
  - Due in next week

Use the database search commands for complex filtering.

✅ Tree View Interface

The Agenda tree view appears in the VS Code sidebar:

AGENDA
└─ Today (3 items)
   ├─ ⚪ TODO Team standup
   ├─ 🔔 TODO [#A] Submit report
   └─ 📅 TODO Review code
└─ Tomorrow (2 items)
   ├─ ⚪ TODO Planning meeting
   └─ ⚪ TODO Update documentation

✅ Opening Items

Click any item in the tree view or quick pick to:

• Open the file containing the item

• Jump to the exact line

• Highlight the headline

The item is centered in the editor for easy viewing.

✅ Quick Pick Navigation

Commands show items in a searchable quick pick:

Agenda: 12 items                           [Type to search]
─────────────────────────────────────────────────────────

  📅 TODO Team standup      TODO [#A] 09:00    work.org:42
  🔔 TODO Submit report     DEADLINE (TODAY)   project.org:156
  ⚪ TODO Review code       TODO :review:       dev.org:78
  ⚪ TODO Update docs       TODO               readme.org:12

Features:

• Type to filter items

• Shows description, tags, priority

• File location in detail

• Icons indicate item type

✅ Item Icons

✅ Keyboard Navigation

In tree view:

• Arrow keys: Navigate items

• Enter: Open item

• Space: Expand/collapse group

In quick pick:

• Type: Filter items

• Arrow keys: Navigate

• Enter: Open item

• Escape: Cancel

✅ Agenda Sources

The agenda automatically includes files from these sources:

By default, the agenda includes:

1. Your journal directory (from scimax.journal.directory)

2. All org files in your workspace folders

3. All scimax projects (registered via projectile)

To add additional files or directories:

Command: scimax.agenda.configure
→ Select: "Add directory to agenda"
→ Select directory to add

Or manually in settings:

{
  "scimax.agenda.include": [
    "/home/user/org/work.org",
    "/home/user/org/personal.org",
    "/home/user/projects"
  ]
}

To disable journal or projects in agenda:

{
  "scimax.agenda.includeJournal": false,
  "scimax.agenda.includeProjects": false
}

✅ Exclude Patterns

Exclude files from agenda using glob patterns or absolute paths:

The exclude list supports:

• Glob patterns (containing *): **/archive/**

• Absolute paths: ~/org/scratch.org

{
  "scimax.agenda.exclude": [
    "**/node_modules/**",
    "**/.git/**",
    "**/archive/**",
    "**/drafts/**",
    "~/org/scratch.org"
  ]
}

Use Scimax: Exclude File from Agenda command to quickly exclude the current file.

✅ Default Time Span

Set the default number of days for agenda views:

{
  "scimax.agenda.defaultSpan": 14
}

✅ Show Done Items

Include or exclude completed items:

{
  "scimax.agenda.showDone": true
}

✅ Show Habits

Control display of recurring habit tasks:

✅ States

Define which TODO keywords to include:

{
  "scimax.agenda.todoStates": [
    "TODO",
    "NEXT",
    "IN-PROGRESS",
    "WAITING",
    "REVIEW"
  ],
  "scimax.agenda.doneStates": [
    "DONE",
    "CANCELLED",
    "REJECTED"
  ]
}

✅ Database Agenda Features

The database agenda (scimax.db.agenda) offers:

1. Fast queries - Indexed data for instant results

2. Complex filtering - Search by property, tag, etc.

3. Semantic search - Find items by meaning

4. Hybrid views - Combine agenda with search

✅ Indexing for Agenda

Before using database agenda, index your files:

The database automatically tracks changes, but manual reindex ensures everything is current.

✅ Database Agenda Commands

✅ Search Scope

Limit agenda queries to specific directories:

Options:

• All files - Search entire database

• Current directory - Only files in current directory

✅ Agenda Item Data

Database agenda items include:

interface AgendaItem {
  type: 'deadline' | 'scheduled' | 'todo';
  heading: HeadingRecord;
  date?: string;
  days_until?: number;
  overdue?: boolean;
}

Properties:

• type - Item category

• heading - Full heading info (title, tags, priority, etc.)

• date - Scheduled/deadline date

• days_until - Days until/past date (negative = overdue)

• overdue - Boolean flag for past deadlines

✅ Querying Agenda

Programmatic access to agenda data:

// Get agenda items
const items = await db.getAgenda({
  before: '+2w',           // Next 2 weeks
  includeUnscheduled: true // Include TODOs without dates
});

// Filter deadlines
const deadlines = items.filter(item => item.type === 'deadline');

// Find overdue
const overdue = items.filter(item => item.overdue);

See Database Search for more on database queries.

✅ Morning Planning

Start your day with the day agenda:

1. Run [[cmd:scimax.agenda.day]]

2. Review today's items

3. Mark priorities

4. Identify blockers

5. Clock in to first task

✅ Weekly Review

Every week:

1. Run [[cmd:scimax.agenda.week]]

2. Check for overdue items

3. Reschedule as needed

4. Add new scheduled items

5. Review WAITING tasks

✅ Deadline Management

Stay on top of deadlines:

1. Run [[cmd:scimax.agenda.deadlines]] or [[cmd:scimax.db.deadlines]]

2. Note items due soon

3. Start working on items with warnings

4. Address overdue items immediately

5. Update estimates for late items

✅ Context-Based Work

Use tags to filter by context:

; At office
Command: scimax.agenda.filterByTag
→ Select: "office"
Work on office-only tasks

; Have phone available
→ Select: "phone"
Make all phone calls

; At computer
→ Select: "computer"
Handle computer-required tasks

✅ Project Review

Review project status:

1. Filter agenda by project tag

2. Check all project items

3. Identify NEXT action

4. Update completed items

5. Add new tasks as needed

✅ Priority Triage

Focus on high-priority items:

1. Filter or group by priority

2. Work through all [#A] items

3. Move to [#B] items

4. Reschedule [#C] if needed

✅ Keep Agenda Files Organized

Structure agenda files logically:

~/org/
  ├── work.org          ; Work tasks
  ├── personal.org      ; Personal tasks
  ├── projects/         ; Project-specific files
  │   ├── project-a.org
  │   └── project-b.org
  └── archive/          ; Archived (excluded)

Configure agenda to scan ~org and exclude archive/.

✅ Use Meaningful Categories

Set CATEGORY properties for better grouping:

#+CATEGORY: Work

* TODO Project tasks
:PROPERTIES:
:CATEGORY: ProjectA
:END:

✅ Example: Software Developer

; work.org

* TODO [#A] Fix production bug                              :urgent:bug:
DEADLINE: <2026-01-15 Wed>
Critical database connection issue.

* TODO [#A] Code review for PR #234                         :review:
SCHEDULED: <2026-01-15 Wed 10:00>
Review authentication changes.

* TODO [#B] Implement user settings page                    :feature:
SCHEDULED: <2026-01-16 Thu>
DEADLINE: <2026-01-20 Mon>
:PROPERTIES:
:EFFORT: 6:00
:END:

* TODO Weekly team standup                                  :meeting:
SCHEDULED: <2026-01-15 Wed 09:00 +1w>

* TODO Sprint planning                                      :meeting:
SCHEDULED: <2026-01-22 Wed 14:00 +2w>

Agenda shows:

• Today: Bug fix (overdue!), code review at 10am, standup at 9am

• Tomorrow: Start user settings

• Next Monday: Settings deadline

✅ Agenda Shows No Items

1. Check agenda files configuration:

2. Verify TODO keywords:

3. Check time range:

4. Reindex database (for database agenda):

5. Check exclude patterns:

✅ Items Not Updating

1. Refresh agenda:

2. Reindex database:

3. Check file watcher:

4. Save file:

✅ Tree View Not Showing

1. Check view visibility:

2. Refresh view:

3. Check for errors:

✅ Slow Performance

1. Use database agenda:

2. Limit agenda files:

3. Exclude large directories:

4. Optimize file sizes:

✅ Date Display Issues

1. Check timestamp format:

2. Verify day of week:

3. Check repeaters:

✅ Main Agenda Commands

✅ Database Agenda Commands

✅ Tree View Commands

✅ Configuration Settings

✅ Agenda Item Properties

✅ Item Type Icons

✅ Quick Workflow

1. Morning: [[cmd:scimax.agenda.day]] - See today's tasks

2. Planning: [[cmd:scimax.agenda.week]] - Plan upcoming work

3. Triage: [[cmd:scimax.agenda.deadlines]] - Handle urgent items

4. Context work: [[cmd:scimax.agenda.filterByTag]] - Focus by context

5. Review: [[cmd:scimax.agenda.todoList]] - Review all TODOs