Metadata-Version: 2.4
Name: jott-cli
Version: 0.8.3
Summary: Feature-rich interactive CLI task manager with AI integration, calendar sync, and keyword automation
Author-email: Scott Anderson <sonander@gmail.com>
Maintainer-email: Scott Anderson <sonander@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/son1112/jot
Project-URL: Repository, https://github.com/son1112/jot
Project-URL: Issues, https://github.com/son1112/jot/issues
Project-URL: Changelog, https://github.com/son1112/jot/blob/main/CHANGELOG.md
Project-URL: Documentation, https://son1112.github.io/jot/
Keywords: cli,task-management,productivity,todo,gtd,ai-integration
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-auth>=2.0.0
Requires-Dist: google-auth-oauthlib>=0.5.0
Requires-Dist: google-auth-httplib2>=0.1.0
Requires-Dist: google-api-python-client>=2.0.0
Requires-Dist: filelock>=3.0.0
Requires-Dist: prompt-toolkit>=3.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: coverage>=7.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: isort>=5.12; extra == "dev"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: tts
Requires-Dist: pyttsx3>=2.90; extra == "tts"
Provides-Extra: docs
Requires-Dist: sphinx<8.0,>=5.0; extra == "docs"
Requires-Dist: furo>=2023.1; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.20; extra == "docs"
Dynamic: license-file

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

[![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)

## TDD: Task-Driven Development

In this house, TDD is Task-Driven Development. The companion idea is JDD, Jott-Driven Design: design the thing by jotting it.

Jot the rough thought first, in whatever form works. A half-sentence, a verb, a "lol". That's the seed.

The seed grows. Notes attach to it. Subtasks split off. An analysis file or a Claude session forms around it. A status color shifts as it moves through review, dev, shipping. Eventually it ships, or it composts.

jott is the tool we use to do this. The methodology came from using it; the name came from the lol.

## 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 via the `analyze:` keyword for task analysis
- **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
- **Leader chord system**: `.` prefix for 20+ shortcuts (e.g., `.m` move, `.n` notes)
- **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 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:**
- `.n` - Edit task notes
- `Ctrl+D` - Delete current task
- `.a` - Toggle archived tasks
- `.f` - Toggle inline notes display
- `.u` - Toggle ALL CAPS
- `Shift+4` - AI-powered task suggestion

**Scheduling:**
- `.w` - Assign day of week
- `.p` - Set priority
- `.x` - Set status

**AI Integration:**
- `analyze:` keyword - Analyze task with Claude Code (plan mode)
- `.j` - Mark as agent task

**Integrations:**
- `Shift+2` - Read tasks aloud (TTS)
- `Shift+3` - Re-authenticate Google Calendar
- `.G` - Export to Google Calendar (single or bulk with time tags)
- `.i` - Import from Google Calendar
- `.b` - Start priority timer (12-minute focus session)

**Navigation & System:**
- `↑/↓` or `Ctrl+N/P` - Navigate tasks
- `Shift+↑/↓` - Reorder tasks
- `Ctrl+F` - Fuzzy search mode
- `.z` - Switch project
- `.l` - Toggle all categories view
- `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):

```bash
# Switch to category
Ctrl+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/
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 `.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

- 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](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

Anderson Reinkordt (anderson.reinkordt+can@gmail.com)
