jott-cli 0.4.0

Feature-rich interactive CLI task manager with AI integration, calendar sync, and keyword automation

jott - AI-Powered CLI Project Management

A feature-rich, keyboard-driven task manager with AI integration, calendar sync, and intelligent automation for developers who live in the terminal.

Features

• Quick-add by default: Just start typing, press Enter to save
• Dual-mode interface: Quick-add mode ↔ Command mode (ESC to switch)
• Cross-project task routing: jott myproject "task" from anywhere
• Keyword automation: Tasks starting with bullet:, gcal:, ai:, analyze: trigger actions
• AI integration: Claude Code integration for task analysis (Shift+9) and execution (Shift+0)
• Google Calendar sync: Bidirectional sync (export tasks, import events)
• Text-to-speech: Read all tasks aloud with Shift+2
• Fuzzy search: Filter tasks quickly with Ctrl+/
• Fuzzy project picker: Interactive search when moving tasks between projects
• Multi-select mode: Bulk operations with Shift+V
• Category system: Up to 12 categories per project
• Task metadata: Priority, status, day-of-week assignment, notes
• Backup system: Organized monthly backups

Installation

From PyPI (Recommended)

# Basic installation
pip install jott-cli

# With text-to-speech support
pip install jott-cli[tts]

# Verify installation
jott --version

From Source

git clone https://github.com/son1112/jot.git
cd jot
pip install -e .

Quick Start

# Launch jott in current directory
jott

# Add a task from command line
jott "Update documentation"

# Quick-add to specific project
jott myproject "Fix authentication bug"

Usage

Quick-Add Mode (Default)

Just type and press Enter:

> Update README documentation
✓ Added: Update README documentation

Keyboard Shortcuts

Task Management:

• Shift+N - Edit task notes
• Shift+D - Delete current task
• Shift+A - Toggle archived tasks
• Shift+F - Toggle inline notes display
• Shift+4 - AI-powered task suggestion

Scheduling:

• Shift+W - Assign day of week
• Shift+P - Set priority
• Shift+X - Set status

AI Integration:

• Shift+9 - Analyze task with Claude Code (plan mode)
• Shift+0 - Execute analysis plan
• Shift+J - Mark as agent task

Integrations:

• Shift+2 - Read tasks aloud (TTS)
• Shift+3 - Re-authenticate Google Calendar
• Shift+G - Export to Google Calendar (single or bulk with time tags)
• Shift+I - Import from Google Calendar
• Shift+B - Start priority timer (12-minute focus session)

Navigation & System:

• ↑/↓ or Ctrl+N/P - Navigate tasks
• Shift+↑/↓ - Reorder tasks
• Ctrl+/ - Fuzzy search mode
• Shift+V - Multi-select mode
• Tab - Cycle through categories
• Ctrl+R - Register current project
• Ctrl+U - Open URLs from task text
• Ctrl+X - Quit
• ESC - Switch to command mode

Keyword Automation

Tasks starting with keywords trigger automatic actions:

• bullet: Deep work session → Starts bullet timer
• gcal: Team standup → Exports to Google Calendar
• ai: Refactor authentication → Marks for AI assistance
• analyze: Complex feature → Triggers Claude Code analysis

Categories

Organize tasks with categories (up to 12 per project):

# Switch to category
Shift+C

# Create category-specific tasks
jott --category=bugs "Fix login redirect"

Cross-Project Routing

Register projects for quick access:

# Auto-discover projects in ~/projects/
Ctrl+R

# Route task to different project
jott myproject "task text"

Configuration

Task Storage

• Local: .jot.json (current directory)
• Categories: .jot-categories/{category}.json
• Global categories: ~/.jot-categories/
• ID manager: .jot.ids.json

Google Calendar Setup

1. Enable Google Calendar API
2. Download credentials
3. Save as ~/.jot/gcal-accounts/default/credentials.json
4. Use Shift+G to export tasks

Re-authentication:

• Press Shift+3 to force re-authentication (if token expires or switching accounts)
• Or manually: rm ~/.jot/gcal-accounts/default/token.json

Text-to-Speech Configuration

Edit .jot.config.json:

{
  "tts": {
    "enabled": true,
    "rate": 150,
    "volume": 0.9,
    "voice": null
  }
}

Claude Code Integration

MCP Server

Jot includes an MCP (Model Context Protocol) server for Claude Code integration:

{
  "mcpServers": {
    "jot": {
      "command": "python",
      "args": ["/path/to/jot/mcp_server.py"],
      "env": {
        "JOT_PROJECT_DIR": "/your/workspace"
      }
    }
  }
}

Slash Commands

Available slash commands for Claude Code:

• /jot - Show current tasks
• /jot-add - Add task to current project
• /jot-done - Mark task as done
• /jot-current - Set/show current task
• /jot-to - Add task to specific project

Development

Running Tests

# Run all tests
make test

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

# Run linting
make lint

Test Coverage

• 169 tests (all passing)
• Zero linting errors

Security

Jot has undergone comprehensive security hardening:

• ✅ Command injection vulnerability fixed (EDITOR handling)
• ✅ Path traversal validation (category/project names)
• ✅ OAuth token permissions (0o600)
• ✅ Keyword length validation (DoS prevention)
• ✅ AppleScript quote escaping (notification system)

See SECURITY.md for full details.

Contributing

Contributions welcome! See CONTRIBUTING.md.

Development Setup

git clone https://github.com/son1112/jot.git
cd jot
pip install -e ".[dev]"
make format  # Format code
make lint    # Check linting
make test    # Run tests

License

MIT License - see LICENSE

Links

• GitHub: https://github.com/son1112/jot
• PyPI: https://pypi.org/project/jott-cli/
• Issues: https://github.com/son1112/jot/issues
• Changelog: https://github.com/son1112/jot/blob/main/CHANGELOG.md

Author

Anderson Reinkordt ([e-mail])