✅ 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

⚠️ Agenda Buffer

The agenda buffer is a persistent, refreshable agenda in a full editor tab — the closest analogue to Emacs org-agenda-mode. Unlike the quick pick, it stays open; unlike the tree view, it gets the whole editor.

Open it with C-c a v (cmd:scimax.agenda.openBuffer), or from the agenda menu (C-c a a), then choose a span (day, week, fortnight, or month):

Agenda for Jun 3 - Jun 9, 2024
======================================================================

Monday, June 3, 2024
--------------------
  10:00 TODO Team standup :work:
  Deadline: TODO [#A] Submit report :work:

Tuesday, June 4, 2024
---------------------
  14:00 TODO Planning meeting

Total: 3 items

The buffer is read-only, so it can never be edited by accident and never prompts to save.

✅ 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 is a view over the Scimax database — anything indexed in the database is agenda-eligible. Configure indexing scope via scimax.db.* (see Database & Search):

Add ad-hoc directories (e.g. a Dropbox-shared notes folder) via scimax.db.include:

{
  "scimax.db.include": [
    "/home/user/org/work.org",
    "/home/user/Dropbox/shared-notes"
  ]
}

After changing indexing settings, run Scimax: Refresh Database (incremental) (cmd:scimax.db.refresh) to pick up new files.

The Scimax: Configure Agenda Files command (cmd:scimax.agenda.configure) is a shortcut for both steps: choose Add directory to agenda or Add file to agenda, and the selected paths are appended to scimax.db.include and indexed immediately.

The legacy scimax.agenda.includeJournal/includeWorkspace/includeProjects/include settings are deprecated and have no effect — the agenda no longer scans files itself. On activation, Scimax shows a one-shot toast if any of these are set, with a button that opens the new scimax.db.* settings.

✅ Exclude Patterns

There are two distinct exclude lists. Pick the one that matches your intent:

Use scimax.db.exclude when a file shouldn't be in the index at all (backup files, archives, Emacs caches). Use scimax.agenda.exclude for files that you want searchable but cluttering the day/week view.

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

Both lists support glob patterns (containing *) and absolute paths (supporting ~ for home).

Quick commands:

• Scimax: Hide File from Agenda View (still indexed) (cmd:scimax.agenda.ignoreFile)

• Scimax: Don't Index File (removes from database) (cmd:scimax.db.ignoreFile)

✅ 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 the agenda, index your files:

For day-to-day use across machines (e.g. Dropbox sync), run Refresh on activation when prompted, or any time you want the agenda to pick up new edits.

✅ 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

Issue: Agenda view is empty or shows fewer items than expected.

Solutions:

1. Check indexed files: #+BEGIN_SRC text Command: scimax.agenda.configure Add your org directories; they are stored in scimax.db.include and indexed automatically #+END_SRC

2. Verify TODO keywords:

   • Check headlines have TODO, SCHEDULED, or DEADLINE

   • Ensure correct keyword spelling

3. Check time range:

   • Day view only shows today's items

   • Try week or month view for more items

4. Sync database (for database agenda): #+BEGIN_SRC text Command: scimax.db.reindex #+END_SRC

5. Check exclude patterns:

   • Ensure files aren't excluded

   • Review scimax.agenda.exclude

✅ Items Not Updating

Issue: Changed items don't appear or update in agenda.

Solutions:

1. Refresh agenda: #+BEGIN_SRC text Command: scimax.agenda.refresh #+END_SRC

2. Sync database: #+BEGIN_SRC text Command: scimax.db.reindex #+END_SRC

3. Check file watcher:

   • Extension should auto-detect changes

   • Manual refresh if needed

4. Save file:

   • Ensure file is saved (C-s)

   • Agenda reads from disk

✅ Tree View Not Showing

Issue: Agenda tree view not visible in sidebar.

Solutions:

1. Check view visibility:

   • View → Open View → Scimax: Agenda

2. Refresh view: #+BEGIN_SRC text Command: scimax.agenda.refresh #+END_SRC

3. Check for errors:

   • View extension logs

   • Check for parsing errors in org files

✅ Slow Performance

Issue: Agenda is slow to load or refresh.

Solutions:

1. Use database agenda:

   • scimax.db.agenda is faster for large collections

   • Index files once, query quickly

2. Limit agenda files:

   • Don't include entire filesystem

   • Use specific directories

3. Exclude large directories: #+BEGIN_SRC json { "scimax.agenda.exclude": [ "*node_modules", "vendor", "build*" ] } #+END_SRC

4. Optimize file sizes:

   • Archive old DONE items

   • Split large files into smaller ones

✅ Date Display Issues

Issue: Dates show incorrectly or items appear on wrong days.

Solutions:

1. Check timestamp format: #+BEGIN_SRC org ; Correct SCHEDULED: <2026-01-15 Wed> ; Incorrect SCHEDULED: <01/15/2026> #+END_SRC

2. Verify day of week:

   • Day must match date

   • Use S- to recalculate

3. Check repeaters: #+BEGIN_SRC org ; Ensure repeater syntax is correct SCHEDULED: <2026-01-15 Wed +1w> #+END_SRC

✅ Main Agenda Commands

✅ Database Agenda Commands

✅ Tree View Commands

✅ Configuration Settings

Indexing scope (what's available to the agenda) lives under scimax.db.*. The agenda's own settings are display-only:

Indexing settings (see Database & Search):

✅ 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