Commands — Command Handler

The commands package implements the CommandHandler class and its mixins, which process user input in both quick-add and command modes.

CommandHandler

class jot.commands.handler.CommandHandler(task_manager, registry=None)

Bases: CoreMixin, MetadataMixin, TransferMixin, BulkMixin, GcalMixin, GithubMixin, AiAnalysisMixin, AiSuggestMixin, NotesMixin, WebClipboardMixin, AudioTimerMixin, ContextMixin, ClaudeMixin

Extensible command system — composed from domain-specific mixins.

handle(command)

Handle a command

Mixins

Core Commands

Core task CRUD and utility mixin.

class jot.commands._core_mixin.CoreMixin

Bases: object

Core task operations: add, delete, edit, set current, help, refresh.

add_task()

Add a new task

quit()

Quit the application

set_current()

Mark a task as current

set_agent_task()

Mark current task as agent task (Claude Code is working on it)

duplicate_task()

Duplicate the current task.

fix_duplicate_ids_interactive()

Check for and fix duplicate task IDs (Shift+1)

delete_task()

Delete a task by ID

delete_current()

Delete the current task

edit_task()

Edit a task’s text

edit_current()

Edit the current task

collect_all_category_tasks(project_dir, show_archived=False)

Collect tasks from all categories (default + local + global).

Returns list of (category_name, is_global, tasks, archived_tasks).

static toggle_all_categories_view(current_mode)

Toggle between normal view and all-categories view.

Returns:

(should_toggle, new_mode)

Return type:

tuple

refresh()

Refresh task list from file

static help()

Show help modal with all keyboard shortcuts.

toggle_caps()

Toggle current task text between ALL CAPS and original case.

Bulk Operations

Bulk task operations mixin for CommandHandler.

class jot.commands._bulk_mixin.BulkMixin

Bases: object

Bulk actions on multiple selected tasks.

bulk_actions_menu(selected_task_ids)

Show bulk actions menu and return selected action.

Returns:

‘priority’, ‘status’, ‘delete’, ‘archive’, ‘cancel’, or None

Return type:

str

bulk_set_priority(task_ids)

Set priority for multiple tasks.

bulk_set_status(task_ids)

Set status for multiple tasks.

bulk_delete(task_ids)

Delete multiple tasks with confirmation.

bulk_archive(task_ids)

Archive multiple tasks with confirmation.

Context Commands

Project/category switching mixin.

class jot.commands._context_mixin.ContextMixin

Bases: object

Switch projects, switch categories, register projects.

switch_category()

Switch to a different category (local or global)

switch_project()

Switch to a different registered project

register_current_project()

Register the current project in the global project registry

Metadata Commands

Metadata operations mixin (priority, status, day assignment).

class jot.commands._metadata_mixin.MetadataMixin

Bases: object

Day assignment, priority, and status operations.

assign_day()

Assign a day of the week to the current task

set_priority()

Set priority for the current task

toggle_highlight()

Pick a task state (color-coded) for the current task.

quick_highlight()

Toggle default highlight color on the current task.

set_priority_high()

Toggle current task priority between high and none.

set_status()

Set status for the current task

assign_parent()

Assign current task as a subtask of another task (Ctrl+L).

Notes Commands

Notes editing, subtask sync, and keyword action mixin.

class jot.commands._notes_mixin.NotesMixin

Bases: object

Editor-based notes, subtask sync, and keyword actions.

static safe_launch_editor(file_path)

Safely launch editor with file_path, avoiding command injection.

Uses shlex.split() to safely parse $EDITOR which may contain arguments (e.g., “emacs -nw”), then calls subprocess without shell=True to prevent command injection.

get_notes_file_extension(editor)

Determine file extension based on editor.

edit_task_notes()

Edit notes for the current task using $EDITOR

sync_subtasks()

Manually sync subtasks from current task’s notes (Ctrl+S)

trigger_keyword_action()

Manually trigger keyword action for current task

Transfer Commands

Task transfer/copy/move mixin.

class jot.commands._transfer_mixin.TransferMixin

Bases: object

Copy, move, and transfer tasks between projects/categories.

copy_task_to_project()

Copy current task to a different project (keeps original)

move_task_to_project()

Move current task to a different project

transfer_task_to_category()

Transfer current task to a different category within the same project

AI Analysis

AI task analysis and execution mixin.

class jot.commands._ai_analysis_mixin.AiAnalysisMixin

Bases: object

Analyze tasks with Claude and execute analysis plans.

ultrathink_task()

Analyze current task with Claude Code

execute_analysis_task()

Execute analysis plan with Claude Code.

AI Suggest

AI task suggestion mixin.

class jot.commands._ai_suggest_mixin.AiSuggestMixin

Bases: object

Suggest new tasks using Claude CLI.

suggest_task()

Analyze tasks and suggest a new one using Claude (Shift+4)

Audio Timer (deprecated)

Text-to-speech and timer mixin.

class jot.commands._audio_timer_mixin.AudioTimerMixin

Bases: object

Read tasks aloud and priority timer.

read_tasks_aloud()

Read all tasks in current category aloud using TTS (Shift+2)

start_priority_timer()

Launch bullet priority timer for current task

Google Calendar

Google Calendar integration mixin.

Exceeds 300-line guideline: gcal requires 7 user-facing flows (account setup, selection, export single/bulk, import with multi-day direction/grouping/display, re-authentication) that cannot be further decomposed without losing readability.

class jot.commands._gcal_mixin.GcalMixin

Bases: object

Google Calendar import, export, and account management.

select_gcal_account()

Select Google Calendar account. Returns account name or None.

export_to_gcal()

Export task(s) to Google Calendar — single or bulk today

import_from_gcal()

Import Google Calendar events as tasks (1-7 days)

reauthenticate_google_calendar()

Force re-authentication with Google Calendar (Shift+3)

Web Clipboard

Web search, URL opening, and clipboard mixin.

class jot.commands._web_clipboard_mixin.WebClipboardMixin

Bases: object

Web search, URL opening, and clipboard operations.

web_search()

Open a web search with the current task text

open_url()

Open URL(s) from current task text in browser

copy_to_clipboard()

Copy current task text to clipboard