Output Example

=== Today's Agenda ===

  TODO     Today    Review paper draft
           docs/paper.org:42
  NEXT     Today    Submit grant proposal
           projects/grant.org:15

Custom Agenda Commands

The CLI runs the custom agenda commands defined in scimax.agenda.customCommands in your VS Code settings.json (see Custom Agenda Commands).

# List your custom commands and their keys
scimax agenda custom

# Print the view for key "d"
scimax agenda custom d

# Structured output
scimax agenda custom d --json

# Write every command's "export" files (.txt, .org, .html, .ics, .json)
scimax agenda store

scimax agenda store from cron keeps HTML or iCalendar copies of your views current, like org-store-agenda-views in Emacs.

Heading Search

Search heading titles, tags, and TODO states:

# Headings whose title matches
scimax search headings "proposal"

# Headings tagged :proposal:
scimax search headings -t proposal

# All TODO headings
scimax search headings --todo TODO

# Combine filters (default limit 50)
scimax search headings -t grant --todo NEXT --limit 20 --json

At least one of a query, -t / --tag, or --todo is required.

Output Example

Searching for: "machine learning"

Found 5 result(s):

Neural Network Architecture (score: 12.34)
  projects/ml-notes.org:156
  "...using machine learning techniques to..."

Deep Learning Overview (score: 10.21)
  docs/tutorials/deep-learning.org:23
  "...introduction to machine learning and..."

Extract Citations

List all citation keys used in a document:

scimax cite extract paper.org

# JSON output
scimax cite extract paper.org --format json

Output:

Found 12 citation(s) with 8 unique key(s):

  doe-2020
  jones-2021
  smith-2019
  ...

Check Citations

Validate citations against a bibliography file:

scimax cite check paper.org --bib references.bib

Output:

Citation Check: paper.org

  Citations found: 12
  Bibliography entries: 15

MISSING (2 cited but not in .bib):
  - nonexistent-2020
  - typo-key

UNUSED (5 in .bib but not cited):
  - old-reference-2010
  - unused-entry
  ...

This is useful in CI pipelines to catch citation errors before publishing.

Convert Citation Syntax

Convert between org-ref v2, v3, and org-cite syntax:

# Convert v2 to v3
scimax cite convert paper.org --from v2 --to v3

# Convert to org-cite
scimax cite convert paper.org --from v3 --to org-cite

# Modify file in place
scimax cite convert paper.org --from v2 --to v3 --inplace

# Output to new file
scimax cite convert paper.org --from v2 --to v3 --output paper-v3.org

List Bibliography

List entries in a BibTeX file:

scimax cite list references.bib

# JSON output
scimax cite list references.bib --format json

Task Model

A task is a heading carrying an :ID: property. The relevant properties are:

Both blocking sources are honored, so --ready and --blocked match what the editor enforces. scimax task done refuses a blocked task unless --force is passed, and reports which tasks the completion unblocked.

File Selection

File selection is global by default. The database spans every indexed file, so scimax task next gives the same answer from any directory: it picks the file with the most task metadata anywhere.

Run scimax task files to see the candidates with their task counts.

Options

Limitations

• done does not write a CLOSED: timestamp, and does not regenerate project-table dynamic blocks; refresh those in the editor.

• :ORDERED: sequences direct children only, not deeper descendants.

• Task ids resolve within one file, so cross-file :DEPENDS: is not followed.

• Effort totals count only Nd and Nh; anything else is reported as unestimated.

Statistics

Show database statistics:

scimax db stats

Output:

=== Database Statistics ===

  Database: /home/user/.config/Code/User/globalStorage/jkitchin.scimax-vscode/scimax-db.sqlite
  Root: /home/user/project

  Files indexed: 42
  Headings: 1234
  Source blocks: 317
  Has embeddings: No
  Org files: 40
  Markdown files: 2

Add --json for structured output.

Optimize

Remove entries for missing files and VACUUM:

scimax db optimize

Close VS Code first: VACUUM needs the database to itself. It rewrites the file, so it needs free disk space about the size of the database. The output reports the size before and after:

Database optimized: 47.0 GB -> 1.9 GB

The same as Scimax: Optimize Database in VS Code. See Database Search.

Check Integrity

Check for missing or stale files:

scimax db check

Output:

Checking database integrity...

MISSING: old-file.org
MISSING: deleted-folder/notes.org

Total files in database: 42
Missing files: 2

Open VS Code to rebuild the index.

When nothing is missing, the last line is Database looks good. Running scimax db sync also removes the missing entries.

Sync

Bring the database into agreement with the configured scan roots and the filesystem in one pass: pick up new files, refresh changed files (mtime-based), refresh in-scope files that are stale, and prune entries for files that no longer exist.

Scan roots are unioned from:

1. scimax.db.include (VS Code settings)

2. scimax.journal.directory

3. scimax.agenda.include

4. NotebookManager projects (every project you have opened in VS Code, persisted in notebooks.json)

Files in the database that do not fall under any current root are still refreshed if they exist and their mtime has advanced; otherwise they are left alone.

# Default daily driver
scimax db sync

# Preview what sync would do without changing the DB
scimax db sync --dry-run

# Show a line per file (in addition to the summary)
scimax db sync --verbose

# Index without generating embeddings
scimax db sync --no-embeddings

Output:

Database: ~/Library/Application Support/Code/User/globalStorage/jkitchin.scimax-vscode/scimax-db.sqlite

Scan roots (3):
  ~/Dropbox/org
  ~/Dropbox/journal
  ~/Dropbox/projects/scimax_vscode

sync complete in 1.4s
  +12 new
  ~5 updated
  -2 removed
  1834 unchanged

The summary uses these markers:

Testing embedding service connection... OK
  Provider: ollama, Model: nomic-embed-text

sync complete in 3.2s
  +12 new
  ~5 updated
  -0 removed
  1834 unchanged
Generating embeddings (14 file(s) remaining)...
  Embeddings complete

✅ Clear

Wipe the database. Use this before a full re-sync, after a schema change, or when troubleshooting suspected corruption. Requires confirmation.

# Interactive confirmation
scimax db clear

# Skip the prompt
scimax db clear --yes

# Typical reset workflow
scimax db clear --yes && scimax db sync

Output:

Database: ~/Library/Application Support/Code/User/globalStorage/jkitchin.scimax-vscode/scimax-db.sqlite
This will delete 1853 file(s), 12044 heading(s), 3201 source block(s).
Continue? [y/N] y
Database cleared.
Run "scimax db sync" to repopulate.

✅ Remove and Ignore Files

Remove files from the database by path or glob. Relative paths are resolved against the current directory.

# Remove one file
scimax db remove notes/scratch.org

# Remove everything matching a glob
scimax db remove "~/Dropbox/archive/**"

# Remove from the database AND add to scimax.db.exclude in settings.json
scimax db ignore "~/Dropbox/archive/**"

remove only deletes database entries, so a later sync adds the files back if they are under a scan root. ignore also appends the pattern (or the absolute path) to scimax.db.exclude in your VS Code settings.json, so sync skips it from then on. Both accept --json.

Prune Excluded Files

Remove database entries that the current exclude rules would reject.

scimax db sync deliberately keeps an entry whose file still exists on disk, even when that file is outside the configured scan roots — otherwise files added by other means would vanish on every sync. The consequence is that tightening scimax.db.exclude, or upgrading to a version that adds a new built-in exclusion, leaves the old rows in place. prune is what clears them.

# See what would go, grouped by the pattern that caught it
scimax db prune --dry-run

# Remove them
scimax db prune

# Machine-readable
scimax db prune --json

Output:

Database: ~/Library/Application Support/Code/User/globalStorage/jkitchin.scimax-vscode/scimax-db.sqlite
Exclude patterns: 22
Indexed files: 58713
Matching exclude rules: 26570
Mode: dry-run (no changes will be written)

    23872  **/node_modules/**
     2574  **/Code/User/History/**
      120  **/build/**
        4  **/Code/User/globalStorage/**

Would remove 26570 file(s). Re-run without --dry-run to apply.

Always run --dry-run first and read the per-pattern breakdown. A pattern that catches far more than you expected is usually a pattern that is too broad.

✅ Scan Directory

Scan a specific directory and add its files to the database. This is a simplified command that takes the directory as a direct argument, making it ideal for cron jobs and scripts.

# Scan a specific directory
scimax db scan /path/to/org-files

# Scan multiple directories (run sequentially)
scimax db scan ~/work/org-files
scimax db scan ~/personal/notes

Output:

Scanning directory: /path/to/org-files
Database path: /home/user/.config/Code/User/globalStorage/jkitchin.scimax-vscode/scimax-db.sqlite

Found 15 org file(s) to index.

  Indexing: meeting-notes.org... OK
  Indexing: project/tasks.org... OK
  Indexing: archive/2024.org... OK
  ...

Indexed: 15 file(s)

#!/bin/bash
set -uo pipefail

# launchd starts jobs with a bare environment, so spell out the PATH.
export PATH="/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin"

LOG_DIR="$HOME/Library/Logs/scimax"
LOG="$LOG_DIR/db-sync.log"
LOCK="$LOG_DIR/db-sync.lock"
MAX_LOG_BYTES=$((5 * 1024 * 1024))

mkdir -p "$LOG_DIR"

if [ -f "$LOG" ] && [ "$(stat -f%z "$LOG")" -gt "$MAX_LOG_BYTES" ]; then
    mv -f "$LOG" "$LOG.1"
fi

# mkdir is atomic: a run that overlaps the previous one backs off rather than
# competing for the database write lock.
if ! mkdir "$LOCK" 2>/dev/null; then
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] skipped: a sync is already running" >> "$LOG"
    exit 0
fi
trap 'rmdir "$LOCK" 2>/dev/null' EXIT

{
    echo "=== $(date '+%Y-%m-%d %H:%M:%S %Z') — scimax db sync ==="
    START=$(date +%s)
    scimax db sync
    STATUS=$?
    echo "--- exit $STATUS after $(( $(date +%s) - START ))s"
    echo
} >> "$LOG" 2>&1

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.USER.scimax-db-sync</string>

  <key>ProgramArguments</key>
  <array>
    <string>/bin/bash</string>
    <string>/Users/USER/.local/bin/scimax-db-sync.sh</string>
  </array>

  <key>StartCalendarInterval</key>
  <array>
    <dict><key>Hour</key><integer>6</integer><key>Minute</key><integer>0</integer></dict>
    <dict><key>Hour</key><integer>17</integer><key>Minute</key><integer>0</integer></dict>
  </array>

  <key>StandardOutPath</key>
  <string>/Users/USER/Library/Logs/scimax/launchd.out</string>
  <key>StandardErrorPath</key>
  <string>/Users/USER/Library/Logs/scimax/launchd.err</string>

  <key>RunAtLoad</key>
  <false/>

  <key>ProcessType</key>
  <string>Background</string>
</dict>
</plist>

plutil -lint ~/Library/LaunchAgents/com.USER.scimax-db-sync.plist
launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.USER.scimax-db-sync.plist

launchctl kickstart -p gui/$UID/com.USER.scimax-db-sync   # run it now
launchctl print gui/$UID/com.USER.scimax-db-sync | grep -E 'state|runs|last exit'
tail -f ~/Library/Logs/scimax/db-sync.log

launchctl bootout gui/$UID/com.USER.scimax-db-sync
launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.USER.scimax-db-sync.plist

crontab -e

# 6am and 5pm daily
0 6,17 * * * /usr/local/bin/scimax db sync >> ~/.local/state/scimax/db-sync.log 2>&1

Initializing a Configuration

--init writes a starter configuration to the current directory. It refuses to overwrite an existing _config.yml or .org-publish.json unless --force is given.

# .org-publish.json with defaults
scimax publish --init

# _config.yml instead
scimax publish --init --yaml

# Custom names and directories
scimax publish --init --name docs --base ./docs --output ./_build/html

If the source directory has no _toc.yml, --init prints an example one.

Installing

Any of these gives the same result:

scimax skill install                          # bundled with the extension, no Python needed
uvx knowhow add jkitchin/scimax_vscode -g -y  # from GitHub with knowhow
npx skills add jkitchin/scimax_vscode -g -y   # from GitHub with npx skills

In VS Code, run Scimax: Install AI Agent Skills (cmd:scimax.skills.install) and choose all projects or this workspace.

Each skill is copied to ~/.agents/skills/<name>, which VS Code, Codex, Cursor, OpenCode and Gemini CLI read, and ~/.claude/skills/<name> is a symlink to it for Claude Code. The install is recorded in ~/.agents/.skill-lock.json, so knowhow check, knowhow upgrade and npx skills update can keep it current.

Commands

scimax skill install [name...]    # Install skills (default: all four)
scimax skill update [name...]     # Reinstall the bundled version
scimax skill uninstall [name...]  # Remove skills installed from scimax
scimax skill list                 # Bundled skills and whether they are installed
scimax skill show [name]          # Print a bundled SKILL.md (default: scimax)
scimax skill path                 # Print the installation directory

install and update stop rather than replace a skill folder of the same name that was installed by something else, unless you pass --force. uninstall only removes skills whose lock entry says they came from jkitchin/scimax_vscode.

Learnings

When you correct the agent, it appends the correction to ~/.config/scimax/learnings.md ($XDG_CONFIG_HOME/scimax/learnings.md if set), and all four skills read that file before answering. It lives outside the skill folders, so updates and uninstalls never touch it.

Before 0.14 the skill was a single folder at ~/.claude/skills/scimax with its own learnings.md. The first scimax skill install or update moves those entries to the new file and replaces the old folder.