Core — Task Management

The core package contains the task management engine: TaskManager and its mixins, IDManager, and shared constants.

TaskManager

class jot.core.task_manager.TaskManager(storage_file='.jot.json', directory=None, id_manager=None, category=None, is_global=False, project_registry=None)

Bases: PersistenceMixin, IdMigrationMixin, CrudMixin, MetadataMixin, DeleteMixin, NavigationMixin, SubtaskMixin, AgeBacklogMixin

Handles task storage and retrieval

__init__(storage_file='.jot.json', directory=None, id_manager=None, category=None, is_global=False, project_registry=None)

Initialize TaskManager.

Parameters:

• storage_file – Base filename (used only if category is None and not global)

• directory – Project directory (ignored if is_global=True)

• id_manager – Shared IDManager instance

• category – Category name (validated for path traversal safety)

• is_global – If True, use global category storage in ~/.jot-categories/

• project_registry – Optional ProjectRegistry for keyword-based project routing

IDManager

class jot.core.id_manager.IDManager(project_dir=None)

Bases: object

Manages unique task IDs across all categories in a project

__init__(project_dir=None)

Initialize ID manager for a project directory

allocate_id()

Allocate a new unique ID with atomic file locking

release_id(task_id)

Release an ID (when task is deleted)

migrate_from_existing_ids(existing_ids)

Migrate from existing task IDs found in category files. Sets next_id to max(existing_ids) + 1 and marks all as allocated.

get_stats()

Get ID allocation statistics

Constants

Core constants for jot application

Archive Manager

Archive management for jot tasks: compress, export, prune.

class jot.core.archive_manager.ArchiveManager(project_dir=None)

Bases: ExportMixin, CompressMixin

Manages archived tasks: compress, export, prune

__init__(project_dir=None)

Initialize ArchiveManager for a project directory

prune_archives(strategy='older_than', value=None, interactive=False)

Remove old archived tasks.

Parameters:

• strategy – ‘older_than’ (months), ‘keep_last’ (count), or ‘file’

• value – Strategy-specific value

• interactive – Show confirmation dialog

get_archive_stats()

Get statistics about archives

Mixins

CRUD Operations

CRUD mixin — add, get, edit tasks and schema migration.

class jot.core._crud_mixin.CrudMixin

Bases: object

Task creation, retrieval, editing, and schema migration.

add_task(task_text, priority='none', status='todo', labels=None, effort=None)

Add a new task with guaranteed unique ID from IDManager.

Returns:

Task ID for normal adds, or routing metadata dict if task targets another project or broadcast.

Return type:

int or dict

duplicate_task(task_id)

Duplicate a task by ID, creating a new copy with a fresh ID.

ensure_default_task()

Create default ‘take a break’ task if no tasks exist

get_tasks()

Return all tasks

get_current_task()

Get the currently selected task

get_task_notes(task_id)

Get notes for a task

edit_task(task_id, new_text)

Edit a task’s text by ID

set_task_field(task_id, field, value)

Set an arbitrary field on a task. Removes the field if value is None.

set_task_notes(task_id, notes_text)

Set notes for a task

migrate_backlog_schema()

Migrate existing tasks to include backlog grooming metadata.

Returns:

Migration statistics

Return type:

dict

Delete Operations

Delete mixin, archive, permanent delete, notes export.

class jot.core._delete_mixin.DeleteMixin

Bases: object

Task removal, archival, and notes preservation.

remove_task(task_id)

Archive a task by ID and set previous task as current

delete_task_permanently(task_id)

Permanently delete a task and release its ID for reuse

archive_task(task_id)

Archive a task by ID (wrapper around remove_task)

save_notes_to_org_file(task_id)

Save task notes to an org file before deletion. Only creates file if task has non-empty notes.

Returns:

Path to created org file, or None if no notes

Return type:

str

Persistence

Persistence mixin — load, save, refresh.

class jot.core._persistence_mixin.PersistenceMixin

Bases: object

Load and save tasks to JSON file.

refresh()

Reload tasks from file

Navigation

Navigation mixin — move, sort, and cycle through tasks.

class jot.core._navigation_mixin.NavigationMixin

Bases: object

Task ordering and current-task navigation.

move_task_up()

Move the current task up in the list

move_task_down()

Move the current task down in the list

sort_by_priority()

Sort tasks by priority (high -> medium -> low -> none)

set_next_current(filtered_tasks=None)

Set the next task as current.

Parameters:

filtered_tasks – Optional list to navigate within (today filter, search).

set_prev_current(filtered_tasks=None)

Set the previous task as current.

Parameters:

filtered_tasks – Optional list to navigate within (today filter, search).

Metadata

Metadata mixin — current, agent, day, priority, status, tally.

class jot.core._metadata_mixin.MetadataMixin

Bases: object

Set task metadata: current flag, agent, day, priority, status, tally.

set_current(task_id)

Mark a task as current (only one can be current). If the task is archived, it will be automatically unarchived.

set_agent_task(task_id=None)

Mark a task as agent_task (Claude Code is working on it). Only one task can be agent_task at a time. Toggles if already set.

set_highlight(task_id=None, color=None)

Set highlight color on a task, or clear it.

Parameters:

• task_id – Task to highlight (defaults to current task).

• color – Color name from HIGHLIGHT_COLORS, or None to clear.

set_task_day(task_id, day)

Assign a day of the week to a task (Monday-Sunday or None).

set_task_priority(task_id, priority)

Set priority for a task (‘none’, ‘low’, ‘medium’, ‘high’).

set_task_status(task_id, status)

Set status for a task (‘todo’, ‘in-progress’, ‘blocked’, ‘done’).

increment_tally()

Increment the tally counter for the current task

Subtasks

Subtask sync mixin — parse checklist items from notes.

class jot.core._subtask_mixin.SubtaskMixin

Bases: object

Sync subtasks from task notes checklists.

sync_subtasks_from_notes(task_id)

Parse checklist items from task notes and sync as subtasks.

Parses ‘- [ ] text’ (todo) and ‘- [X] text’ (done) lines. Nested text below a checklist item becomes the subtask’s notes. Creates new tasks with ‘parent:{id}’ label, skips duplicates.

Returns:

dict with ‘created’, ‘updated’, ‘total’ counts, or None if task not found

Compress

Compress mixin — compress archived tasks into tar.gz files.

class jot.core._compress_mixin.CompressMixin

Bases: object

Compress old archived tasks into monthly tar.gz archives.

compress_archives(keep_n=None, category=None)

Compress old archived tasks into timestamped tar.gz files.

Parameters:

• keep_n – Number of recent archived tasks to keep in main file

• category – Specific category to compress (or None for default)

Returns:

dict with compression results

Export

Export mixin — archive export to JSON, CSV, Markdown, text.

class jot.core._export_mixin.ExportMixin

Bases: object

Export archived tasks in multiple formats.

export_archives(format='json', output=None, include_compressed=True, category=None)

Export archived tasks to various formats.

Parameters:

• format – ‘json’, ‘csv’, ‘markdown’, or ‘text’

• output – Output file path (or None for auto-named file)

• include_compressed – Include tasks from compressed archives

• category – Export specific category only

Returns:

dict with export results

Age Backlog

Age and backlog mixin — staleness detection and task transfer.

class jot.core._age_backlog_mixin.AgeBacklogMixin

Bases: object

Task age analysis, staleness detection, and backlog transfer.

get_task_age_days(task)

Calculate age of task in days since last update.

is_task_stale(task, stale_threshold_days=7)

Check if a task is considered stale.

transfer_old_tasks_to_backlog(age_threshold_days=30, backlog_category='backlog')

Transfer tasks older than threshold to backlog category.

Returns:

Statistics about transferred tasks

Return type:

dict

ID Migration

ID migration mixin — migrate and auto-fix task IDs.

class jot.core._id_migration_mixin.IdMigrationMixin

Bases: object

Migrate existing IDs to IDManager and fix duplicates.