jott-cli 0.2.0

Simple, extensible interactive CLI task list

#+TITLE: jot - Simple Interactive CLI Task List
#+AUTHOR: Scott Anderson
#+DATE: 2025-10-02

[[./screenshots/Screenshot_2025-10-05 20.58.24_L0Nuxi.png]]

* Overview

~jot~ is a simple, extensible interactive CLI tool for managing task lists.
It provides a clean interface for quickly viewing and adding tasks in your
current directory.

* Features

- ⚡ **Quick-add mode by default** - Start typing immediately, no commands needed
- 📝 Dual-mode interface (Quick-add ↔ Command mode)
- 🚀 **Cross-project task routing** - Send tasks to any project by name
- 🔑 **Keyword automation system** - Auto-trigger actions with ~keyword: task~ format (bullet, gcal, ai, analyze, remind)
- 🤖 **Claude Code slash commands** - AI-assisted task management integration
- 🧠 **AI task analysis workflow** - Analyze tasks (Shift+9), execute plans (Shift+0) with session tracking
- 📋 **Analysis file tracking** - Persistent session management and resumability with visual indicators
- 🔌 **MCP Server** - Model Context Protocol server for Claude Code with full category support
- 📅 **Google Calendar integration** - Export tasks (Shift+G) and import events (Shift+I)
- ⏱  **Bullet priority timer integration** - Launch focus sessions (Shift+B) with automatic time tracking
- 💾 Persistent storage in local ~.jot.json~ file
- 🎨 Clean, interactive display with color-coded modes
- 🌿 **Special "take a break" styling** - Calming green color when current
- 🔧 Extensible command system for future features
- 📁 Auto-discovery of projects in ~/projects/

* Installation

** From PyPI (Recommended)

#+begin_src bash
# Install from PyPI
pip install jott

# Verify installation
jott --version
#+end_src

** From Source

#+begin_src bash
# Clone the repository
git clone [e-mail]:son1112/jot.git ~/projects/jot
cd ~/projects/jot

# Install in development mode
pip install -e .

# Optional: Install development dependencies for testing
pip install -e ".[dev]"
#+end_src

** Manual Installation

#+begin_src bash
# Clone the repository
git clone [e-mail]:son1112/jot.git ~/projects/jot

# Make the script executable
chmod +x ~/projects/jot/jot.py

# Create an alias in your shell config (.zshrc, .bashrc, etc.)
alias jott='python3 ~/projects/jot/jot.py'
#+end_src

* Usage

Simply run ~jott~ in any directory:

#+begin_src bash
jott
#+end_src

You can also add an initial task from the command line:

#+begin_src bash
jott "feed the cats"
jott buy groceries and milk
#+end_src

** Cross-Project Task Routing

Send tasks to specific projects by name from anywhere:

#+begin_src bash
# Add task to rubber-ducky-live project
jott rubber-ducky-live 'implement OAuth refresh tokens'

# Add task to storytime project
jott storytime 'add voice pitch variation'

# List all registered projects
jott --list-projects

# View all projects with their tasks grouped
jott --all-projects

# Manually register a project
jott --register my-project /path/to/project

# Unregister a project
jott --unregister my-project

# Refresh auto-discovery
jott --refresh
#+end_src

*Auto-Discovery:* On first run, jot automatically discovers all projects in
~/projects/ that contain a .jot.json file and registers them in
~~/.jot-projects.json~.

*All Projects Overview:* The ~--all-projects~ command provides a bird's-eye
view of your entire project ecosystem. It displays each project with:
- Task counts (active and archived)
- Up to 10 active tasks per project
- Current task highlighting with ✨ or 🌿 icons
- Long task text truncated for readability
- Project paths for reference

[[./screenshots/Screenshot_2025-10-05 13.35.29_0vIeH9.png]]

This is useful for daily planning, spotting neglected projects, and getting a
quick overview of what's happening across your entire portfolio.

** Visual Styling

~jot~ uses color to enhance the user experience:

- **Current task**: Cyan + bold + ✨ icon (→ marker)
- **"Take a break" task (when current)**: Green + bold + 🌿 icon
- **Quick-add mode**: Green footer
- **Command mode**: Yellow footer

[[./screenshots/Screenshot_2025-10-05 21.10.58_fGILCJ.png]]

The special "take a break" styling provides a calming visual reminder when
you need rest. Each project displays its name in the header with a distinctive
ASCII art logo.

[[./screenshots/Screenshot_2025-10-05 21.10.17_KZLn6S.png]]

** Smart Deletion

When you delete a task, ~jot~ automatically maintains your workflow by
setting the previous task as current. This keeps you in the flow when
cleaning up completed items:

- **Middle task deletion**: Previous task becomes current
- **First task deletion**: New first task becomes current
- **Last task deletion**: New last task (previously second-to-last) becomes current
- **Only task deletion**: No current task (list is empty)

This eliminates the need to manually re-navigate after deletions.

** Moving Tasks Between Projects

Sometimes you realize a task belongs in a different project. The ~Shift+M~
shortcut lets you quickly move the current task to any registered project:

1. Navigate to the task you want to move (or it's already current)
2. Press ~Shift+M~ in either quick-add or command mode
3. Select target project by number or name
4. Task is removed from current project and added to target project

Starting with a task you want to move:

[[./screenshots/Screenshot_2025-11-14 12.28.48_uxLTDG.png]]

Press ~Shift+M~ and select from your registered projects:

[[./screenshots/Screenshot_2025-11-14 12.29.23_Ikt2w9.png]]

Task is now moved to the target project with all metadata preserved:

[[./screenshots/Screenshot_2025-11-14 12.32.24_nXZDiT.png]]

This is especially useful when you're doing daily planning and realize tasks
are in the wrong project context, or when breaking down large tasks across
multiple projects.

** Notes Feature

Attach detailed notes to any task using the ~Shift+N~ shortcut. Notes open in
your preferred editor ($EDITOR) and support rich text, code snippets, links,
or any other information you need to remember about a task.

*** Using Notes

1. Navigate to a task (make it current with arrow keys or 'c' command)
2. Press ~Shift+N~ to open notes editor
3. Add your notes (lines starting with # are ignored)
4. Save and close editor
5. Task shows 📝 icon when it has notes

[[./screenshots/Screenshot_2025-11-14 12.31.27_Ne5MJK.png]]

*** Notes Indicator

Tasks with notes display a 📝 emoji so you can quickly identify which tasks
have additional context:

[[./screenshots/Screenshot_2025-11-14 12.32.24_nXZDiT.png]]

*** Editing Notes

- Press ~Shift+N~ again to edit existing notes
- Clear all content to remove notes from a task
- Notes are preserved when moving tasks between projects

*** Inline Notes Display

Toggle inline notes viewing with ~Shift+F~ to see notes directly in the task list
without opening the editor. When enabled, tasks with notes show their content
indented below:

#+begin_example
  [ ] 75. 📝 ✨ test hol
      ├─ this is really cool. at first it's like.... oh it's janky, but reme...
      │       this is not for you
      └─ ... (1 more line)
#+end_example

[[./screenshots/Screenshot_2025-11-18 12.17.12_9jH8Jb.png]]
/Inline notes display - press Shift+F to toggle notes visibility/

Features:
- Shows up to 3 lines of notes
- Truncates long lines at 70 characters
- Uses box-drawing characters for visual connection
- Dim styling distinguishes notes from task text
- Press ~Shift+N~ to edit notes (still works when inline display is on)

** Fuzzy Search Mode

Quickly find tasks with fuzzy search by pressing ~/~ in quick-add mode. Type
any part of the task text to filter the list - matches can be non-contiguous
characters.

*** How It Works

1. Press ~/~ from quick-add mode
2. Start typing to filter tasks (e.g., "aut" matches "authentication")
3. Use ~↑/↓~ to navigate filtered results
4. Press ~Enter~ to select a task (makes it current)
5. Press ~ESC~ to cancel and return to quick-add

Fuzzy matching means you can find tasks quickly without typing the exact text.
Perfect for navigating large task lists.

** Multi-select Mode

Perform bulk operations on multiple tasks at once using ~Shift+V~ to enter
multi-select mode.

*** Using Multi-select

1. Press ~Shift+V~ from quick-add mode
2. Navigate with ~↑/↓~ and press ~Space~ to toggle task selection
3. Perform operations on all selected tasks:
   - Delete multiple tasks
   - Move to different project
   - Archive multiple tasks
   - Change priority/status in bulk
4. Press ~ESC~ to exit multi-select mode

The footer shows the count of selected tasks. This is especially useful for
cleaning up completed tasks or reorganizing large task lists.

** Google Calendar Integration

Bidirectional sync between jot and Google Calendar:
- **Export** (~Shift+G~): Send tasks to your calendar
- **Import** (~Shift+I~): Fetch today's events as tasks

*** Setup

1. **Enable Google Calendar API** in Google Cloud Console:
   - Go to [[https://console.cloud.google.com][Google Cloud Console]]
   - Create or select a project
   - Enable "Google Calendar API"

2. **Create OAuth 2.0 credentials**:
   - Navigate to "Credentials" in your project
   - Click "Create Credentials" → "OAuth client ID"
   - Choose "Desktop app" as application type
   - Download the credentials file

3. **Install credentials**:
   #+begin_src bash
   mkdir -p ~/.jot
   mv ~/Downloads/credentials.json ~/.jot/credentials.json
   #+end_src

4. **First-time authentication**:
   - Press ~Shift+G~ on any task
   - Your browser will open for Google OAuth consent
   - Grant calendar access to the app
   - Token is saved to ~~/.jot/token.json~ for future use

*** Usage

**** Export Tasks to Calendar (Shift+G)

In quick-add mode, navigate to any task and press ~Shift+G~:

#+begin_example
→ [✨] 42. Team standup meeting

Press Shift+G

✓ Event created: Team standup meeting
   9:00 AM - 10:00 AM
   https://calendar.google.com/calendar/event?eid=...

Press Enter to continue...
#+end_example

[[./screenshots/Screenshot_2025-11-14 12.16.00_wd0Z2l.png]]
/Google Calendar account selection - choose between multiple configured accounts/

The event is created in your primary Google Calendar with:
- **Title**: Task text
- **Start time**: Current time (rounded to nearest 15 minutes)
- **Duration**: 15 minutes
- **Description**: "Created from jot task"

**** Import Events as Tasks (Shift+I)

In quick-add mode, press ~Shift+I~ to fetch today's calendar events:

#+begin_example
Press Shift+I

Found 3 event(s) for today:

  1. 9:00 AM - 9:30 AM: Morning Standup
  2. 📅 Team Offsite
  3. 2:00 PM - 3:00 PM: Client Review

Import all as tasks? (y/N): y

✓ Imported 3 event(s) as tasks

Press Enter to continue...
#+end_example

Imported events become tasks with time prefixes:
- **Timed events**: "9:00 AM - 9:30 AM: Morning Standup"
- **All-day events**: "📅 Team Offsite"

*** Requirements

The Google Calendar integration requires additional Python packages:
#+begin_src bash
pip install google-auth google-auth-oauthlib google-auth-httplib2 google-api-python-client
#+end_src

These are automatically installed with the main jot package.

** Bullet Priority Timer Integration

Quick launch the bullet priority timer for focused work sessions directly from jot.

Press ~Shift+B~ in quick-add mode to start a 12-minute priority timer:

#+begin_example
→ [✨] 42. Fix authentication bug

Press Shift+B

🔥 Starting priority timer for: Fix authentication bug
Duration: 12 minutes (default)

Press Enter to continue...

✓ Priority timer started

Press Enter to continue...
#+end_example

[[./screenshots/Screenshot_2025-11-14 12.23.09_qkMuqJ.png]]
/Bullet priority timer started - 12-minute focused work session/

*** Features
- *Auto-links to current task* - Bullet automatically tracks time for the current jot task
- *Enhanced alerts* - Louder sound and voice announcement with task name
- *Perfect for focused work* - 12-minute default duration ideal for urgent tasks
- *Non-blocking* - Returns to jot immediately while timer runs in background

*** Requirements

Requires [[https://github.com/sonander/bullet][bullet timer]] to be installed:

#+begin_src bash
cd ~/projects/bullet
npm install
npm link
#+end_src

*** What is Bullet?

bullet is a developer-focused CLI timer that integrates with jot for time tracking:
- Priority timers with enhanced alerts
- Auto-cycling timers (Pomodoro, 10-and-2, 52-17)
- Session logging and AI-powered summaries
- Tmux status bar integration

See the [[https://github.com/son1112/bullet][bullet repository]] for full documentation.

** Claude Code Task Analysis & Execution

Break down complex tasks with AI-powered analysis and execute implementation
plans with full session tracking and resumability.

*** Overview

The analysis workflow helps you:
- Break down complex tasks into detailed implementation plans
- Get AI-generated technical approach and risk assessment
- Execute plans in Claude Code with persistent session tracking
- Resume interrupted work sessions seamlessly

*** How It Works

1. *Analyze (Shift+9)*: Claude Code analyzes the current task in plan mode and
   creates a detailed ~.jot.analysis.{id}.org~ file containing:
   - Task breakdown into subtasks with checkboxes
   - Technical approach recommendations
   - Complexity estimates (Simple/Medium/Complex)
   - Potential risks and mitigation strategies
   - Acceptance criteria

2. *Execute (Shift+0)*: Launches Claude Code in a new Terminal window with:
   - The analysis file loaded as system context
   - Unique session UUID for resumability
   - Execution history tracking per task
   - Automatic session metadata storage
   - Task automatically marked as agent task (🤖)

*** Usage Example

#+begin_example
→ [✨] 208. 📋 organize .jot.* files

Press Shift+9 to analyze...

🤔 Analyze: organize .jot.* files

Options:
  [Enter] - Standard analysis
  [c]     - Custom analysis prompt
  [q]     - Cancel

Choice: [Enter]

⏳ Analyzing with Claude Code...
This may take 10-15 seconds...

✓ Analysis saved to .jot.analysis.208.org ($0.043)

Open analysis in editor? [Y/n]: y
#+end_example

After reviewing the analysis plan:

#+begin_example
→ [✨] 208. 📋 organize .jot.* files

Press Shift+0 to execute...

🚀 Launching Claude Code...
Task ID: 208
Session: a3f9b2c1...
Analysis: .jot.analysis.208.org

✓ Terminal launched

Claude Code is running in a new Terminal window
Session ID: a3f9b2c1-4d6e-5a2b-8c9d-1e3f7g8h9i0j
#+end_example

*** Visual Indicators

Tasks with analysis files show a 📋 indicator:

#+begin_example
208. 📋 organize .jot.* files
209. 📝 Update documentation
210. 🤖 Fix authentication bug   <- Agent task (Claude working on it)
#+end_example

*** Analysis File Format

Analysis files (~.jot.analysis.{id}.org~) are Org-mode documents containing:

#+begin_example
#+TITLE: Analysis for Task 208
#+DATE: 2025-12-11 12:00
#+TASK: organize .jot.* files

* Task Analysis

** Overview
Brief description of what needs to be done...

** Task Breakdown
- [ ] Subtask 1: Create backup directory
- [ ] Subtask 2: Implement pruning logic
- [ ] Subtask 3: Add configuration options

** Technical Approach
Key technical decisions and implementation strategy...

** Acceptance Criteria
- Criterion 1: All .jot.* files organized
- Criterion 2: No data loss
- Criterion 3: Configuration documented

** Complexity Estimate
Medium - Requires file system operations and testing

** Potential Risks
- Risk 1: Accidentally deleting active files
  Mitigation: Test with backups first
#+end_example

*** Session Tracking

Each execution creates a session record stored in task metadata:

#+begin_src json
{
  "execution_history": [
    {
      "session_id": "a3f9b2c1-4d6e-5a2b-8c9d-1e3f7g8h9i0j",
      "started_at": "2025-12-11T12:15:30",
      "status": "in_progress",
      "analysis_file": ".jot.analysis.208.org"
    }
  ]
}
#+end_src

To resume an interrupted session, use the stored session ID:

#+begin_src bash
claude --session-id a3f9b2c1-4d6e-5a2b-8c9d-1e3f7g8h9i0j
#+end_src

Next time you press ~Shift+0~ on the same task, jot will offer to resume the
existing session or start a new one.

*** Integration with Keyword System

Use the ~analyze:~ keyword for automatic analysis on task creation:

#+begin_example
analyze: Implement OAuth refresh token system
#+end_example

This triggers immediate Claude Code analysis in plan mode. The analysis runs
automatically when you press Enter, creating the analysis file without
additional interaction.

The task will show the 📋 indicator as soon as the analysis completes.

*** When to Use Analysis Workflow

*Best for:*
- Complex tasks requiring detailed breakdown
- Technical implementation planning
- Long-running development sessions
- Tasks needing risk assessment
- Unfamiliar problem domains
- Tasks with multiple subtasks

*Use slash commands instead when:*
- Already in Claude Code session
- Quick task queries or updates
- Managing multiple tasks at once
- Integration with Claude Code conversation

*** Requirements

- Claude Code CLI must be installed and configured (~claude --version~)
- Terminal emulator (Terminal.app, iTerm2, gnome-terminal, konsole, or similar)
- macOS, Linux, or Windows with bash/compatible shell

*** Tips & Best Practices

- *Review analysis before executing*: Press ~Shift+9~, review in editor, then
  ~Shift+0~ to execute
- *Add task notes first*: Use ~Shift+N~ to add context before analyzing - Claude
  will include notes in the analysis
- *Custom analysis focus*: Press ~c~ during analysis to specify focus (e.g.,
  "security implications", "performance optimization")
- *Session persistence*: Session UUIDs are deterministic per task - same UUID for
  resume operations
- *Combine with priorities*: Use ~Shift+P~ to set priority before analyzing
  critical tasks
- *Track execution*: Use ~execution_history~ to see how many attempts a task
  required

** Modes

~jot~ operates in two modes:

*** Quick-Add Mode (Default)
- Start typing immediately to add tasks
- Press ~Enter~ to save the task
- Press ~ESC~ to switch to Command mode
- Press ~Backspace~ to edit your input
- Use ~↑/↓~ or ~Ctrl+N/P~ to navigate tasks (without leaving quick-add mode)
- Use ~Shift+↑/↓~ to reorder tasks (without leaving quick-add mode)
- Press ~Shift+M~ to move current task to different project (without leaving quick-add mode)
- Press ~Shift+R~ to refresh task list (without leaving quick-add mode)
- Press ~Shift+Q~ to quit (without leaving quick-add mode)

*** Command Mode
- Press ~a~ to return to Quick-Add mode
- Use single-key commands (see below)
- Navigate and manage tasks

** Commands

*** Task Management
- ~a~ - Switch to Quick-Add mode (from Command mode)
- ~c~ - Mark task as current
- ~d~ - Delete task by ID (previous task becomes current)
- ~D~ - Delete current task (Shift+D) (previous task becomes current)
- ~e~ - Edit task by ID
- ~E~ - Edit current task (Shift+E)
- ~M~ - Move current task to different project (Shift+M)
- ~r~ - Refresh task list
- ~h~ - Show help
- ~q~ - Quit

*** Navigation
- ~↑~ / ~Ctrl+p~ - Previous task
- ~↓~ / ~Ctrl+n~ - Next task
- ~Shift+↑~ - Move current task up in priority
- ~Shift+↓~ - Move current task down in priority

[[./screenshots/Screenshot_2025-11-14 12.35.31_nY4pau.png]]
/Task reordering with Shift+↑ - task 426 moved to top of list/

*** Quick-Add Mode Shortcuts
- ~Shift+M~ - Move current task to different project
- ~Shift+R~ - Refresh task list
- ~Shift+Q~ - Quit

** Storage

Tasks are stored in ~.jot.json~ in your current directory. Each directory
maintains its own task list.

The JSON file uses this structure:

#+begin_src json
{
  "tasks": [
    {
      "id": 1,
      "text": "feed the cats",
      "done": false,
      "current": true
    }
  ],
  "archived": []
}
#+end_src

When you delete tasks, they are moved to the ~archived~ array rather than
being permanently deleted.

* Keyword Automation System

~jot~ includes a powerful keyword automation system that triggers actions when
tasks are created with special keyword prefixes.

** How It Works

When you add a task with the format ~keyword: task text~, jot automatically
detects the keyword and executes the associated action.

#+begin_example
bullet: Write documentation  # Starts priority timer automatically
gcal: Team standup          # Exports to Google Calendar
ai: Research quantum AI     # Marks task for Claude Code (🤖)
remind: Check email         # Sets notification (manual trigger)
#+end_example

** Built-in Keywords

| Keyword  | Action                                        | Auto-Trigger |
|----------+-----------------------------------------------+--------------|
| bullet:  | Start bullet priority timer                   | Yes          |
| gcal:    | Export task to Google Calendar                | Yes          |
| ai:      | Mark task for AI/agent                        | Yes          |
| analyze: | Analyze with Claude Code (creates .org file)  | Yes          |
| remind:  | Display system notification                   | No (manual)  |

** Configuration

Keywords are configured in ~~/.jot-keywords.json~:

#+begin_src json
{
  "keywords": {
    "bullet": {
      "auto_trigger": true,
      "description": "Start bullet priority timer"
    }
  },
  "aliases": {
    "timer": "bullet",  // Shortcuts to existing keywords
    "claude": "ai"
  }
}
#+end_src

Here's what the configuration file looks like:

[[./screenshots/Screenshot_2025-11-14 12.22.55_2Fh6jD.png]]

** Using Keywords

*** Auto-Trigger Keywords

Keywords with ~auto_trigger: true~ execute immediately when the task is created:

#+begin_example
$ jot "bullet: Deep work session"
✓ Added: bullet: Deep work session
Started bullet priority timer
#+end_example

Here's the ~bullet:~ keyword in action - typing the task:

[[./screenshots/Screenshot_2025-11-14 11.37.10_cfzySS.png]]

And the result after the timer launches:

[[./screenshots/Screenshot_2025-11-14 12.16.38_MG2V4O.png]]

The ~ai:~ keyword marks tasks for Claude Code with a 🤖 emoji:

[[./screenshots/Screenshot_2025-11-14 12.14.59_NPtJIu.png]]

The ~gcal:~ keyword exports tasks to Google Calendar:

[[./screenshots/Screenshot_2025-11-14 11.39.08_gvfOkp.png]]

*** Manual-Trigger Keywords

Keywords with ~auto_trigger: false~ require manual execution with *Shift+E*:

#+begin_example
1. Add task: "remind: Call dentist"
2. Navigate to task
3. Press Shift+E to execute keyword action
#+end_example

** Keyboard Shortcuts

- *Shift+E* - Execute keyword action for current task (manual trigger)
- Works for both auto-trigger and manual-trigger keywords

** Aliases

Create shortcuts to existing keywords for convenience:

#+begin_src json
"aliases": {
  "timer": "bullet",   // timer: → bullet:
  "cal": "gcal",       // cal: → gcal:
  "claude": "ai"       // claude: → ai:
}
#+end_src

Example usage:
#+begin_example
$ jot "timer: Focus session"    # Same as bullet:
$ jot "claude: Research task"   # Same as ai:
#+end_example

** Adding Custom Keywords (Advanced)

*Note:* Custom keywords require editing ~jot.py~ source code. This is not
configurable through ~~/.jot-keywords.json~ alone.

To add a new keyword:

1. *Add handler function* to ~KeywordHandler~ class in ~jot.py~:

#+begin_src python
def _handle_email(self, task):
    """Send task via email"""
    import smtplib
    # Your implementation here
    task_text = task['text']
    # Send email logic...
    return f"Emailed task: {task_text}"
#+end_src

2. *Register the handler* in ~_register_builtin_handlers()~ method:

#+begin_src python
def _register_builtin_handlers(self):
    # ... existing handlers ...

    self.register('email', self._handle_email,
                  auto_trigger=True,
                  description="Email task to yourself")
#+end_src

3. *Update config* (optional) - Add to ~~/.jot-keywords.json~:

#+begin_src json
{
  "keywords": {
    "email": {
      "auto_trigger": true,
      "description": "Email task to yourself"
    }
  }
}
#+end_src

4. *Use your keyword*:

#+begin_example
$ jot "email: Remember meeting notes"
✓ Added: email: Remember meeting notes
Emailed task: Remember meeting notes
#+end_example

** Keyword Validation

Keywords must be:
- Alphanumeric characters, hyphens, or underscores only
- Followed by a colon and space
- Case-insensitive (normalized to lowercase)

Valid:   ~bullet:~, ~gcal:~, ~my-keyword:~, ~task_123:~
Invalid: ~@mention:~, ~#hashtag:~, ~space keyword:~

* Architecture

** Extensibility

The command system is designed for easy extension. To add new commands:

1. Add a method to the ~CommandHandler~ class
2. Register it in the ~commands~ dictionary
3. The method should return ~True~ to continue running or ~False~ to quit

** Example: Adding a Delete Command

#+begin_src python
def delete_task(self):
    """Delete a task by ID"""
    task_id = int(input("Task ID to delete: "))
    # Implementation here
    return True

# In __init__:
self.commands['d'] = self.delete_task
#+end_src

** File Structure

The jot project follows an organized file structure for task data, backups, and
analysis files:

#+begin_example
project-directory/
├── .jot.json                      # Main task database
├── .jot.{category}.json           # Category-specific task files
├── .jot-backups/                  # Organized backup directory
│   ├── README.md                  # Backup documentation
│   ├── 2025-10/                   # October 2025 backups
│   │   └── YYYYMMDD_HHMMSS.json
│   ├── 2025-11/                   # November 2025 backups
│   │   └── YYYYMMDD_HHMMSS.json
│   └── YYYY-MM/                   # Future month directories
│       └── YYYYMMDD_HHMMSS.json
├── .jot.analysis.{id}.org         # Task analysis files (Shift+9)
├── .jot-id-manager.json           # ID allocation state
└── .jot-projects.json             # Global project registry (~/)
#+end_example

*** Task Database (~.jot.json~)

The main task storage file containing:
- Active tasks with metadata
- Archived tasks
- Task IDs and state
- Keyword automation metadata

*** Backup System (~.jot-backups/~)

Automatic backups are created in organized year-month subdirectories:

*When backups are created:*
- Before task deletion
- Before bulk operations
- Before schema migrations
- Before duplicate ID fixes

*Naming convention:* ~YYYYMMDD_HHMMSS.json~

*Retention policy:* Keep last 10 backups OR 30 days (manual pruning for now)

See ~.jot-backups/README.md~ for restoration and management details.

*** Analysis Files (~.jot.analysis.{id}.org~)

Created when using Shift+9 or ~analyze:~ keyword. Contains:
- Task breakdown
- Technical approach
- Complexity estimate
- Risk assessment
- Acceptance criteria

These files enable the Shift+0 execution workflow with persistent session
tracking.

*** ID Manager (~.jot-id-manager.json~)

Maintains ID allocation state to prevent ID conflicts across:
- Active tasks
- Archived tasks
- Multiple categories

*** Project Registry (~~/.jot-projects.json~)

Global registry of all jot-enabled projects for cross-project task routing via
~/jot-to~ command.

* Claude Code Integration

~jot~ includes custom slash commands for AI-assisted task management directly
within Claude Code. These commands let you manage tasks without leaving your
development context.

** Available Slash Commands

[[./screenshots/Screenshot_2025-10-06 09.15.50_2LDCLi.png]]

- ~/jot~ - Show current tasks with AI analysis
- ~/jot-add <task>~ - Add a new task
- ~/jot-to <project> <task>~ - Add task to a specific project
- ~/jot-done <id>~ - Mark task as complete and archive it
- ~/jot-current [id]~ - Show or set current task
- ~/jot-archive~ - View archived tasks
- ~/jot-summary~ - Get AI-powered task analysis and recommendations

** Quick Example

#+begin_example
/jot                                    # See your tasks
/jot-add implement OAuth flow           # Add a task
/jot-to rubber-ducky-live fix bug       # Add task to another project
/jot-current 7                          # Set task #7 as current
/jot-done 5                             # Archive completed task
/jot-summary                            # Get AI recommendations
#+end_example

** In Action

[[./screenshots/Screenshot_2025-10-06 09.17.05_K460SZ.png]]

The ~/jot~ command provides AI-powered analysis of your current tasks,
including summaries and intelligent recommendations for what to focus on next.

See [[file:CLAUDE-CODE-SLASH-COMMANDS.org][CLAUDE-CODE-SLASH-COMMANDS.org]] for detailed documentation and workflow
examples.

** MCP Server

~jot~ includes a Model Context Protocol (MCP) server that provides deep
integration with Claude Code. This enables Claude to directly interact with
your tasks and categories without requiring slash commands.

*** Features

- **Category Management** - List, create, and switch between categories
- **Task Operations** - Add, update, delete, and query tasks
- **Task Properties** - Set day, priority, and status
- **Project Context** - Automatic awareness of local and global categories

*** Setup

#+begin_src bash
# Install MCP dependencies
pip install -e ".[mcp]"
#+end_src

Add to your Claude Code config:

#+begin_src json
{
  "mcpServers": {
    "jot": {
      "command": "python",
      "args": ["/absolute/path/to/jot/mcp_server.py"],
      "env": {}
    }
  }
}
#+end_src

*** Usage Examples

#+begin_example
# Claude can now directly interact with jot:
"Claude, list all my jot categories"
"Claude, add a task 'Fix authentication bug' to my bugs category"
"Claude, what's my current task?"
"Claude, set task #42 to high priority and assign it to Tuesday"
"Claude, create a new category called 'research'"
#+end_example

See [[file:MCP_SETUP.org][MCP_SETUP.org]] for complete setup instructions and API documentation.

* Roadmap

Implemented features:
- [X] Quick-add mode as default interface
- [X] Dual-mode system (Quick-add ↔ Command)
- [X] Quick-add mode shortcuts (Shift+R refresh, Shift+Q quit)
- [X] Special "take a break" styling (green + 🌿 icon when current)
- [X] Sparkle emoji for regular current tasks (✨ icon)
- [X] Smart deletion (previous task becomes current after deletion)
- [X] Cross-project task routing
- [X] Project auto-discovery
- [X] Project registry management (--list-projects, --register, --unregister)
- [X] All projects overview (--all-projects command)
- [X] Move tasks between projects (Shift+M shortcut)
- [X] Project name display in header
- [X] Navigation in quick-add mode (Ctrl+N/P, arrows)
- [X] Unique ID generation (no duplicates after deletions)
- [X] Default "take a break" task for empty projects
- [X] Test suite with pytest (14 tests)
- [X] Cleanup script for duplicate IDs
- [X] Claude Code slash commands integration
- [X] /jot-to command for cross-project tasks
- [X] Delete/remove tasks (~d~ command)
- [X] Edit task text (~e~ command)
- [X] Mark current task
- [X] Arrow key navigation
- [X] Keyboard shortcuts (Ctrl+n/p)
- [X] Task prioritization (move up/down)
- [X] Archive deleted tasks
- [X] Command-line initial task

* Testing

~jot~ includes a comprehensive test suite using pytest:

#+begin_src bash
# Run all tests
python3 -m pytest test_jot.py -v

# Run specific test
python3 -m pytest test_jot.py::test_unique_ids_after_deletion -v

# Run tests with coverage report
python3 -m pytest test_jot.py --cov=jot --cov-report=term-missing

# Generate HTML coverage report
python3 -m pytest test_jot.py --cov=jot --cov-report=html
# Open htmlcov/index.html in browser to view detailed coverage
#+end_src

**Test Coverage:**
- ID uniqueness (including after deletions)
- Default "take a break" task creation
- Current task exclusivity
- Task navigation and reordering
- Archive system
- Smart deletion (previous task becomes current)
  - Middle task deletion
  - First task deletion
  - Last task deletion
- Data persistence
- Project registry management

**Current Coverage:** 24% (core TaskManager and ProjectRegistry classes are
well-tested; CLI command handlers are not yet covered)

* Development & Code Quality

** Linting & Formatting

~jot~ uses ~black~ for code formatting and ~flake8~ for linting. Configuration
is managed through ~pyproject.toml~ and ~.flake8~.

*** Quick Commands

Use the provided Makefile for common development tasks:

#+begin_src bash
# Check code formatting (no changes)
make format-check

# Auto-format all Python files
make format

# Run linting checks
make lint

# Run all linting and formatting checks
make lint-all

# Run tests
make test

# Run tests with coverage
make test-cov
#+end_src

*** Manual Commands

If you prefer to run tools directly:

#+begin_src bash
# Format code with black
black jot.py test_*.py

# Check formatting without changes
black --check jot.py test_*.py

# Run flake8 linter
flake8 jot.py test_*.py

# Sort imports with isort
isort jot.py test_*.py
#+end_src

*** Configuration

*Line Length:* 100 characters (balances readability with practicality)

*Ignored Flake8 Rules:*
- ~E203~: Whitespace before ':' (conflicts with black)
- ~W503~: Line break before binary operator (outdated rule)
- ~F541~: F-string without placeholders (sometimes intentional)
- ~E501~: Line too long (black handles this)

*** Pre-Commit Workflow

Before committing:

#+begin_src bash
make format    # Auto-format code
make lint-all  # Verify all checks pass
make test      # Ensure tests pass
#+end_src

*** Installing Development Dependencies

#+begin_src bash
pip install -e ".[dev]"
#+end_src

This installs:
- ~pytest~ (testing)
- ~pytest-cov~ (coverage)
- ~black~ (formatting)
- ~flake8~ (linting)
- ~isort~ (import sorting)

* Maintenance

** Fixing Duplicate IDs

If you encounter duplicate task IDs (from using an older version), run:

#+begin_src bash
python3 fix-duplicate-ids.py              # Fix all projects
python3 fix-duplicate-ids.py path/to/.jot.json  # Fix specific file
#+end_src

This will:
- Create a timestamped backup
- Reassign unique IDs to all tasks
- Preserve task order

Future features to add:
- [ ] Toggle task completion (~t~ command)
- [ ] Clear completed/archived tasks
- [ ] Filter tasks (show only incomplete/complete)
- [ ] View archived tasks from CLI
- [ ] Delete current task from quick-add mode (Shift+D shortcut)
- [ ] Send task to Claude Code for AI assistance
- [ ] Due dates
- [ ] Tags/categories
- [ ] Export to other formats

* License

MIT