jott-cli 0.2.2
Feature-rich interactive CLI task manager with AI integration, calendar sync, and keyword automation
Requires Python: >=3.6
Keywords: cli, task-management, productivity, todo, gtd, ai-integration

# jot - 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.**

[![PyPI version](https://badge.fury.io/py/jott-cli.svg)](https://badge.fury.io/py/jott-cli)
[![Python 3.6+](https://img.shields.io/badge/python-3.6+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 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 `/`
- **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)

```bash
# Basic installation
pip install jott-cli

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

# Verify installation
jott --version
```

### From Source

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

## Quick Start

```bash
# Launch jot 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

**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
- `Shift+I` - Import from Google Calendar
- `Shift+B` - Start priority timer (12-minute focus session)

**Navigation:**
- `↑/↓` or `Ctrl+N/P` - Navigate tasks
- `Shift+↑/↓` - Reorder tasks
- `/` - Fuzzy search mode
- `Shift+V` - Multi-select mode
- `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):

```bash
# Switch to category
Shift+C

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

### Cross-Project Routing

Register projects for quick access:

```bash
# Auto-discover projects in ~/projects/
Shift+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`:

```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:

```json
{
  "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

```bash
# Run all tests
make test

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

# Run linting
make lint
```

### Test Coverage

- 108 tests (all passing)
- 15.83% coverage
- 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](https://github.com/son1112/jot/blob/main/SECURITY.md) for full details.

## Contributing

Contributions welcome! See [CONTRIBUTING.md](https://github.com/son1112/jot/blob/main/CONTRIBUTING.md).

### Development Setup

```bash
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](https://github.com/son1112/jot/blob/main/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

Scott Anderson (sonander@gmail.com)