kasl: Key Activity Synchronization and Logging 🕒

kasl

Overview 📖

kasl is a comprehensive command-line utility designed to streamline work activity tracking, task management, and productivity reporting. It automatically monitors your work sessions, tracks breaks, manages tasks, and generates detailed reports for better productivity insights.

Current Version: 0.8.2

Key Features 🌟

🔍 Activity Monitoring

Automatic work session tracking - Detects when you start and end your workday
Smart break detection - Automatically records breaks based on inactivity
Background monitoring - Runs silently in the background
Cross-platform support - Works on Windows, macOS, and Linux

📋 Task Management

CRUD operations - Create, read, update, and delete tasks
Task templates - Save frequently used tasks as reusable templates
Tagging system - Organize tasks with custom tags and colors
Progress tracking - Track task completion percentage
Batch operations - Edit or delete multiple tasks at once

📊 Reporting & Analytics

Daily reports - Comprehensive view of work intervals and tasks
Monthly summaries - Aggregated statistics and productivity metrics
Productivity calculation - Measure actual work time vs. presence time
Short interval detection - Identify and merge fragmented work periods
Export capabilities - Export data to CSV, JSON, or Excel formats

⚙️ Advanced Features

Time adjustment - Correct work times with preview before applying
Database migrations - Safe schema updates when upgrading
API integrations - Connect with GitLab, Jira, and custom APIs
Autostart support - Start monitoring automatically on system boot
Debug logging - Detailed logs for troubleshooting

Quick Start 🚀

Installation

Install kasl using curl:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/lacodda/kasl/main/tools/install.sh)"

Or using wget:

sh -c "$(wget https://raw.githubusercontent.com/lacodda/kasl/main/tools/install.sh -O -)"

Initial Setup

# Configure kasl interactively
kasl init

# Start activity monitoring
kasl watch

# Enable autostart on system boot
kasl autostart enable

Daily Workflow

# Create a new task
kasl task --name "Review pull requests" --completeness 0

# Update task progress
kasl task --edit 1

# View today's report
kasl report

# Submit daily report
kasl report --send

System Requirements 💻

Operating System: Windows 10+, macOS 10.15+, or Linux
Architecture: x86_64
Memory: 50MB RAM
Storage: 10MB disk space
Network: Optional (for API integrations and updates)

License 📄

This project is licensed under the MIT License - see the LICENSE file for details.

Support 📞

📧 Email: lahtachev@gmail.com
🐛 Issues: GitHub Issues
📖 Documentation: kasl.lacodda.com

Made with ❤️ by Kirill Lakhtachev

Getting Started

This guide will help you get up and running with kasl quickly.

Installation

Quick Install (Recommended)

Install kasl using curl:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/lacodda/kasl/main/tools/install.sh)"

Or using wget:

sh -c "$(wget https://raw.githubusercontent.com/lacodda/kasl/main/tools/install.sh -O -)"

Build from Source

Requirements:

Rust 1.70 or higher
Git

git clone https://github.com/lacodda/kasl.git
cd kasl
cargo build --release
cargo install --path .

Verify Installation

Check that kasl is installed correctly:

kasl --version

Initial Configuration

Interactive Setup

Run the interactive configuration wizard:

kasl init

This will guide you through setting up:

Monitor settings (pause thresholds, activity detection)
API integrations (GitLab, Jira, SiServer)
Server configuration for report submission

Manual Configuration

Configuration files are stored in:

Windows: %LOCALAPPDATA%\lacodda\kasl\config.json
macOS: ~/Library/Application Support/lacodda/kasl/config.json
Linux: ~/.local/share/lacodda/kasl/config.json

Example configuration:

{
  "monitor": {
    "min_pause_duration": 20,
    "pause_threshold": 60,
    "poll_interval": 500,
    "activity_threshold": 30,
    "min_work_interval": 10
  },
  "si": {
    "login": "your.email@company.com",
    "auth_url": "https://auth.company.com",
    "api_url": "https://api.company.com"
  },
  "gitlab": {
    "access_token": "your-token",
    "api_url": "https://gitlab.com"
  },
  "jira": {
    "login": "your.email@company.com",
    "api_url": "https://jira.company.com"
  }
}

First Steps

1. Start Activity Monitoring

Begin tracking your work sessions:

# Start monitoring in the background
kasl watch

# Or run in foreground for debugging
kasl watch --foreground

2. Enable Autostart (Optional)

Configure kasl to start automatically on system boot:

kasl autostart enable

3. Create Your First Task

Add a task to track your work:

kasl task --name "Set up kasl" --completeness 100

4. View Your Report

Check your work summary:

kasl report

Daily Workflow

Morning Routine

Check yesterday's report (if needed):
```
kasl report --last
```

Create today's tasks:

kasl task --name "Code review" --completeness 0
kasl task --name "Team meeting" --completeness 0

Start monitoring (if not already running):
```
kasl watch
```

During the Day

Update task progress:
```
kasl task --edit 1  # Edit task by ID
```

Add new tasks as needed:

kasl task --name "Bug fix" --completeness 0

View current status:
```
kasl task --show  # Show today's tasks
```

End of Day

View today's report:
```
kasl report
```
Submit report (if configured):
```
kasl report --send
```
End workday manually (if needed):
```
kasl end
```

Common Tasks

Task Management

# Create a task
kasl task --name "Task name" --comment "Description" --completeness 0

# List tasks
kasl task --show

# Edit a task
kasl task --edit 1

# Delete a task
kasl task --delete 1

# Use templates
kasl task --from-template

Time Adjustments

# Adjust work start time
kasl adjust --mode start --minutes 30

# Add a pause
kasl adjust --mode pause --minutes 15

# Adjust work end time
kasl adjust --mode end --minutes 20

Data Export

# Export today's data
kasl export --format csv

# Export all data
kasl export all --format json

# Export to specific file
kasl export --output my_report.csv

Monthly Summary

# View monthly summary
kasl sum

# Submit monthly report
kasl sum --send

Troubleshooting

Check if Monitoring is Running

kasl watch --stop  # Stop any running instances
kasl watch --foreground  # Start in foreground to see logs

Debug Mode

Enable debug logging:

KASL_DEBUG=1 kasl watch --foreground

Reset Configuration

If you need to start over:

kasl init --delete

Next Steps

Read the Features guide to learn about advanced capabilities
Explore API Integrations for external service connections
Check the Configuration guide for detailed settings
Review Commands for complete command reference

Features

kasl provides comprehensive work activity tracking and task management capabilities. This guide covers all major features and their usage.

🔍 Activity Monitoring

Automatic Work Session Detection

kasl automatically detects when you start and end your workday based on your activity patterns:

Activity Threshold: Configurable duration of continuous activity required to start a workday
Smart Detection: Distinguishes between brief interactions and actual work sessions
Background Operation: Runs silently without interrupting your workflow

Break Detection

Intelligent pause detection that adapts to your work patterns:

Inactivity Threshold: Configurable time before a pause is detected
Minimum Pause Duration: Only records breaks longer than the specified duration
Automatic Resume: Detects when you return to work and resumes tracking

Configuration Options

{
  "monitor": {
    "min_pause_duration": 20,    // Minutes - minimum break to record
    "pause_threshold": 60,       // Seconds - inactivity before pause
    "poll_interval": 500,        // Milliseconds - activity check interval
    "activity_threshold": 30,    // Seconds - activity before workday start
    "min_work_interval": 10      // Minutes - minimum work interval
  }
}

🎯 Productivity Optimization

Manual Break Management

Strategic break placement for productivity improvement:

Automatic Placement: Optimal break positioning using intelligent algorithms
Interactive Mode: User-guided break creation with multiple placement options
Productivity Validation: Ensures breaks improve metrics effectively
Conflict Prevention: Avoids overlaps with existing pauses

Break Placement Strategies

# Automatic optimal placement
kasl breaks -m 30

# Interactive placement selection
kasl breaks

Placement Algorithms:

Middle of Longest Work Period: Splits extended work sessions
After Existing Pauses: Extends natural break periods
Before Existing Pauses: Creates preparation time

Productivity Metrics

Real-time productivity tracking and validation:

Threshold Validation: Configurable minimum productivity for report submission
Break Recommendations: Suggests break duration to reach targets
Progress Tracking: Shows productivity impact of added breaks
Report Integration: Blocks low-productivity report submission

Configuration

{
  "productivity": {
    "min_productivity_threshold": 75.0,
    "workday_hours": 8.0,
    "min_break_duration": 20,
    "max_break_duration": 180,
    "min_workday_fraction_before_suggest": 0.5
  }
}

Key Features:

Smart Recommendations: Only suggests breaks when meaningful
Validation Safeguards: Prevents invalid break placement
Progress Feedback: Shows real-time productivity improvements
Report Quality: Ensures only high-quality reports are submitted

📋 Task Management

CRUD Operations

Complete task lifecycle management:

# Create tasks
kasl task --name "Review PR" --comment "Security review" --completeness 0

# Read tasks
kasl task --show
kasl task --show --all  # Show all tasks, not just today's

# Update tasks
kasl task --edit 1  # Interactive editing
kasl task --edit-interactive  # Edit multiple tasks

# Delete tasks
kasl task --delete 1
kasl task --delete-today  # Delete all today's tasks

Task Templates

Save frequently used tasks as reusable templates:

# Create a template
kasl template create --name "daily-standup"

# Use a template
kasl task --from-template
kasl task --template "daily-standup"

Tagging System

Organize tasks with custom tags and colors:

# Create tags
kasl tag create --name "urgent" --color "red"
kasl tag create --name "backend" --color "blue"

# Assign tags to tasks
kasl task --name "Fix bug" --tags "urgent,backend"

# Filter by tags
kasl task --show --tag "urgent"

Progress Tracking

Track task completion with percentage-based progress:

0%: Not started
1-99%: In progress
100%: Completed

kasl task --name "Feature implementation" --completeness 25
kasl task --edit 1  # Update progress interactively

📊 Reporting & Analytics

Daily Reports

Comprehensive daily work summaries:

# View today's report
kasl report

# View yesterday's report
kasl report --last

# Submit report to configured API
kasl report --send

Report includes:

Work intervals with precise timing
Break periods and durations
Task completion status
Productivity metrics
Total work hours

Monthly Summaries

Aggregated monthly statistics:

# View monthly summary
kasl sum

# Submit monthly report
kasl sum --send

Features:

Daily work hour totals
Average daily hours
Productivity trends
Working day count
Rest day integration

Productivity Metrics

Calculate and track productivity:

Gross Time: Total time from start to end
Net Time: Actual work time minus breaks
Productivity Percentage: Net time / Gross time
Break Analysis: Break frequency and duration patterns

Short Interval Filtering

Automatically filter out brief work periods for cleaner reporting:

Automatic Detection: Short intervals are filtered based on min_work_interval configuration
Display-Level Filtering: Original data remains intact in the database
Consistent Behavior: Same filtering applies to both display and API submission
User Notification: Information about filtered intervals is shown in reports

# Reports automatically filter short intervals
kasl report

# Configuration controls the filtering threshold
# (set via min_work_interval in monitor config)

⚙️ Advanced Features

Time Adjustments

Correct work times with preview before applying:

# Adjust work start time
kasl adjust --mode start --minutes 30 --date 2025-01-15

# Add a pause
kasl adjust --mode pause --minutes 15 --date 2025-01-15

# Adjust work end time
kasl adjust --mode end --minutes 20 --date 2025-01-15

Features:

Preview changes before applying
Multiple adjustment modes
Date-specific adjustments
Force mode for immediate application

Data Export

Export data in multiple formats:

# Export to CSV
kasl export --format csv --output report.csv

# Export to JSON
kasl export --format json --output data.json

# Export to Excel
kasl export --format excel --output report.xlsx

# Export all data
kasl export all --format json

Supported formats:

CSV: Universal compatibility
JSON: Structured data
Excel: Formatted reports with multiple sheets

Database Management

Safe database operations:

# View migration status (debug builds only)
kasl migrations status

# View migration history (debug builds only)
kasl migrations history

Features:

Automatic schema migrations
Safe database updates
Migration history tracking
Rollback capabilities (debug builds)

🔗 API Integrations

GitLab Integration

Import commits as completed tasks:

# Configure GitLab
kasl init  # Interactive setup

# Find tasks from GitLab
kasl task --find

Features:

Automatic commit import
User activity tracking
Repository-specific filtering
Commit message parsing

Jira Integration

Import completed issues:

# Configure Jira
kasl init  # Interactive setup

# Find tasks from Jira
kasl task --find

Features:

Issue status tracking
Automatic completion detection
Custom field mapping
Project-specific filtering

SiServer Integration

Submit reports to internal systems:

# Configure SiServer
kasl init  # Interactive setup

# Submit daily report
kasl report --send

# Submit monthly report
kasl sum --send

Features:

Secure authentication
Report formatting
Error handling
Retry logic

🚀 System Integration

Autostart Support

Configure automatic startup:

# Enable autostart
kasl autostart enable

# Check status
kasl autostart status

# Disable autostart
kasl autostart disable

Platform support:

Windows: Task Scheduler and Registry
macOS: LaunchAgent (planned)
Linux: systemd user service (planned)

Background Monitoring

Silent background operation:

# Start background monitoring
kasl watch

# Stop monitoring
kasl watch --stop

# Check if running
kasl watch --status

Features:

Daemon process management
Automatic restart on failure
Resource optimization
Signal handling

Debug Logging

Comprehensive debugging capabilities:

# Enable debug mode
KASL_DEBUG=1 kasl watch --foreground

# Use Rust logging
RUST_LOG=kasl=debug kasl report

# Trace level logging
RUST_LOG=kasl=trace kasl watch

Log levels:

Error: Critical issues
Warn: Important warnings
Info: General information
Debug: Detailed debugging
Trace: Maximum verbosity

📱 Cross-Platform Support

Operating Systems

Windows 10+: Full native support
macOS 10.15+: Full native support
Linux: Full native support

Architecture Support

x86_64: Primary target
ARM64: Planned support

Installation Methods

Binary releases: Pre-compiled executables
Package managers: Platform-specific packages
Source compilation: From Rust source code

🔒 Security Features

Data Protection

Local storage: All data stored locally
Encrypted credentials: API tokens encrypted at rest
Session management: Secure session handling
Permission isolation: Minimal system permissions

Privacy

No telemetry: No data sent without explicit consent
Local processing: All analysis done locally
Configurable sharing: Control over data export
Audit trails: Complete operation logging

📈 Performance

Resource Usage

Memory: ~50MB RAM
CPU: Minimal background usage
Storage: ~10MB application + data
Network: Optional API calls only

Optimization

Efficient polling: Configurable activity check intervals
Database optimization: Indexed queries and transactions
Memory management: Automatic cleanup and garbage collection
Background processing: Non-blocking operations

Configuration

kasl uses a JSON configuration file to store all application settings. This guide covers all configuration options and their usage.

Configuration File Location

Configuration files are stored in platform-specific locations:

Windows: %LOCALAPPDATA%\lacodda\kasl\config.json
macOS: ~/Library/Application Support/lacodda/kasl/config.json
Linux: ~/.local/share/lacodda/kasl/config.json

Configuration Structure

{
  "monitor": {
    "min_pause_duration": 20,
    "pause_threshold": 60,
    "poll_interval": 500,
    "activity_threshold": 30,
    "min_work_interval": 10
  },
  "si": {
    "login": "your.email@company.com",
    "auth_url": "https://auth.company.com",
    "api_url": "https://api.company.com"
  },
  "gitlab": {
    "access_token": "your-token",
    "api_url": "https://gitlab.com"
  },
  "jira": {
    "login": "your.email@company.com",
    "api_url": "https://jira.company.com"
  },
  "server": {
    "api_url": "https://api.company.com/timetracking",
    "auth_token": "your-api-token"
  },
  "productivity": {
    "min_productivity_threshold": 75.0,
    "workday_hours": 8.0,
    "min_break_duration": 20,
    "max_break_duration": 180,
    "min_workday_fraction_before_suggest": 0.5
  }
}

Monitor Configuration

Controls activity monitoring behavior:

`min_pause_duration`

Type: u64
Default: 20
Unit: Minutes
Description: Minimum break duration to record in the database
Usage: Pauses shorter than this threshold are ignored

`pause_threshold`

Type: u64
Default: 60
Unit: Seconds
Description: Inactivity duration before a pause is detected
Usage: Time without keyboard/mouse activity to trigger pause

`poll_interval`

Type: u64
Default: 500
Unit: Milliseconds
Description: Frequency of activity status checks
Usage: Lower values = more responsive, higher CPU usage

`activity_threshold`

Type: u64
Default: 30
Unit: Seconds
Description: Continuous activity required to start a workday
Usage: Prevents false starts from brief interactions

`min_work_interval`

Type: u64
Default: 10
Unit: Minutes
Description: Minimum work interval duration for report filtering
Usage: Intervals shorter than this duration are automatically filtered out from reports (display and API submission)

SiServer Configuration

Internal company API integration:

Type: String
Description: Corporate username for LDAP authentication
Example: "john.doe@company.com"

`auth_url`

Type: String
Description: Authentication endpoint URL
Example: "https://auth.company.com"

`api_url`

Type: String
Description: Main API endpoint URL
Example: "https://api.company.com"

GitLab Configuration

GitLab API integration for commit tracking:

`access_token`

Type: String
Description: Personal Access Token with required scopes
Required Scopes: read_user, read_repository
Generation: GitLab → User Settings → Access Tokens

`api_url`

Type: String
Description: GitLab instance base URL
Examples:
- "https://gitlab.com" (GitLab.com)
- "https://gitlab.company.com" (Self-hosted)

Jira Configuration

Jira API integration for issue tracking:

Type: String
Description: Jira username (not email unless configured)
Note: Check with Jira administrator for username format

`api_url`

Type: String
Description: Jira instance base URL
Examples:
- "https://company.atlassian.net" (Atlassian Cloud)
- "https://jira.company.com" (Server/Data Center)

Server Configuration

External reporting API configuration:

`api_url`

Type: String
Description: Base URL for report submission
Example: "https://api.company.com/timetracking"

`auth_token`

Type: String
Description: Authentication token for API access
Format: Depends on API requirements (Bearer, API key, etc.)

Productivity Configuration

Controls productivity tracking and break management:

`min_productivity_threshold`

Type: f64
Default: 75.0
Description: Minimum productivity percentage required for report submission
Range: 0.0 to 100.0
Usage: Reports with productivity below this threshold will be blocked until breaks are added

`workday_hours`

Type: f64
Default: 8.0
Description: Expected daily work hours for productivity calculations
Range: 1.0 to 24.0
Usage: Used to calculate available work time for productivity metrics

`min_break_duration`

Type: u64
Default: 20
Description: Minimum allowed break duration in minutes
Range: 1 to 480
Usage: Prevents creation of breaks shorter than this duration

`max_break_duration`

Type: u64
Default: 180
Description: Maximum allowed break duration in minutes
Range: 1 to 480
Usage: Prevents creation of breaks longer than this duration

`min_workday_fraction_before_suggest`

Type: f64
Default: 0.5
Description: Fraction of workday that must pass before showing productivity suggestions
Range: 0.0 to 1.0
Usage: Prevents early recommendations when insufficient work time has elapsed

Example Configuration:

{
  "productivity": {
    "min_productivity_threshold": 75.0,
    "workday_hours": 8.0,
    "min_break_duration": 20,
    "max_break_duration": 180,
    "min_workday_fraction_before_suggest": 0.5
  }
}

Interactive Configuration

Initial Setup

Run the interactive configuration wizard:

kasl init

This guides you through:

Monitor settings configuration
API integration setup
Server configuration
Credential management

Configuration Reset

Remove existing configuration:

kasl init --delete

This will:

Delete the configuration file
Remove global PATH settings
Reset to initial state

Manual Configuration

Creating Configuration File

Create the configuration directory and file:

# Windows
mkdir "%LOCALAPPDATA%\lacodda\kasl"

# macOS/Linux
mkdir -p ~/.local/share/lacodda/kasl

Example Configuration

{
  "monitor": {
    "min_pause_duration": 15,
    "pause_threshold": 45,
    "poll_interval": 1000,
    "activity_threshold": 60,
    "min_work_interval": 5
  },
  "gitlab": {
    "access_token": "glpat-XXXXXXXXXXXXXXXXXXXX",
    "api_url": "https://gitlab.com"
  },
  "jira": {
    "login": "john.doe",
    "api_url": "https://company.atlassian.net"
  }
}

Configuration Validation

Syntax Check

Validate JSON syntax:

# Using jq (if available)
jq . config.json

# Using Python
python -m json.tool config.json

Runtime Validation

kasl validates configuration on startup:

kasl watch --foreground

Common validation errors:

Invalid JSON syntax
Missing required fields
Invalid URL formats
Unsupported configuration values

Security Considerations

Credential Storage

API Tokens: Stored encrypted in separate files
Passwords: Prompted interactively, not stored
Session Data: Cached temporarily for performance

File Permissions

Ensure proper file permissions:

# Linux/macOS
chmod 600 ~/.local/share/lacodda/kasl/config.json
chmod 700 ~/.local/share/lacodda/kasl/

Environment Variables

Override configuration with environment variables:

# Override monitor settings
export KASL_MIN_PAUSE_DURATION=30
export KASL_PAUSE_THRESHOLD=90

# Override API URLs
export KASL_GITLAB_API_URL=https://gitlab.company.com
export KASL_JIRA_API_URL=https://jira.company.com

Troubleshooting

Configuration Issues

Problem: Configuration not found

# Check if file exists
ls ~/.local/share/lacodda/kasl/config.json

# Recreate configuration
kasl init

Problem: Invalid configuration

# Validate JSON syntax
python -m json.tool config.json

# Check for missing fields
kasl watch --foreground

Problem: API connection failures

# Test API connectivity
curl -H "Authorization: Bearer YOUR_TOKEN" https://api.company.com/health

# Check network settings
ping api.company.com

Debug Configuration

Enable debug logging to see configuration loading:

RUST_LOG=kasl=debug kasl watch --foreground

This will show:

Configuration file location
Loaded configuration values
Validation results
API connection attempts

Commands

kasl provides a comprehensive set of commands for work activity tracking, task management, and reporting.

Command Overview

Core Commands

init - Initialize application configuration
watch - Start activity monitoring
task - Manage tasks and work items
report - Generate and submit reports
sum - View monthly summaries

Data Management

export - Export data to various formats
breaks - Add manual breaks for productivity optimization
pauses - View recorded breaks and pauses

Organization

tag - Manage task tags and categorization
template - Create and use task templates

System Integration

autostart - Configure automatic startup
update - Update application to latest version

Quick Reference

Daily Workflow

# Start monitoring (if not already running)
kasl watch

# Create today's tasks
kasl task --name "Code review" --completeness 0
kasl task --name "Team meeting" --completeness 0

# Update task progress
kasl task --edit 1

# View today's report
kasl report

# Submit report (if configured)
kasl report --send

Task Management

# Create tasks
kasl task --name "Task name" --comment "Description" --completeness 0

# List tasks
kasl task --show
kasl task --show --all

# Edit tasks
kasl task --edit 1
kasl task --edit-interactive

# Delete tasks
kasl task --delete 1 2 3
kasl task --delete-today

Productivity Optimization

# Add strategic break for productivity
kasl breaks -m 30

# Interactive break placement
kasl breaks

# Force break creation
kasl breaks -m 45 --force

Data Export

# Export today's data
kasl export --format csv

# Export all data
kasl export all --format json

# Export to specific file
kasl export --output my_report.csv

Tag Management

# Create tags
kasl tag create --name "urgent" --color "red"
kasl tag create --name "backend" --color "blue"

# List tags
kasl tag list

# Assign tags to tasks
kasl task --name "Fix bug" --tags "urgent,backend"

# Filter by tags
kasl task --show --tag "urgent"

Templates

# Create template
kasl template create --name "daily-standup"

# Use template
kasl task --from-template
kasl task --template "daily-standup"

Command Categories

Activity Monitoring

Commands for tracking work sessions and activity:

watch - Core monitoring functionality
breaks - Strategic break placement for productivity
pauses - View recorded breaks and pauses

Task Management

Commands for organizing and tracking work items:

task - Complete task lifecycle management
tag - Task categorization and organization
template - Reusable task templates

Reporting & Analytics

Commands for generating insights and reports:

report - Daily work reports
sum - Monthly summaries and statistics
export - Data export for external analysis

System Management

Commands for application configuration and maintenance:

init - Initial setup and configuration
autostart - System integration
update - Application updates

Getting Help

Command Help

Get help for any command:

kasl --help
kasl <command> --help

Examples

View command examples:

# Show all available commands
kasl --help

# Show specific command help
kasl task --help
kasl report --help

Interactive Mode

Some commands support interactive mode:

# Interactive task creation
kasl task

# Interactive template selection
kasl task --from-template

# Interactive task editing
kasl task --edit-interactive

Command Options

Global Options

Most commands support these global options:

--help - Show command help
--version - Show version information

Common Options

Many commands support these common options:

--date - Specify date (YYYY-MM-DD or 'today')
--output - Specify output file
--format - Specify output format

Debug Options

Debug options for troubleshooting:

--foreground - Run in foreground mode
--debug - Enable debug logging

Best Practices

Command Organization

Use templates for frequently created tasks
Use tags for task categorization
Regular exports for data backup
Monitor configuration for optimal detection

Workflow Integration

Start monitoring at the beginning of your workday
Create tasks as you plan your work
Update progress throughout the day
Review reports at the end of the day

Data Management

Regular backups using export functionality
Clean up old data periodically
Validate data using report commands
Monitor database size and performance

`init` - Initialize Application Configuration

The init command sets up kasl configuration interactively, guiding you through the initial setup process.

Usage

kasl init [OPTIONS]

Options

Option	Description
`-d, --delete`	Remove existing configuration instead of creating new one
`-h, --help`	Print help information

Description

The init command provides an interactive configuration wizard that guides you through setting up:

Monitor Settings: Activity detection thresholds and timing
API Integrations: GitLab, Jira, and SiServer connections
Server Configuration: External reporting endpoints
Credential Management: Secure storage setup

Interactive Setup

Monitor Configuration

Configure activity monitoring behavior:

Minimum pause duration (minutes) [20]: 
Pause threshold (seconds) [60]: 
Poll interval (milliseconds) [500]: 
Activity threshold (seconds) [30]: 
Minimum work interval (minutes) [10]:

Settings Explained:

Minimum pause duration: Breaks shorter than this are ignored
Pause threshold: Time without activity before pause detection
Poll interval: How often to check for activity
Activity threshold: Continuous activity needed to start workday
Minimum work interval: Short intervals to merge

API Integrations

Configure external service connections:

GitLab Integration

Enable GitLab integration? (y/N): y
GitLab API URL [https://gitlab.com]: 
GitLab Access Token:

Jira Integration

Enable Jira integration? (y/N): y
Jira API URL: 
Jira Username:

SiServer Integration

Enable SiServer integration? (y/N): y
SiServer Auth URL: 
SiServer API URL: 
SiServer Username:

Server Configuration

Configure external reporting:

Enable external reporting? (y/N): y
Server API URL: 
Authentication Token:

Configuration Reset

Remove existing configuration:

kasl init --delete

This will:

Delete the configuration file
Remove global PATH settings
Reset to initial state

Configuration File Location

Configuration is stored in platform-specific locations:

Windows: %LOCALAPPDATA%\lacodda\kasl\config.json
macOS: ~/Library/Application Support/lacodda/kasl/config.json
Linux: ~/.local/share/lacodda/kasl/config.json

Example Configuration

After running init, your configuration will look like:

{
  "monitor": {
    "min_pause_duration": 20,
    "pause_threshold": 60,
    "poll_interval": 500,
    "activity_threshold": 30,
    "min_work_interval": 10
  },
  "gitlab": {
    "access_token": "glpat-XXXXXXXXXXXXXXXXXXXX",
    "api_url": "https://gitlab.com"
  },
  "jira": {
    "login": "john.doe",
    "api_url": "https://company.atlassian.net"
  },
  "si": {
    "login": "john.doe@company.com",
    "auth_url": "https://auth.company.com",
    "api_url": "https://api.company.com"
  },
  "server": {
    "api_url": "https://api.company.com/timetracking",
    "auth_token": "your-api-token"
  }
}

Credential Management

Secure Storage

Credentials are stored securely:

API Tokens: Encrypted in separate files
Passwords: Prompted interactively, not stored
Session Data: Cached temporarily

File Permissions

Ensure proper file permissions:

# Linux/macOS
chmod 600 ~/.local/share/lacodda/kasl/config.json
chmod 700 ~/.local/share/lacodda/kasl/

Troubleshooting

Configuration Issues

Problem: Configuration not saved

# Check file permissions
ls -la ~/.local/share/lacodda/kasl/config.json

# Recreate configuration
kasl init --delete
kasl init

Problem: Invalid configuration

# Validate JSON syntax
python -m json.tool ~/.local/share/lacodda/kasl/config.json

# Reset configuration
kasl init --delete
kasl init

API Configuration Issues

Problem: API connection failures

# Test connectivity
curl -H "Authorization: Bearer YOUR_TOKEN" https://gitlab.com/api/v4/user

# Reconfigure integration
kasl init

Examples

Basic Setup

# Run interactive setup
kasl init

# Follow prompts to configure:
# 1. Monitor settings
# 2. API integrations (optional)
# 3. Server configuration (optional)

Reset Configuration

# Remove existing configuration
kasl init --delete

# Run setup again
kasl init

Partial Configuration

# Run setup and skip optional integrations
kasl init

# Only configure monitor settings
# Skip GitLab, Jira, and SiServer when prompted

Next Steps

After running init:

Start monitoring:
```
kasl watch
```
Enable autostart (optional):
```
kasl autostart enable
```

Create your first task:

kasl task --name "Set up kasl" --completeness 100

View your report:
```
kasl report
```

watch - Start activity monitoring
task - Manage tasks
report - Generate reports
autostart - Configure automatic startup

`watch` Command

The watch command is the core monitoring functionality of kasl. It tracks user activity to automatically detect work sessions, breaks, and workday boundaries. The command can run in background daemon mode for daily use or in foreground mode for debugging and development.

Usage

kasl watch [OPTIONS]

Options

--foreground: Run the watcher in the foreground for debugging
- Provides real-time feedback about detected activity
- Shows pause events and workday state changes
- Useful for testing configuration changes and troubleshooting
--stop, -s: Stop any running background watcher process
- Terminates the background daemon if it's currently running
- Safely closes database connections and cleans up system resources
- Useful before system shutdown or when restarting with new configuration

Operating Modes

Background Daemon Mode (Default)

kasl watch

Runs silently in the background, perfect for daily use:

Automatically starts monitoring when you begin working
Detects work vs. break periods based on configurable thresholds
Records workday start/end times and pause periods
Maintains activity state across application restarts

Foreground Debug Mode

kasl watch --foreground

Runs in the terminal with detailed logging:

Real-time activity detection feedback
Pause event notifications
Workday state change logging
Configuration testing and validation

Stop Mode

kasl watch --stop

Terminates background monitoring:

Stops any running daemon process
Properly closes database connections
Cleans up system resources

How It Works

Activity Detection

The monitor tracks these input events:

Keyboard presses and releases
Mouse button clicks
Mouse movement
Mouse wheel scrolling

Work Session Detection

Input Detection: Monitors keyboard and mouse activity using system APIs
Activity Analysis: Determines work vs. break periods based on configurable thresholds
Database Recording: Automatically records workday start/end times and pause periods
State Management: Maintains activity state across application restarts

Configuration Settings

The monitor behavior is controlled by configuration settings:

pause_threshold: Seconds of inactivity before recording a pause
poll_interval: Milliseconds between activity checks
activity_threshold: Seconds of activity needed to start a workday
min_pause_duration: Minimum pause length to record (filters noise)

Examples

Daily Usage

# Start background monitoring (recommended for daily use)
kasl watch

# Check if monitoring is running
ps aux | grep kasl

Debugging and Development

# Run in foreground to see activity detection in real-time
kasl watch --foreground

# Test configuration changes
kasl watch --foreground
# Press Ctrl+C to stop

System Management

# Stop monitoring before system shutdown
kasl watch --stop

# Restart with new configuration
kasl watch --stop
kasl watch

Database Operations

During monitoring, the system automatically:

Creates workday records when sustained activity is detected
Records pause start times when inactivity threshold is exceeded
Records pause end times when activity resumes
Updates workday end times when monitoring stops

Signal Handling

The daemon process responds to these signals:

SIGTERM: Graceful shutdown (Unix)
SIGINT: Interrupt signal (Unix)
Ctrl+C: Console interrupt (Windows)

Troubleshooting

Common Issues

Daemon already running

# Check if daemon is running
ps aux | grep kasl

# Stop existing daemon
kasl watch --stop

# Start new daemon
kasl watch

Permission issues

# Run with elevated permissions if needed
sudo kasl watch --foreground

Configuration errors

# Test configuration in foreground mode
kasl watch --foreground

Debug Mode

Enable debug logging for troubleshooting:

RUST_LOG=kasl=debug kasl watch --foreground

Process Management

# Check daemon status
ps aux | grep kasl

# View daemon logs (if configured)
tail -f ~/.local/share/lacodda/kasl/kasl.log

# Force stop daemon (if needed)
pkill -f kasl

Integration with Other Commands

The watch command works with other kasl commands:

task: Create and manage tasks while monitoring
report: Generate reports based on monitored data
adjust: Manually adjust times recorded by monitoring
pauses: View recorded breaks and pauses

Best Practices

Daily Workflow

Start monitoring at the beginning of your workday
Let it run in the background during work
Stop monitoring before system shutdown
Review data using report and pauses commands

Configuration

Adjust thresholds based on your work patterns
Test settings using foreground mode
Monitor performance and adjust as needed
Backup configuration regularly

Troubleshooting

Use foreground mode for debugging
Check system permissions for input device access
Verify database connectivity
Review logs for error messages

task - Manage tasks and work items
report - Generate work reports
adjust - Adjust recorded times
pauses - View recorded breaks
init - Configure monitoring settings

`task` Command

The task command provides comprehensive task management functionality in kasl, including creating, displaying, updating, and organizing tasks. It supports various operations through command-line options and interactive interfaces, providing flexibility in how tasks are handled within the application.

Usage

kasl task [OPTIONS]

Options

Task Creation and Editing

-n, --name <NAME>: Specifies the name of the task
- Used for creating a new task or updating an existing one
- Required for task creation
-c, --comment <COMMENT>: Adds a comment to the task
- Optional additional information about the task
- Useful for detailed task descriptions
-p, --completeness <COMPLETENESS>: Indicates the completeness of the task as a percentage (0-100)
- Used to update the task's progress
- 0% = not started, 100% = completed
--tags <TAGS>: Assign tags to the task
- Comma-separated list of tags for categorization
- Tags are automatically created if they don't exist

Task Display and Filtering

-s, --show: Displays tasks based on the specified filter
- Without additional filtering options, defaults to showing today's tasks
-a, --all: When used with --show, displays all tasks
- Overrides the default filter of today's tasks
-i, --id <ID>: Specifies one or more task IDs
- When used with --show, filters the displayed tasks to those with the given IDs
--tag <TAG>: Filter tasks by tag
- Shows only tasks with the specified tag
- Can be combined with other filters

Interactive Operations

-f, --find: Finds and allows the user to update incomplete tasks
- Triggers a user interface for selecting incomplete tasks and updating their completeness
--edit <ID>: Edit a specific task by ID
- Opens interactive editor for the specified task
--edit-interactive: Edit tasks interactively
- Shows list of tasks to choose from for editing
--from-template: Create task from template
- Shows available templates to choose from
--template <TEMPLATE>: Use specific template for task creation
- Creates task using the specified template

Task Management

--delete <IDS>: Delete tasks by ID
- Accepts multiple task IDs separated by spaces
--delete-today: Delete all tasks for today
- Removes all tasks created today
--delete-all: Delete all tasks
- Removes all tasks from the database (use with caution)

Examples

Basic Task Operations

# Create a new task
kasl task --name "New Task" --comment "This is a test task" --completeness 50

# Create task with tags
kasl task --name "Fix bug" --tags "urgent,backend" --completeness 0

# Display today's tasks
kasl task --show

# Display all tasks
kasl task --show --all

# Display tasks with specific tag
kasl task --show --tag "urgent"

Interactive Operations

# Find and update incomplete tasks
kasl task --find

# Edit specific task
kasl task --edit 1

# Edit tasks interactively
kasl task --edit-interactive

# Create task from template
kasl task --from-template

# Use specific template
kasl task --template "daily-standup"

Task Management

# Update task completeness
kasl task --edit 1 --completeness 75

# Delete specific tasks
kasl task --delete 1 2 3

# Delete all today's tasks
kasl task --delete-today

# Delete all tasks (use with caution)
kasl task --delete-all

Use Cases

Daily Task Management

# Create today's tasks
kasl task --name "Daily standup" --template "daily-standup"
kasl task --name "Code review" --tags "urgent,backend"
kasl task --name "Team meeting" --tags "meeting"

# Review and update progress
kasl task --show
kasl task --find

# Complete finished tasks
kasl task --edit 1 --completeness 100

Project Organization

# Create project-specific tasks
kasl task --name "Frontend bug fix" --tags "frontend,bug,urgent"
kasl task --name "API documentation" --tags "backend,documentation"

# Filter by project
kasl task --show --tag "frontend"
kasl task --show --tag "backend"

Template Usage

# Create templates for common tasks
kasl template create --name "bug-fix"
kasl template create --name "meeting"

# Use templates to create tasks
kasl task --template "bug-fix" --name "Fix login issue"
kasl task --template "meeting" --name "Client call"

Sample Output

Task List

+---+----+----------+------------------+------------------+-------------+------------------+
| # | ID | TASK ID | NAME             | COMMENT          | COMPLETENESS| TAGS             |
+---+----+----------+------------------+------------------+-------------+------------------+
| 1 | 1  | 0       | Daily standup    | Team sync        | 100%        | meeting          |
| 2 | 2  | 0       | Code review      | Review PR #123   | 75%         | urgent           |
| 3 | 3  | 0       | Bug fix          | Fix login issue  | 0%          | bug, urgent      |
| 4 | 4  | 0       | Documentation    | Update API docs  | 25%         | docs             |
+---+----+----------+------------------+------------------+-------------+------------------+

Interactive Task Selection

Select task to edit:
1. Daily standup (100%)
2. Code review (75%)
3. Bug fix (0%)
4. Documentation (25%)

Enter task number: 2

Editing task: Code review
Current completeness: 75%

New completeness (0-100): 100
New comment (press Enter to keep current): Review completed

✅ Task updated successfully!

Integration with Other Commands

The task command works with other kasl commands:

tag: Create and manage tags for task categorization
template: Use templates for quick task creation
report: View tasks in daily and monthly reports
export: Export task data for external analysis

Best Practices

Task Organization

Use descriptive names: Clear, specific task names
Add helpful comments: Detailed descriptions for complex tasks
Use tags consistently: Establish tag conventions for your projects
Update progress regularly: Keep task completeness current

Workflow Integration

Create tasks at the start: Plan your day with task creation
Use templates: Save time with reusable task templates
Review regularly: Check task status throughout the day
Complete tasks promptly: Mark tasks as done when finished

Data Management

Regular cleanup: Delete completed tasks periodically
Use filters: Leverage tag and date filters for organization
Backup data: Export tasks before major cleanup operations
Monitor patterns: Review task completion patterns for insights

tag - Manage tags for task categorization
template - Create and use task templates
report - View tasks in work reports
export - Export task data for analysis

`report` Command

The report command generates comprehensive daily work reports with detailed information about work sessions, breaks, productivity metrics, and completed tasks. It also supports automatic report submission to external systems and monthly summary generation.

Usage

kasl report [OPTIONS]

Options

--send: Submit the generated daily report to configured API
- Automatically submits the report to the configured reporting service (typically SiServer)
- Enables integration with organizational time tracking systems
- Useful for compliance and organizational reporting requirements
--last, -l: Generate report for the previous day instead of today
- Useful for submitting yesterday's report in the morning
- Reviewing completed work sessions
- Batch processing of historical reports
--month: Submit monthly summary report to configured API
- Generates and submits an aggregate monthly report
- Contains summary statistics and total work hours
- Typically used for organizational reporting requirements at month-end

Examples

Basic Report Generation

# Generate and display today's report
kasl report

# Generate report for yesterday
kasl report --last

# Generate and send today's report
kasl report --send

Advanced Reporting

# Submit monthly summary report
kasl report --month

# Generate yesterday's report and send it
kasl report --last --send

Report Analysis

# Review today's work without sending
kasl report

# Check yesterday's productivity
kasl report --last

Report Components

Daily Report Structure

The daily report includes:

Work Session Summary
- Start and end times
- Total work duration
- Productivity percentage
- Break periods
Task Completion
- List of completed tasks
- Task completion percentages
- Task descriptions and comments
Productivity Metrics
- Net working time vs. gross time
- Break analysis
- Efficiency calculations
Time Intervals
- Detailed work periods (short intervals automatically filtered out)
- Break periods
- Activity patterns
- Information about filtered short intervals

Monthly Report Structure

Monthly reports include:

Aggregate Statistics
- Total work hours for the month
- Average daily hours
- Overall productivity percentage
Daily Breakdown
- Each workday with hours and productivity
- Rest days with default hours
- Missing days identification
Trend Analysis
- Productivity trends
- Work pattern analysis
- Performance insights

Short Interval Filtering

The report command automatically filters out work intervals that are shorter than the configured min_work_interval threshold. This filtering provides cleaner, more meaningful reports by removing brief interruptions that don't represent significant work periods.

How It Works

Automatic Detection: Work intervals are analyzed based on the min_work_interval configuration setting
Display Filtering: Short intervals are filtered at display time - no database modifications are made
Consistent Application: Same filtering logic applies to both local display (kasl report) and API submission (kasl report --send)
User Notification: When short intervals are filtered, users receive information about how many were filtered and their total duration

Configuration

The filtering threshold is controlled by the min_work_interval setting in your configuration:

{
  "monitor": {
    "min_work_interval": 30
  }
}

This setting defines the minimum duration (in minutes) for intervals to be included in reports.

Benefits

Cleaner Reports: Eliminates noise from brief interruptions
Better Analytics: Focus on meaningful work periods
Preserved Data: Original data remains intact in the database
Consistent Behavior: Same filtering for display and API submission

Sample Output

Daily Report

December 15, 2024

+--------------+-------+-------+----------+
| ID           | START | END   | DURATION |
+--------------+-------+-------+----------+
| 1            | 09:00 | 12:00 | 03:00    |
| 2            | 13:00 | 15:30 | 02:30    |
| 3            | 15:45 | 17:30 | 01:45    |
|              |       |       |          |
| TOTAL        |       |       | 07:15    |
| PRODUCTIVITY |       |       | 92.0%    |
+--------------+-------+-------+----------+

Tasks

+---+----+----------+------------------+------------------+-------------+------------------+
| # | ID | TASK ID | NAME             | COMMENT          | COMPLETENESS| TAGS             |
+---+----+----------+------------------+------------------+-------------+------------------+
| 1 | 1  | 0       | Daily standup    | Team sync        | 100%        | meeting          |
| 2 | 2  | 0       | Code review      | Review PR #123   | 100%        | urgent           |
| 3 | 3  | 0       | Bug fix          | Fix login issue  | 75%         | bug, urgent      |
| 4 | 4  | 0       | Documentation    | Update API docs  | 25%         | docs             |
+---+----+----------+------------------+------------------+-------------+------------------+

Filtered out 2 short intervals (total: 0:15)

Monthly Report

December 2024

+------------+----------+-------------+
| DATE       | DURATION | PRODUCTIVITY|
+------------+----------+-------------+
| 2024-12-02 | 08:15    | 92.0%       |
| 2024-12-03 | 07:45    | 88.0%       |
| 2024-12-04 | 08:30    | 95.0%       |
| 2024-12-05 | 07:20    | 85.0%       |
| 2024-12-06 | 08:00    | 90.0%       |
|            |          |             |
| TOTAL      | 39:50    | 90.0%       |
+------------+----------+-------------+

Use Cases

Daily Work Review

# Review today's work at end of day
kasl report

# Submit report to organization
kasl report --send

Weekly Planning

# Review yesterday's work before planning today
kasl report --last

Monthly Reporting

# Generate monthly summary for management
kasl report --month

Integration with Other Commands

The report command works with other kasl commands:

watch: Uses data collected by activity monitoring
task: Includes task completion data in reports
adjust: Reflects manual time adjustments in reports
pauses: Integrates pause data for comprehensive reporting

Best Practices

Daily Workflow

Review at end of day: Generate report to review productivity
Submit promptly: Send reports to maintain compliance
Monitor filtering: Check filtered interval notifications for data quality
Monitor trends: Track productivity patterns over time

Report Quality

Verify data accuracy: Check reports for unusual patterns
Review filtering: Note filtered short intervals for context
Document adjustments: Note any manual time corrections
Review completeness: Ensure all work is properly recorded

Organizational Integration

Configure API settings: Set up proper integration with reporting systems
Test submissions: Verify report delivery before relying on automation
Monitor compliance: Ensure reports meet organizational requirements
Backup locally: Keep local copies of submitted reports

watch - Monitor activity for report data
task - Manage tasks included in reports
adjust - Adjust times reflected in reports
pauses - View breaks included in reports
sum - Generate monthly summaries

`sum` Command

The sum command generates comprehensive monthly reports showing daily work hours, productivity metrics, and calendar integration with company rest days. It provides both detailed daily breakdowns and aggregate statistics for the current month.

Usage

kasl sum [OPTIONS]

Options

--send: Submit the monthly summary report
- Generates and submits the summary to the configured reporting API
- Useful for organizational reporting requirements
- Integrates with external systems like SiServer

Report Components

The monthly summary includes:

Daily Breakdown: Each workday with hours and productivity percentage
Rest Days: Company holidays and weekends with default hours
Monthly Totals: Total hours worked and average daily hours
Productivity Metrics: Average productivity across all workdays

Data Sources

The summary integrates data from multiple sources:

Local Database: Recorded workdays and pause information
External API: Company rest dates and holidays (if configured)
Configuration: Default work hours for rest days

Productivity Calculation

Productivity is calculated as:

Productivity = (Net Working Time / Gross Working Time) * 100%

Where:

Net Working Time: Actual productive work (excluding all pauses)
Gross Working Time: Total presence time (excluding long breaks only)

This provides insight into how effectively time is used during work sessions.

Rest Day Integration

If SiServer integration is configured, the summary will:

Fetch official company rest dates for the current month
Include these dates with default 8-hour entries
Distinguish between work days and rest days in the display

Examples

Basic Monthly Summary

# Display monthly summary for current month
kasl sum

Submit Monthly Report

# Generate and submit summary to configured API
kasl sum --send

Sample Output

December 2024

+------------+----------+-------------+
| DATE       | DURATION | PRODUCTIVITY|
+------------+----------+-------------+
| 2024-12-02 | 08:15    | 92.0%       |
| 2024-12-03 | 07:45    | 88.0%       |
| 2024-12-04 | 08:30    | 95.0%       |
| 2024-12-05 | 07:20    | 85.0%       |
| 2024-12-06 | 08:00    | 90.0%       |
| 2024-12-07 | 08:00    | 100.0%      |
| 2024-12-08 | 08:00    | 100.0%      |
| 2024-12-09 | 08:15    | 91.0%       |
| 2024-12-10 | 07:30    | 87.0%       |
|            |          |             |
| TOTAL      | 79:15    | 92.5%       |
+------------+----------+-------------+

Configuration

SiServer Integration

To enable rest day integration, configure SiServer in your settings:

kasl init --si-server-url "https://your-server.com" --si-server-token "your-token"

Default Work Hours

Configure default hours for rest days:

# Set default hours for rest days (default is 8 hours)
kasl init --default-hours 8

Integration with Other Commands

The sum command works with other kasl commands:

report: Daily reports that feed into monthly summaries
watch: Activity monitoring that provides the underlying data
adjust: Manual time adjustments that affect summary calculations
export: Export monthly data for external analysis

Use Cases

Monthly Reporting

# Generate monthly report for management
kasl sum --send

Productivity Analysis

# Review productivity trends
kasl sum
# Compare with previous months

Compliance Reporting

# Submit required monthly reports
kasl sum --send

Troubleshooting

Common Issues

No data for current month

# Check if monitoring is running
kasl watch --foreground

# Verify data exists
kasl report --last

API submission fails

# Check API configuration
kasl init --show-config

# Test API connection
kasl report --send

Incorrect rest days

# Verify SiServer configuration
kasl init --si-server-url "https://your-server.com"

# Check rest day settings
kasl init --show-config

Data Validation

# Verify daily data before generating summary
kasl report --last

# Check for missing days
kasl report --show-all

Best Practices

Monthly Workflow

Review daily reports throughout the month
Generate summary at month-end
Submit to organization if required
Archive data for historical analysis

Data Quality

Ensure monitoring is active during work hours
Review and adjust any incorrect time entries
Validate rest day configuration
Check API integration before submission

Reporting

Submit reports promptly at month-end
Keep local copies of submitted reports
Review productivity trends over time
Use insights to improve work patterns

report - Generate daily work reports
watch - Monitor activity for data collection
adjust - Adjust recorded times
export - Export data for external analysis
init - Configure API integration

`export` Command

The export command provides comprehensive data export functionality, supporting multiple output formats and data types. It enables users to extract their work data for external analysis, backup purposes, or integration with other tools and systems.

Usage

kasl export [DATA_TYPE] [OPTIONS]

Arguments

DATA_TYPE: Type of data to export (default: report)
- report: Daily work report with intervals and productivity
- tasks: Task records with completion status and metadata
- summary: Monthly summary with aggregate statistics
- all: Complete data export including all available information

Options

-f, --format <FORMAT>: Output format for the exported data (default: csv)
- csv: Comma-separated values, compatible with Excel and other spreadsheet tools
- json: Structured JSON data, ideal for programmatic processing
- excel: Native Excel format with formatting, charts, and multiple worksheets
-o, --output <PATH>: Custom output file path
- When specified, the export will be saved to this exact location
- If not provided, a default filename will be generated based on timestamp, data type, and format
-d, --date <DATE>: Target date for data export (default: today)
- today: Current date
- YYYY-MM-DD: Specific date in ISO format
- For summary exports, this determines the month to summarize

Supported Export Formats

CSV Format

Compatibility: Works with Excel, Google Sheets, and other spreadsheet applications
Structure: Tabular data with headers
Use Cases: Quick analysis, data sharing, simple reporting

JSON Format

Compatibility: Ideal for programmatic processing and API integration
Structure: Hierarchical data with metadata
Use Cases: Custom analysis scripts, data integration, backup

Excel Format

Compatibility: Native Excel with formatting and multiple sheets
Structure: Multiple worksheets with charts and formatting
Use Cases: Professional reporting, complex analysis, presentation

Data Types

Report Export

Exports daily work reports with intervals, tasks, and productivity metrics:

# Export today's report as CSV
kasl export report --format csv

# Export yesterday's report as Excel
kasl export report --date 2024-12-15 --format excel

Tasks Export

Exports task records with completion status and metadata:

# Export all tasks as JSON
kasl export tasks --format json

# Export today's tasks as CSV
kasl export tasks --date today --format csv

Summary Export

Exports monthly summaries with aggregate statistics:

# Export current month summary as Excel
kasl export summary --format excel

# Export specific month as CSV
kasl export summary --date 2024-11-01 --format csv

Complete Export

Exports all available data for comprehensive backup:

# Export all data as JSON
kasl export all --format json

# Export all data as Excel with custom filename
kasl export all --format excel --output my_backup.xlsx

Examples

Basic Exports

# Export today's report (default)
kasl export

# Export today's report as CSV
kasl export report --format csv

# Export today's report as JSON
kasl export report --format json

Custom File Names

# Export with custom filename
kasl export --output my_report.csv

# Export with date-specific filename
kasl export --date 2024-12-15 --output december_15_report.xlsx

Different Data Types

# Export tasks
kasl export tasks --format csv

# Export monthly summary
kasl export summary --format excel

# Export complete backup
kasl export all --format json --output backup.json

Date-Specific Exports

# Export yesterday's data
kasl export --date 2024-12-15

# Export specific date
kasl export --date 2024-11-30 --format excel

Sample Output

CSV Export (Report)

Date,Start Time,End Time,Duration,Productivity,Task Count
2024-12-15,09:00:00,17:30:00,8h 30m,92%,5

JSON Export (Tasks)

{
  "date": "2024-12-15",
  "tasks": [
    {
      "id": 1,
      "name": "Code review",
      "comment": "Review pull request #123",
      "completeness": 100,
      "tags": ["urgent", "backend"]
    }
  ]
}

Excel Export (Summary)

Sheet 1: Daily breakdown with charts
Sheet 2: Task completion statistics
Sheet 3: Productivity analysis
Sheet 4: Monthly totals and trends

File Naming Convention

Default filenames follow this pattern:

kasl_export_YYYYMMDD_HHMMSS.[format]

Examples:

kasl_export_20241215_143022.csv
kasl_export_20241215_143022.json
kasl_export_20241215_143022.xlsx

Use Cases

Data Backup

# Create comprehensive backup
kasl export all --format json --output backup_$(date +%Y%m%d).json

External Analysis

# Export for spreadsheet analysis
kasl export report --format csv --output analysis.csv

# Export for custom scripts
kasl export tasks --format json --output tasks.json

Reporting

# Create professional report
kasl export summary --format excel --output monthly_report.xlsx

# Export for management review
kasl export report --format excel --output daily_report.xlsx

Integration

# Export for API integration
kasl export all --format json --output api_data.json

# Export for database import
kasl export tasks --format csv --output tasks_import.csv

Troubleshooting

Common Issues

File permission errors

# Check directory permissions
ls -la /path/to/output/directory

# Use different output location
kasl export --output ~/Desktop/export.csv

Format not supported

# Check available formats
kasl export --help

# Use different format
kasl export --format csv

Date parsing errors

# Use correct date format
kasl export --date 2024-12-15

# Use 'today' for current date
kasl export --date today

Data Validation

# Verify data exists before export
kasl report --date 2024-12-15

# Check file was created
ls -la kasl_export_*.csv

Best Practices

Regular Backups

Schedule regular exports for data backup
Use different formats for different purposes
Store backups securely in multiple locations
Verify backup integrity after creation

File Management

Use descriptive filenames with dates
Organize exports in dedicated directories
Archive old exports to save space
Document export purposes for future reference

Data Analysis

Use CSV for quick spreadsheet analysis
Use JSON for custom scripts and APIs
Use Excel for professional reporting
Combine formats for comprehensive analysis

Integration with Other Commands

The export command works with other kasl commands:

report: Export daily reports
sum: Export monthly summaries
task: Export task data
watch: Data collected by monitoring feeds into exports

report - Generate daily work reports
sum - Generate monthly summaries
task - Manage tasks for export
watch - Monitor activity for data collection

`breaks` Command

The breaks command enables strategic placement of manual break periods to optimize productivity metrics and meet minimum thresholds for report submission. This productivity-focused feature helps users improve their work reports by adding intentional breaks that complement automatic pause detection.

Usage

kasl breaks [OPTIONS]

Options

-m, --minutes <MINUTES>: Duration of the break in minutes
- When specified, automatically finds optimal placement for the break
- If not specified, enters interactive mode for manual break configuration
- Must be within configured minimum and maximum break duration limits
--force: Force creation even if productivity validation fails
- Bypasses normal productivity threshold checks
- Creates the break regardless of current productivity levels
- Use with caution as this skips validation safeguards

Break Management Modes

Automatic Mode

Optimal break placement with specified duration:

# Add a 30-minute break with automatic optimal placement
kasl breaks -m 30

# Add a 60-minute break, bypassing productivity checks
kasl breaks -m 60 --force

How Automatic Placement Works:

Analyzes existing work intervals and pauses
Finds optimal placement using multiple strategies
Avoids conflicts with existing pauses
Maintains minimum work intervals around breaks

Interactive Mode

Guided break creation with user selection:

# Start interactive break creation
kasl breaks

# The command will prompt for:
# 1. Break duration (within configured limits)
# 2. Placement options with timing details
# 3. Selection from available placement strategies

Break Placement Strategies

The system uses intelligent algorithms to suggest optimal break placement:

1. Middle of Longest Work Period

Places the break in the center of the longest uninterrupted work interval:

Advantage: Splits long work sessions effectively
Best for: Improving focus and preventing fatigue

2. After Existing Pauses

Places breaks immediately following detected pauses:

Advantage: Extends natural break periods
Best for: Consolidating rest time

3. Before Existing Pauses

Places breaks just before detected pauses:

Advantage: Creates preparation time before natural breaks
Best for: Structuring work transitions

Examples

Quick Break Addition

# Add 30-minute break with optimal placement
kasl breaks -m 30

# Output:
# ✅ Break created: 14:30 - 15:00 (30 minutes)
# 📈 Productivity improved from 68% to 76%

Interactive Break Creation

# Start interactive mode
kasl breaks

# Sample interaction:
# Enter break duration (20-180 minutes): 45
# 
# Available break placement options:
# 1. 12:15 - 13:00 (45 min) - Middle of longest work period
# 2. 10:30 - 11:15 (45 min) - After morning pause
# 3. 15:45 - 16:30 (45 min) - Before afternoon pause
# 
# Select break placement: 1
# 
# ✅ Break created: 12:15 - 13:00 (45 minutes)

Productivity Optimization

# When productivity is too low for report submission:
# ⚠️ Current productivity: 68% (below 75% threshold)
# 💡 Add a 22-minute break to reach minimum productivity

kasl breaks -m 22

# ✅ Break created: 13:00 - 13:22 (22 minutes)
# 📈 Productivity improved to 75% - report can now be submitted

Productivity Integration

Automatic Recommendations

The system provides productivity recommendations when:

Current productivity is below configured threshold (default: 75%)
Enough of the workday has passed to make meaningful suggestions
Report submission is blocked due to low productivity

Threshold Validation

Before creating breaks, the system:

Calculates current productivity including existing pauses and breaks
Validates duration limits based on configuration
Checks for conflicts with existing pauses
Ensures minimum work intervals are maintained

Report Integration

Breaks directly impact report functionality:

Report display includes break information and productivity metrics
API submission validates productivity before sending reports
Productivity warnings suggest break creation when needed

Configuration

Break behavior is controlled by configuration settings:

{
  "productivity": {
    "min_productivity_threshold": 75.0,
    "workday_hours": 8.0,
    "min_break_duration": 20,
    "max_break_duration": 180,
    "min_workday_fraction_before_suggest": 0.5
  }
}

Configuration Options

min_productivity_threshold: Minimum productivity percentage for report submission
workday_hours: Expected daily work hours for calculations
min_break_duration: Minimum allowed break duration in minutes
max_break_duration: Maximum allowed break duration in minutes
min_workday_fraction_before_suggest: Fraction of workday before showing recommendations

Sample Output

Successful Break Creation

🔄 Analyzing workday and existing pauses...
✅ Break created: 14:30 - 15:00 (30 minutes)
📈 Productivity updated: 68% → 76%

Interactive Selection

📋 Break duration: 45 minutes

Available placement options:
1. 12:15 - 13:00 (45 min) - Middle of longest work period
2. 10:30 - 11:15 (45 min) - After 15-minute pause
3. 15:45 - 16:30 (45 min) - Before 8-minute pause

Select break placement: 2

✅ Break created: 10:30 - 11:15 (45 minutes)
📈 Productivity improved from 68% to 75%

Productivity Warning

⚠️ Low productivity detected: 68% (threshold: 75%)
💡 Consider adding a 22-minute break to reach minimum productivity
📝 Use: kasl breaks -m 22

Use Cases

Meeting Productivity Thresholds

# When report submission is blocked:
kasl report
# ❌ Productivity too low (68%) - minimum 75% required
# 💡 Add 22-minute break to reach threshold

kasl breaks -m 22
# ✅ Break added - productivity now 75%

kasl report
# ✅ Report sent successfully

Improving Work-Life Balance

# Add structured lunch break
kasl breaks -m 60

# Add afternoon rest period
kasl breaks -m 30

Optimizing Long Work Sessions

# Add break in middle of long work period
kasl breaks
# Select: "Middle of longest work period"

Validation and Safety

Pre-Creation Checks

The command performs several validations:

Workday Existence: Ensures a workday exists for today
Duration Limits: Validates break duration within configured bounds
Conflict Detection: Prevents overlaps with existing pauses
Work Interval Maintenance: Ensures minimum work time around breaks

Smart Placement

The placement algorithm ensures:

No Overlaps: Breaks don't conflict with existing pauses
Minimum Work Time: Maintains required work intervals
Optimal Timing: Places breaks for maximum productivity benefit
Current Time Validation: Only places breaks in completed time periods

Troubleshooting

Common Issues

No valid break placement found

# Check existing pauses and work intervals
kasl pauses

# Try shorter break duration
kasl breaks -m 20

# Check if enough work time has passed
kasl report

Break duration out of range

# Check configured limits
# Default: 20-180 minutes

# Use duration within limits
kasl breaks -m 45

Productivity still too low after break

# Check current productivity
kasl report

# Add additional break if needed
kasl breaks -m 30

Data Validation

# View current workday status
kasl report

# Check existing pauses
kasl pauses

# Review productivity metrics
kasl report --productivity

Best Practices

Strategic Break Placement

Target productivity thresholds rather than arbitrary break times
Use automatic mode for optimal placement
Add breaks gradually to see productivity impact
Monitor report feedback to understand effectiveness

Productivity Optimization

Check productivity early in the workday
Add breaks proactively before productivity drops too low
Use recommended durations from productivity warnings
Balance break time with actual work requirements

Integration Workflow

Monitor productivity throughout the day
Add breaks when warned by the system
Validate report submission after adding breaks
Review daily patterns to improve future planning

Integration with Other Commands

The breaks command works seamlessly with other kasl commands:

report: Shows productivity metrics and break impact
pauses: Displays existing pauses to avoid conflicts
watch: Continues monitoring activity with breaks included
export: Includes break data in exported reports

report - View productivity metrics and break impact
pauses - View existing pauses and gaps
watch - Monitor activity including break periods
export - Export data including break information

`pauses` Command

The pauses command provides detailed views of automatically detected and manually recorded breaks during work sessions. It helps users understand their break patterns and verify the accuracy of automatic pause detection.

Usage

kasl pauses [OPTIONS]

Options

-d, --date <DATE>: Date to fetch pauses for (default: today)
- today: Current date
- YYYY-MM-DD: Specific date in ISO format
-m, --min-duration <MINUTES>: Minimum pause duration filter in minutes
- When specified, only pauses longer than this duration will be displayed
- Overrides the default minimum pause duration from configuration
- Useful for filtering out brief interruptions and focusing on significant breaks
- If not specified, uses the configured min_pause_duration setting

Display Format

The output includes:

Pause List: Each pause with start time, end time, and duration
Total Time: Sum of all pause durations for the day
Pause Count: Number of breaks recorded

Data Sources

Pause data comes from:

Automatic Detection: Monitor-recorded inactivity periods
Manual Adjustments: User-added pauses via adjust command
Time Corrections: Modified pause times from manual adjustments

Examples

Basic Usage

# Show today's pauses
kasl pauses

# Show pauses for specific date
kasl pauses --date 2024-12-15

# Show pauses for yesterday
kasl pauses --date 2024-12-14

Duration Filtering

# Show only pauses longer than 30 minutes
kasl pauses --min-duration 30

# Show only significant breaks (longer than 15 minutes)
kasl pauses --min-duration 15

# Filter specific date with duration
kasl pauses --date 2024-12-15 --min-duration 10

Analysis Examples

# Review break patterns for the week
kasl pauses --date 2024-12-15
kasl pauses --date 2024-12-16
kasl pauses --date 2024-12-17

# Focus on significant breaks only
kasl pauses --min-duration 30

# Compare different duration thresholds
kasl pauses --min-duration 5
kasl pauses --min-duration 15
kasl pauses --min-duration 30

Sample Output

Today's Pauses

December 15, 2024

+--------------+-------+-------+----------+
| ID           | START | END   | DURATION |
+--------------+-------+-------+----------+
| 1            | 10:30 | 10:45 | 00:15    |
| 2            | 12:00 | 13:00 | 01:00    |
| 3            | 15:15 | 15:30 | 00:15    |
| 4            | 16:45 | 17:00 | 00:15    |
|              |       |       |          |
| TOTAL        |       |       | 01:45    |
+--------------+-------+-------+----------+

Filtered Output (min-duration: 30)

December 15, 2024

+--------------+-------+-------+----------+
| ID           | START | END   | DURATION |
+--------------+-------+-------+----------+
| 1            | 12:00 | 13:00 | 01:00    |
|              |       |       |          |
| TOTAL        |       |       | 01:00    |
+--------------+-------+-------+----------+

No Pauses Found

December 15, 2024

+--------------+-------+-------+----------+
| ID           | START | END   | DURATION |
+--------------+-------+-------+----------+
+--------------+-------+-------+----------+

Use Cases

Daily Break Review

# Review today's break patterns
kasl pauses

# Check if lunch break was recorded
kasl pauses --min-duration 30

Break Pattern Analysis

# Analyze break patterns over multiple days
for date in 2024-12-15 2024-12-16 2024-12-17; do
    echo "=== $date ==="
    kasl pauses --date $date
    echo
done

Monitoring Verification

# Verify that automatic pause detection is working
kasl pauses --min-duration 5

# Check for missed breaks
kasl pauses --date 2024-12-15

Manual Pause Review

# Review manually added pauses
kasl pauses --date 2024-12-15

# Compare with automatic detection
kasl report --date 2024-12-15

Duration Filtering

Understanding Duration Filters

The --min-duration option helps focus on significant breaks:

5 minutes: Very short breaks (coffee, bathroom)
15 minutes: Standard short breaks
30 minutes: Significant breaks (lunch, meetings)
60 minutes: Major breaks (lunch, appointments)

Configuration Integration

The command respects your configuration settings:

# Check your current minimum pause duration setting
kasl init --show-config

# The pauses command will use this setting by default
kasl pauses

Integration with Other Commands

The pauses command works with other kasl commands:

report: Compare pause data with overall workday summary
adjust: Add manual pauses that appear in pause listings
watch: Automatic pause detection that feeds into pause data
export: Export pause data for external analysis

Troubleshooting

Common Issues

No pauses found

# Check if workday exists
kasl report --date 2024-12-15

# Try without duration filter
kasl pauses --date 2024-12-15

# Check monitoring configuration
kasl init --show-config

Unexpected pause durations

# Review pause detection settings
kasl init --show-config

# Check for manual adjustments
kasl adjust --date 2024-12-15

Missing breaks

# Add manual pause if automatic detection missed it
kasl adjust --mode pause --minutes 30 --date 2024-12-15

# Verify the pause was added
kasl pauses --date 2024-12-15

Data Validation

# Cross-reference with workday report
kasl report --date 2024-12-15
kasl pauses --date 2024-12-15

# Export data for external verification
kasl export --date 2024-12-15 --format json

Best Practices

Regular Review

Review daily pauses to understand break patterns
Verify automatic detection is working correctly
Add manual pauses for missed breaks
Analyze patterns to improve work habits

Break Management

Use appropriate duration filters for different analysis needs
Document manual pauses with clear descriptions
Review break patterns to optimize productivity
Ensure compliance with break requirements

Data Quality

Verify pause accuracy regularly
Add missing breaks promptly
Review monitoring settings if detection is poor
Keep pause data consistent with workday records

report - View complete workday summary including pauses
adjust - Add manual pauses and adjust recorded times
watch - Monitor activity and detect automatic pauses
export - Export pause data for external analysis

`tag` Command

The tag command provides comprehensive tag management functionality, enabling users to create, organize, and utilize tags for better task categorization. Tags serve as a flexible labeling system that allows users to group and filter tasks by project, priority, type, or any custom criteria.

Usage

kasl tag [COMMAND] [OPTIONS]

Commands

`create` - Create a new tag

kasl tag create <NAME> [OPTIONS]

Arguments:

NAME: Unique name for the tag (required)

Options:

-c, --color <COLOR>: Optional color for visual organization
- Common color names: "red", "blue", "green", "yellow", "purple", "orange"
- Hex color codes: "#FF0000", "#00FF00", etc.

Examples:

# Create a simple tag
kasl tag create "urgent"

# Create a tag with color
kasl tag create "backend" --color "blue"

# Create a tag with hex color
kasl tag create "frontend" --color "#FF6B6B"

`list` - List all available tags

kasl tag list

Displays a formatted table of all existing tags with their names, colors, and creation dates.

Example:

kasl tag list

`edit` - Edit an existing tag

kasl tag edit <TAG> [OPTIONS]

Arguments:

TAG: Tag name or ID to edit

Options:

-n, --name <NAME>: New name for the tag
-c, --color <COLOR>: New color for the tag

Examples:

# Edit tag interactively
kasl tag edit "urgent"

# Edit tag with new name
kasl tag edit "urgent" --name "critical"

# Edit tag with new color
kasl tag edit "backend" --color "darkblue"

`delete` - Delete a tag

kasl tag delete <TAG> [OPTIONS]

Arguments:

TAG: Tag name or ID to delete

Options:

--force: Skip confirmation prompt

Examples:

# Delete tag with confirmation
kasl tag delete "old-tag"

# Force delete without confirmation
kasl tag delete "old-tag" --force

Tag Features

Tag CRUD Operations

Create: Define new tags with names and colors
Read: List and view existing tags
Update: Modify tag properties
Delete: Remove tags and clean up associations

Color Coding

Visual organization with customizable tag colors:

Named Colors: "red", "blue", "green", "yellow", "purple", "orange"
Hex Colors: "#FF0000", "#00FF00", "#0000FF"
Visual Impact: Colors appear in task listings and reports

Task Association

Link tags to tasks for categorization:

# Create task with tags
kasl task --name "Fix bug" --tags "urgent,backend"

# Add tags to existing task
kasl task --edit 1 --tags "urgent,backend"

Filtering

Find tasks by tag assignments:

# Show tasks with specific tag
kasl task --show --tag "urgent"

# Show tasks with multiple tags
kasl task --show --tag "backend,urgent"

Use Cases

Project Organization

# Create project tags
kasl tag create "frontend" --color "blue"
kasl tag create "backend" --color "green"
kasl tag create "mobile" --color "purple"

# Assign to tasks
kasl task --name "Update UI" --tags "frontend"
kasl task --name "Fix API bug" --tags "backend"

Priority Management

# Create priority tags
kasl tag create "urgent" --color "red"
kasl tag create "high" --color "orange"
kasl tag create "low" --color "gray"

# Filter by priority
kasl task --show --tag "urgent"

Task Type Categorization

# Create type tags
kasl tag create "bug" --color "red"
kasl tag create "feature" --color "green"
kasl tag create "documentation" --color "blue"
kasl tag create "meeting" --color "yellow"

# Organize tasks by type
kasl task --name "Fix login bug" --tags "bug,urgent"
kasl task --name "Add user profile" --tags "feature,frontend"

Status Tracking

# Create status tags
kasl tag create "in-progress" --color "blue"
kasl tag create "blocked" --color "red"
kasl tag create "waiting-review" --color "yellow"
kasl tag create "completed" --color "green"

# Track task status
kasl task --name "Code review" --tags "waiting-review,backend"

Examples

Complete Workflow

# 1. Create tags for your project
kasl tag create "frontend" --color "blue"
kasl tag create "backend" --color "green"
kasl tag create "urgent" --color "red"
kasl tag create "bug" --color "orange"

# 2. List all tags
kasl tag list

# 3. Create tasks with tags
kasl task --name "Fix login bug" --tags "urgent,bug,frontend"
kasl task --name "Add API endpoint" --tags "backend,feature"

# 4. Filter tasks by tags
kasl task --show --tag "urgent"
kasl task --show --tag "frontend"

Tag Management

# Create a comprehensive tag system
kasl tag create "project-a" --color "blue"
kasl tag create "project-b" --color "green"
kasl tag create "urgent" --color "red"
kasl tag create "low-priority" --color "gray"
kasl tag create "meeting" --color "yellow"
kasl tag create "documentation" --color "purple"

# Edit tag properties
kasl tag edit "project-a" --name "main-project" --color "darkblue"

# Delete unused tags
kasl tag delete "old-tag"

Interactive Usage

# Interactive tag creation
kasl tag create "new-tag"
# Prompts for color if not specified

# Interactive tag editing
kasl tag edit "existing-tag"
# Prompts for new name and color

# Interactive tag deletion
kasl tag delete "unused-tag"
# Prompts for confirmation

Sample Output

+----+----------+-------+
| ID | NAME     | COLOR |
+----+----------+-------+
| 1  | urgent   | red   |
| 2  | backend  | blue  |
| 3  | frontend | green |
| 4  | bug      | orange|
| 5  | meeting  | yellow|
+----+----------+-------+

Tag Creation

✅ Tag 'urgent' created successfully!
Color: red
ID: 1

Tag Editing

Editing tag 'urgent' (ID: 1)

Current properties:
├── Name: urgent
└── Color: red

New name (press Enter to keep current): critical
New color (press Enter to keep current): darkred

✅ Tag updated successfully!

Auto-Creation

Tags are automatically created when assigned to tasks:

# This will create the "new-tag" tag if it doesn't exist
kasl task --name "New task" --tags "new-tag,urgent"

Best Practices

Tag Naming

Use descriptive names: "frontend" instead of "fe"
Be consistent: Use the same naming convention
Keep it simple: Avoid overly complex tag names
Use lowercase: For consistency and easier typing

Color Organization

Use meaningful colors: Red for urgent, green for completed
Limit color palette: Don't use too many different colors
Consider accessibility: Ensure colors are distinguishable
Be consistent: Use the same colors for similar concepts

Tag Management

Regular cleanup: Delete unused tags
Consolidate similar tags: Merge duplicate concepts
Document tag meanings: Keep a reference of what each tag means
Review usage: Check which tags are most/least used

Task Organization

Use multiple tags: Combine project, priority, and type tags
Don't over-tag: Avoid using too many tags per task
Be consistent: Use the same tags for similar tasks
Review regularly: Update tags as projects evolve

Integration with Other Commands

The tag command works with other kasl commands:

task: Create and manage tasks with tags
report: View tasks organized by tags in reports
export: Export task data with tag information
sum: Include tag-based analysis in summaries

Troubleshooting

Common Issues

Tag already exists

# Check existing tags
kasl tag list

# Use different name or edit existing tag
kasl tag edit "existing-tag"

Tag not found

# List all tags to see available options
kasl tag list

# Check spelling and case sensitivity
kasl tag list | grep -i "tag-name"

Color not supported

# Use standard color names
kasl tag create "mytag" --color "red"

# Or use hex color codes
kasl tag create "mytag" --color "#FF0000"

Data Recovery

# Export tasks with tags before deletion
kasl export tasks --format json

# Review tag usage before deletion
kasl task --show --tag "tag-to-delete"

task - Create and manage tasks with tags
report - View tasks organized by tags
export - Export task data with tag information
sum - Include tag-based analysis in summaries

`template` Command

The template command provides comprehensive template management functionality for kasl, enabling users to create, edit, delete, and search reusable task templates. Templates streamline the creation of frequently used tasks by providing predefined values for name, comment, and completion status.

Usage

kasl template [COMMAND] [OPTIONS]

Commands

`create` - Create a new task template

kasl template create [OPTIONS]

Options:

-n, --name <NAME>: Unique name identifier for the template
- Must be unique across all templates
- Should be descriptive enough to easily identify the template's purpose
- Used for referencing the template in task creation commands

Examples:

# Create template interactively
kasl template create

# Create template with name
kasl template create --name "daily-standup"

`list` - List all available templates

kasl template list

Displays a formatted table of all existing templates with their names, task names, comments, and default completion values.

Example:

kasl template list

`edit` - Edit an existing template

kasl template edit [NAME] [OPTIONS]

Arguments:

NAME: Name of the template to edit (optional)
- If not provided, an interactive selection interface will be presented

Examples:

# Edit template interactively
kasl template edit

# Edit specific template
kasl template edit "daily-standup"

`delete` - Delete a template

kasl template delete [NAME] [OPTIONS]

Arguments:

NAME: Name of the template to delete (optional)
- If not provided, an interactive selection interface will be presented

Options:

--force: Skip confirmation prompt

Examples:

# Delete template with confirmation
kasl template delete "old-template"

# Force delete without confirmation
kasl template delete "old-template" --force

`search` - Search templates

kasl template search <QUERY>

Arguments:

QUERY: Search query string
- Searches both template names and task names for matches
- Case-insensitive partial matching is supported

Examples:

# Search for templates containing "meeting"
kasl template search "meeting"

# Search for templates containing "daily"
kasl template search "daily"

Template Features

Template CRUD Operations

Create: Define new templates with predefined task values
Read: List and view existing templates
Update: Modify template properties
Delete: Remove templates from the system

Search Functionality

Find templates by name or content:

Name Search: Find templates by template name
Content Search: Find templates by task name or comment
Partial Matching: Case-insensitive search with partial matches

Interactive Management

User-friendly interfaces for all operations:

Interactive Creation: Guided template creation process
Interactive Selection: Choose from available templates
Confirmation Prompts: Prevent accidental deletions

Integration

Seamless integration with task creation workflows:

# Use template when creating task
kasl task --from-template

# Use specific template
kasl task --template "daily-standup"

Use Cases

Daily Routines

# Create daily standup template
kasl template create --name "daily-standup"
# Template: Task name: "Daily standup", Comment: "Team sync meeting", Completeness: 0

# Create daily planning template
kasl template create --name "daily-planning"
# Template: Task name: "Plan day", Comment: "Review and plan daily tasks", Completeness: 0

Meeting Templates

# Create client meeting template
kasl template create --name "client-meeting"
# Template: Task name: "Client meeting", Comment: "Discuss project requirements", Completeness: 0

# Create team meeting template
kasl template create --name "team-meeting"
# Template: Task name: "Team meeting", Comment: "Weekly team sync", Completeness: 0

Development Tasks

# Create code review template
kasl template create --name "code-review"
# Template: Task name: "Code review", Comment: "Review pull request", Completeness: 0

# Create bug fix template
kasl template create --name "bug-fix"
# Template: Task name: "Fix bug", Comment: "Investigate and fix reported issue", Completeness: 0

Administrative Tasks

# Create documentation template
kasl template create --name "documentation"
# Template: Task name: "Update documentation", Comment: "Update project documentation", Completeness: 0

# Create email template
kasl template create --name "email"
# Template: Task name: "Email correspondence", Comment: "Respond to emails", Completeness: 0

Examples

Complete Workflow

# 1. Create templates for common tasks
kasl template create --name "daily-standup"
kasl template create --name "code-review"
kasl template create --name "client-meeting"

# 2. List all templates
kasl template list

# 3. Use templates to create tasks
kasl task --from-template
# Select from available templates

# 4. Use specific template
kasl task --template "daily-standup"

Template Management

# Create comprehensive template library
kasl template create --name "morning-routine"
kasl template create --name "afternoon-review"
kasl template create --name "end-of-day"
kasl template create --name "weekly-planning"

# Edit template properties
kasl template edit "morning-routine"

# Search for specific templates
kasl template search "meeting"

# Delete unused templates
kasl template delete "old-template"

Interactive Usage

# Interactive template creation
kasl template create
# Prompts for template name, task name, comment, and completeness

# Interactive template selection
kasl template edit
# Shows list of available templates to choose from

# Interactive template deletion
kasl template delete
# Shows list and prompts for confirmation

Sample Output

Template List

+---------------+---------------+---------------------+-------------+
| TEMPLATE NAME | TASK NAME     | COMMENT             | COMPLETENESS|
+---------------+---------------+---------------------+-------------+
| daily-standup | Daily standup | Team sync meeting   | 0%          |
| code-review   | Code review   | Review PR           | 0%          |
| client-meeting| Client meeting| Discuss requirements| 0%          |
| bug-fix       | Fix bug       | Investigate and fix | 0%          |
| documentation | Update docs   | Update documentation| 0%          |
+---------------+---------------+---------------------+-------------+

Template Creation

Creating new template...

Template name: daily-standup
Task name: Daily standup
Comment: Team sync meeting
Default completeness (0-100): 0

✅ Template 'daily-standup' created successfully!

Template Search

Searching for templates containing "meeting"...

Results:
├── client-meeting: Client meeting - Discuss requirements
├── team-meeting: Team meeting - Weekly team sync
└── daily-standup: Daily standup - Team sync meeting

Found 3 matching templates.

Template Editing

Editing template 'daily-standup'

Current properties:
├── Task name: Daily standup
├── Comment: Team sync meeting
└── Completeness: 0%

New task name (press Enter to keep current): Daily standup meeting
New comment (press Enter to keep current): Daily team standup meeting
New completeness (press Enter to keep current): 0

✅ Template updated successfully!

Using Templates with Tasks

Interactive Template Selection

# Create task using template selection
kasl task --from-template

# The command will show available templates:
# 1. daily-standup
# 2. code-review
# 3. client-meeting
# Select template: 1

Direct Template Usage

# Use specific template
kasl task --template "daily-standup"

# Use template with additional options
kasl task --template "code-review" --tags "urgent,backend"

Template with Customization

# Use template but override task name
kasl task --template "bug-fix" --name "Fix login bug"

# Use template but add custom comment
kasl task --template "client-meeting" --comment "Discuss new feature requirements"

Best Practices

Template Naming

Use descriptive names: "daily-standup" instead of "ds"
Be consistent: Use the same naming convention
Keep it simple: Avoid overly complex template names
Use lowercase: For consistency and easier typing

Template Content

Generic task names: Allow for customization when used
Clear comments: Provide helpful default descriptions
Appropriate completeness: Usually 0% for new tasks
Reusable structure: Make templates flexible for different contexts

Template Organization

Group related templates: Use consistent naming patterns
Regular cleanup: Delete unused templates
Document template purposes: Keep track of when to use each template
Review and update: Keep templates current with your workflow

Template Usage

Use templates frequently: For any recurring task type
Customize when needed: Override template values when appropriate
Combine with tags: Use templates with tags for better organization
Review effectiveness: Update templates based on usage patterns

Integration with Other Commands

The template command works with other kasl commands:

task: Use templates to create tasks quickly
tag: Combine templates with tags for better organization
report: View tasks created from templates in reports
export: Export template data for backup or sharing

Troubleshooting

Common Issues

Template name already exists

# Check existing templates
kasl template list

# Use different name or edit existing template
kasl template edit "existing-template"

Template not found

# List all templates to see available options
kasl template list

# Search for similar templates
kasl template search "partial-name"

Template not working with task creation

# Verify template exists
kasl template list

# Check template name spelling
kasl template search "template-name"

Data Recovery

# Export templates before deletion
kasl export --format json

# Review template usage before deletion
kasl template list

task - Create tasks using templates
tag - Combine templates with tags
report - View tasks created from templates
export - Export template data

`autostart` Command

The autostart command provides cross-platform functionality for managing whether kasl automatically starts monitoring when the system boots. It supports different autostart mechanisms depending on the operating system.

Usage

kasl autostart [COMMAND]

Commands

`enable` - Enable autostart on system boot

kasl autostart enable

Configures the system to automatically start kasl monitoring when the user logs in or the system boots.

Platform-specific behavior:

Windows:

Primary: Windows Task Scheduler (requires admin privileges)
Fallback: Registry Run key (current user)
Provides clear feedback about which method was used

macOS: LaunchAgent (planned - not yet implemented) Linux: systemd user service (planned - not yet implemented)

`disable` - Disable autostart on system boot

kasl autostart disable

Removes any existing autostart configuration, ensuring kasl will not automatically start on system boot.

`status` - Show current autostart status

kasl autostart status

Checks and displays whether autostart is currently enabled or disabled on the system.

Examples

Basic Usage

# Enable autostart
kasl autostart enable

# Check current status
kasl autostart status

# Disable autostart
kasl autostart disable

Windows-Specific Examples

# Enable with admin privileges (recommended)
# Run as Administrator
kasl autostart enable

# Enable without admin (user-level only)
kasl autostart enable

# Check which method was used
kasl autostart status

Platform Support

Windows

Supported Methods:

Windows Task Scheduler (Primary)
- Requires administrator privileges
- More reliable and configurable
- Can be managed through Windows Task Manager
Registry Run Key (Fallback)
- User-level configuration
- Works without admin privileges
- Less configurable than Task Scheduler

Implementation Details:

Attempts Task Scheduler first
Falls back to Registry if admin access denied
Provides clear feedback about which method was used

macOS (Planned)

Future Implementation:

LaunchAgent: User-level autostart
Configuration in ~/Library/LaunchAgents/
Integration with macOS system preferences

Linux (Planned)

Future Implementation:

systemd user service: Modern Linux systems
init.d scripts: Legacy systems
Integration with desktop environment autostart

Sample Output

Enable Autostart (Windows - Task Scheduler)

✅ Autostart enabled successfully!
Method: Windows Task Scheduler
Status: Active
Next run: On system startup

Enable Autostart (Windows - Registry Fallback)

⚠️  Autostart enabled with limited functionality
Method: Registry Run Key (user-level)
Status: Active
Note: Task Scheduler method requires administrator privileges

Status Check

Autostart Status: Enabled
Method: Windows Task Scheduler
Configuration: Active
Next startup: Will start automatically on system boot

Disable Autostart

✅ Autostart disabled successfully!
Removed: Task Scheduler entry
Removed: Registry entries
Status: Disabled

Unsupported Platform

❌ Autostart not supported on this platform
Platform: macOS
Status: Not implemented
Note: This feature is planned for future releases

Use Cases

Daily Workflow Automation

# Set up autostart for seamless monitoring
kasl autostart enable

# Verify it's working
kasl autostart status

# Start monitoring manually for first time
kasl watch

System Administration

# Deploy to multiple workstations
kasl autostart enable

# Verify deployment
kasl autostart status

# Remove from decommissioned systems
kasl autostart disable

Development and Testing

# Enable for testing
kasl autostart enable

# Test autostart functionality
# Restart system and verify kasl starts

# Disable after testing
kasl autostart disable

Troubleshooting

Common Issues

Insufficient privileges (Windows)

# Run as Administrator
# Right-click Command Prompt/PowerShell -> "Run as Administrator"
kasl autostart enable

# Or use user-level fallback
kasl autostart enable
# Will use Registry method automatically

Autostart not working after enable

# Check status
kasl autostart status

# Verify system startup
# Restart system and check if kasl starts

# Re-enable if needed
kasl autostart disable
kasl autostart enable

Platform not supported

# Check current platform support
kasl autostart status

# Manual startup alternative
# Add kasl watch to your startup scripts

Windows-Specific Issues

Task Scheduler not working

# Check Task Scheduler manually
# Open Task Scheduler -> Task Scheduler Library -> kasl

# Try Registry method
kasl autostart disable
kasl autostart enable

Registry method issues

# Check Registry manually
# HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run

# Re-enable with admin privileges
kasl autostart disable
# Run as Administrator
kasl autostart enable

Verification Steps

# 1. Enable autostart
kasl autostart enable

# 2. Check status
kasl autostart status

# 3. Test by restarting system
# Restart your computer

# 4. Verify kasl is running
kasl watch --stop
# If kasl was running, autostart is working

Best Practices

Windows Deployment

Use administrator privileges when possible for Task Scheduler method
Test autostart functionality after deployment
Document deployment method used for each system
Monitor autostart status regularly

System Management

Enable autostart on all workstations that need monitoring
Disable autostart when removing kasl from systems
Verify functionality after system updates
Keep autostart configuration documented

Security Considerations

Task Scheduler method is more secure than Registry
User-level autostart is sufficient for most use cases
Monitor autostart entries for unauthorized changes
Disable autostart on shared systems when appropriate

Integration with Other Commands

The autostart command works with other kasl commands:

watch: The monitoring command that gets started automatically
init: Configure kasl before enabling autostart
status: Check if monitoring is running after autostart

watch - The monitoring command that autostart enables
init - Configure kasl before setting up autostart
update - Update kasl while preserving autostart settings

`update` Command

The update command handles checking for and installing newer versions of kasl from GitHub releases. It provides automatic binary replacement with backup and rollback capabilities.

Usage

kasl update

How It Works

The update process performs a complete workflow:

Version Check: Queries GitHub API for the latest release
Platform Detection: Identifies the correct binary for the current OS/architecture
Download: Retrieves the latest release archive
Extraction: Unpacks the new binary from the archive
Replacement: Safely replaces the current executable with backup

Update Sources

Updates are fetched from GitHub releases at: https://github.com/{owner}/{repo}/releases/latest

The updater automatically selects the appropriate asset based on:

Architecture: x86_64, aarch64, etc.
Operating System: Windows (MSVC), macOS (Darwin), Linux (musl)

Platform Support

Supported platform identifiers:

x86_64-pc-windows-msvc - Windows 64-bit
x86_64-apple-darwin - macOS Intel
aarch64-apple-darwin - macOS Apple Silicon
x86_64-unknown-linux-musl - Linux 64-bit

Safety Features

The update process is designed to be safe and atomic:

Backup Creation: Creates backups of the current executable before replacement
Archive Validation: Validates downloaded archives before extraction
Clear Feedback: Provides detailed information about the update process
Error Handling: Handles network errors and other issues gracefully
Rollback Capability: Can restore from backup if update fails

Examples

Basic Update

# Check for and install updates
kasl update

Update Workflow

# 1. Check current version
kasl --version

# 2. Update to latest version
kasl update

# 3. Verify update
kasl --version

Sample Output

No Update Required

ℹ️  kasl is already up to date
Current version: 0.8.0
Latest version: 0.8.0
No update required.

Update Available

🔄 Checking for updates...
✅ New version available: 0.8.1

📥 Downloading update...
├── Platform: x86_64-pc-windows-msvc
├── Size: 2.5 MB
└── Progress: 100%

🔧 Installing update...
├── Creating backup: kasl.exe.backup
├── Extracting binary
└── Replacing executable

✅ Update completed successfully!
Version: 0.8.1
Backup: kasl.exe.backup

Update Error

❌ Update failed: Network error
Error: Failed to download release archive
Suggestion: Check your internet connection and try again

Use Cases

Regular Maintenance

# Check for updates weekly
kasl update

# Verify update was successful
kasl --version

System Administration

# Update kasl on multiple systems
for system in system1 system2 system3; do
    ssh $system "kasl update"
done

Development and Testing

# Update to latest development version
kasl update

# Test new features
kasl --help

# Rollback if needed (manual process)
# Restore from backup file

Troubleshooting

Common Issues

Network connectivity problems

# Check internet connection
ping github.com

# Try again later
kasl update

Permission errors

# Run with elevated privileges (Windows)
# Right-click Command Prompt -> "Run as Administrator"
kasl update

# Check file permissions (Unix)
ls -la $(which kasl)

Insufficient disk space

# Check available disk space
df -h

# Clean up space and try again
kasl update

Update Failures

Download failed

# Check network connection
curl -I https://github.com

# Try again
kasl update

Extraction failed

# Check if backup exists
ls -la kasl.exe.backup

# Restore from backup manually
cp kasl.exe.backup kasl.exe

Binary replacement failed

# Check if kasl is running
tasklist | grep kasl

# Stop kasl and try again
kasl watch --stop
kasl update

Verification Steps

# 1. Check current version
kasl --version

# 2. Perform update
kasl update

# 3. Verify new version
kasl --version

# 4. Test functionality
kasl --help

Best Practices

Update Strategy

Regular updates: Check for updates weekly or monthly
Test after update: Verify functionality after each update
Keep backups: Don't delete backup files immediately
Monitor for issues: Watch for any problems after updates

System Management

Update during maintenance windows: Choose appropriate times for updates
Update all systems: Keep all installations on the same version
Document update process: Keep track of update procedures
Test in staging: Test updates on non-critical systems first

Backup Management

Preserve backups: Keep backup files for potential rollback
Clean up old backups: Remove backups older than a few versions
Verify backup integrity: Test backup restoration periodically
Document rollback procedures: Know how to restore from backup

Integration with Other Commands

The update command works with other kasl commands:

autostart: Updates preserve autostart configuration
init: Configuration settings are preserved during updates
watch: Monitoring continues after update (if autostart is enabled)

autostart - Autostart settings are preserved during updates
init - Configuration is maintained during updates
watch - Monitoring continues after successful updates

API Integrations

kasl supports integration with external services for enhanced task management and reporting capabilities.

Overview

API integrations provide:

Task Discovery: Import tasks from external systems
Report Submission: Send reports to organizational systems
Credential Management: Secure storage and authentication
Session Handling: Automatic session management and renewal

GitLab Integration

Import commits and merge requests as completed tasks.

Setup

Generate Access Token:
- Go to GitLab → User Settings → Access Tokens
- Create token with scopes: read_user, read_repository
- Copy the generated token

Configure Integration:

kasl init
# Follow prompts to configure GitLab

Configuration

{
  "gitlab": {
    "access_token": "glpat-XXXXXXXXXXXXXXXXXXXX",
    "api_url": "https://gitlab.com"
  }
}

Features

Commit Import: Automatically import today's commits as completed tasks
User Activity: Track user activity across repositories
Repository Filtering: Support for multiple repositories
Commit Message Parsing: Extract meaningful task names from commit messages

Usage

# Find tasks from GitLab
kasl task --find

# This will show:
# - Incomplete local tasks
# - Today's GitLab commits
# - Interactive selection interface

API Endpoints Used

GET /api/v4/user - Get user information
GET /api/v4/events - Get user events
GET /api/v4/projects/{id}/repository/commits/{sha} - Get commit details

Jira Integration

Import completed issues and track work items.

Setup

Get Credentials:
- Username (not email, unless configured)
- Password (prompted interactively)
- Jira instance URL

Configure Integration:

kasl init
# Follow prompts to configure Jira

Configuration

{
  "jira": {
    "login": "john.doe",
    "api_url": "https://company.atlassian.net"
  }
}

Features

Issue Import: Import completed issues as tasks
Status Tracking: Filter by issue status
Project Support: Support for multiple projects
Field Mapping: Custom field support

Usage

# Find tasks from Jira
kasl task --find

# This will show:
# - Incomplete local tasks
# - Today's GitLab commits
# - Today's completed Jira issues
# - Interactive selection interface

API Endpoints Used

POST /rest/auth/1/session - Authenticate
GET /rest/api/2/search - Search issues
GET /rest/api/2/issue/{key} - Get issue details

SiServer Integration

Submit reports to internal company systems.

Setup

Get Credentials:
- Corporate username
- Password (prompted interactively)
- Authentication URL
- API URL

Configure Integration:

kasl init
# Follow prompts to configure SiServer

Configuration

{
  "si": {
    "login": "john.doe@company.com",
    "auth_url": "https://auth.company.com",
    "api_url": "https://api.company.com"
  }
}

Features

Daily Reports: Submit daily work reports
Monthly Reports: Submit monthly summaries
Rest Dates: Import company holidays and rest days
Secure Authentication: LDAP-based authentication

Usage

# Submit daily report
kasl report --send

# Submit monthly report
kasl sum --send

# This will:
# - Authenticate with SiServer
# - Format report data
# - Submit via API
# - Handle errors and retries

API Endpoints Used

POST /auth/login - Authenticate
POST /reports/daily - Submit daily report
POST /reports/monthly - Submit monthly report
GET /calendar/rest-dates - Get rest dates

Credential Management

Secure Storage

Credentials are stored securely:

API Tokens: Encrypted in separate files
Passwords: Not stored, prompted interactively
Session Data: Cached temporarily

File Locations

Windows: %LOCALAPPDATA%\lacodda\kasl\
macOS: ~/Library/Application Support/lacodda/kasl/
Linux: ~/.local/share/lacodda/kasl/

Encryption

Algorithm: AES-256-CBC
Key Management: Compile-time embedded keys
File Permissions: Restricted access

Session Management

Automatic Handling

Sessions are managed automatically:

Authentication: Prompted when needed
Caching: Sessions cached for performance
Renewal: Automatic session renewal
Cleanup: Expired sessions removed

Session Files

.gitlab_session - GitLab session data
.jira_session - Jira session data
.si_session - SiServer session data

Error Handling

Network Errors: Automatic retry with backoff
Authentication Failures: Re-prompt for credentials
Session Expiry: Automatic re-authentication
Rate Limiting: Respect API rate limits

Troubleshooting

Common Issues

Problem: Authentication failures

# Clear cached sessions
rm ~/.local/share/lacodda/kasl/.gitlab_session
rm ~/.local/share/lacodda/kasl/.jira_session
rm ~/.local/share/lacodda/kasl/.si_session

# Reconfigure integration
kasl init

Problem: API connection errors

# Test connectivity
curl -H "Authorization: Bearer YOUR_TOKEN" https://gitlab.com/api/v4/user

# Check network settings
ping gitlab.com

Problem: Rate limiting

# Wait and retry
# kasl handles rate limiting automatically
# Check API documentation for limits

Debug Mode

Enable debug logging for API operations:

RUST_LOG=kasl=debug kasl task --find

This will show:

API requests and responses
Authentication attempts
Session management
Error details

API Limits

Be aware of API rate limits:

GitLab: 600 requests/hour for authenticated users
Jira: Varies by plan and usage
SiServer: Depends on company configuration

Best Practices

Security

Token Rotation: Regularly rotate API tokens
Minimal Permissions: Use tokens with minimal required scopes
Secure Storage: Keep configuration files secure
Network Security: Use HTTPS for all API communications

Performance

Caching: Sessions are cached to reduce API calls
Batch Operations: Use batch operations when possible
Rate Limiting: Respect API rate limits
Connection Pooling: Efficient HTTP connection management

Monitoring

Error Tracking: Monitor for authentication failures
Usage Monitoring: Track API usage patterns
Performance Metrics: Monitor response times
Log Analysis: Review debug logs for issues

Custom Integrations

Adding New APIs

To add support for new APIs:

Create API Client: Implement the Session trait
Add Configuration: Extend configuration structure
Update Commands: Add integration to relevant commands
Add Tests: Comprehensive test coverage

Example Implementation

#![allow(unused)]
fn main() {
pub struct CustomApi {
    client: Client,
    config: CustomConfig,
    credentials: Option<LoginCredentials>,
    retries: i32,
}

impl Session for CustomApi {
    async fn login(&self) -> Result<String> {
        // Implementation
    }
    
    fn set_credentials(&mut self, password: &str) -> Result<()> {
        // Implementation
    }
    
    // ... other required methods
}
}

Configuration Extension

{
  "custom_api": {
    "login": "username",
    "api_url": "https://api.example.com"
  }
}

Database

kasl uses SQLite as its local database for storing work sessions, tasks, and configuration data.

Overview

The database provides:

Local Storage: All data stored locally for privacy
ACID Compliance: Reliable data integrity
Migration System: Safe schema updates
Cross-Platform: Works on all supported platforms

Database Location

Database files are stored in platform-specific locations:

Windows: %LOCALAPPDATA%\lacodda\kasl\kasl.db
macOS: ~/Library/Application Support/lacodda/kasl/kasl.db
Linux: ~/.local/share/lacodda/kasl/kasl.db

CREATE TABLE workdays (
    id INTEGER PRIMARY KEY,
    date TEXT UNIQUE NOT NULL,
    start TEXT NOT NULL,
    end TEXT
);

`pauses`

Stores break periods during work sessions:

CREATE TABLE pauses (
    id INTEGER PRIMARY KEY,
    start TEXT NOT NULL,
    end TEXT,
    duration INTEGER
);

`tasks`

Stores task information and metadata:

CREATE TABLE tasks (
    id INTEGER PRIMARY KEY,
    task_id INTEGER DEFAULT 0,
    timestamp TEXT DEFAULT CURRENT_TIMESTAMP,
    name TEXT NOT NULL,
    comment TEXT,
    completeness INTEGER DEFAULT 100,
    excluded_from_search BOOLEAN DEFAULT FALSE
);

`tags`

Stores task categorization tags:

CREATE TABLE tags (
    id INTEGER PRIMARY KEY,
    name TEXT UNIQUE NOT NULL,
    color TEXT,
    created_at TEXT DEFAULT CURRENT_TIMESTAMP
);

`task_tags`

Links tasks to tags (many-to-many relationship):

CREATE TABLE task_tags (
    task_id INTEGER NOT NULL,
    tag_id INTEGER NOT NULL,
    FOREIGN KEY (task_id) REFERENCES tasks(id) ON DELETE CASCADE,
    FOREIGN KEY (tag_id) REFERENCES tags(id) ON DELETE CASCADE,
    PRIMARY KEY (task_id, tag_id)
);

`task_templates`

Stores reusable task templates:

CREATE TABLE task_templates (
    id INTEGER PRIMARY KEY,
    name TEXT UNIQUE NOT NULL,
    task_name TEXT NOT NULL,
    comment TEXT,
    completeness INTEGER DEFAULT 0,
    created_at TEXT DEFAULT CURRENT_TIMESTAMP
);

`migrations`

Tracks database schema version:

CREATE TABLE migrations (
    version INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    applied_at TEXT DEFAULT CURRENT_TIMESTAMP
);

Data Types

Timestamps

Format: ISO 8601 (YYYY-MM-DD HH:MM:SS)
Timezone: Local system time
Storage: TEXT for human readability

Dates

Format: ISO 8601 (YYYY-MM-DD)
Storage: TEXT for consistency

Durations

Unit: Seconds
Storage: INTEGER for efficient calculations

Booleans

Storage: INTEGER (0 = false, 1 = true)
SQLite standard: No native boolean type

Migration System

Automatic Migrations

Migrations run automatically on startup:

kasl watch  # Migrations run automatically

Manual Migration Management

Debug builds provide migration commands:

# Check migration status
kasl migrations status

# View migration history
kasl migrations history

Migration Process

Version Check: Compare current vs. target version
Migration Selection: Find pending migrations
Transaction: Apply migrations in transaction
Version Update: Update migration table
Rollback: Rollback on failure

Migration Safety

Transactions: All migrations run in transactions
Idempotency: Safe to run multiple times
Rollback: Automatic rollback on failure
Versioning: Strict version ordering

Data Management

Backup

Create database backups:

# Copy database file
cp ~/.local/share/lacodda/kasl/kasl.db kasl_backup.db

# Export data
kasl export all --format json --output backup.json

Restore

Restore from backup:

# Replace database file
cp kasl_backup.db ~/.local/share/lacodda/kasl/kasl.db

# Import data
# (Manual import not yet implemented)

Cleanup

Remove old data:

# Delete specific tasks
kasl task --delete 1 2 3

# Delete all today's tasks
kasl task --delete-today

# Delete old pauses (manual SQL)
sqlite3 kasl.db "DELETE FROM pauses WHERE start < date('now', '-30 days');"

Performance

Indexes

Automatic indexes for performance:

-- Workdays table
CREATE INDEX idx_workdays_date ON workdays(date);

-- Tasks table
CREATE INDEX idx_tasks_timestamp ON tasks(timestamp);
CREATE INDEX idx_tasks_completeness ON tasks(completeness);

-- Pauses table
CREATE INDEX idx_pauses_start ON pauses(start);

Optimization

Connection Pooling: Efficient connection management
Prepared Statements: Reused query plans
Transactions: Batch operations for performance
Memory Management: Automatic cleanup

Monitoring

Check database performance:

# Enable SQLite logging
RUST_LOG=kasl=debug kasl report

# Check database size
ls -lh ~/.local/share/lacodda/kasl/kasl.db

# Analyze database
sqlite3 kasl.db "ANALYZE;"

Security

File Permissions

Secure database file:

# Linux/macOS
chmod 600 ~/.local/share/lacodda/kasl/kasl.db
chmod 700 ~/.local/share/lacodda/kasl/

Data Privacy

Local Storage: No data sent to external servers
Encryption: Consider filesystem encryption
Access Control: Restrict file permissions
Audit Trail: Complete operation logging

Troubleshooting

Common Issues

Problem: Database locked

# Check for running processes
ps aux | grep kasl

# Stop all kasl processes
kasl watch --stop

# Check file permissions
ls -la ~/.local/share/lacodda/kasl/kasl.db

Problem: Corrupted database

# Check database integrity
sqlite3 kasl.db "PRAGMA integrity_check;"

# Recover if possible
sqlite3 kasl.db ".recover" | sqlite3 kasl_recovered.db

# Restore from backup
cp kasl_backup.db kasl.db

Problem: Migration failures

# Check migration status
kasl migrations status

# View error logs
RUST_LOG=kasl=debug kasl watch --foreground

Debug Database

Enable SQLite debugging:

# Show SQL queries
RUST_LOG=kasl=debug kasl report

# Direct database access
sqlite3 ~/.local/share/lacodda/kasl/kasl.db

# Common queries
SELECT * FROM workdays ORDER BY date DESC LIMIT 5;
SELECT * FROM tasks WHERE date(timestamp) = date('now');
SELECT COUNT(*) FROM pauses WHERE date(start) = date('now');

Advanced Usage

Direct SQL Access

Access database directly:

sqlite3 ~/.local/share/lacodda/kasl/kasl.db

Common queries:

-- Today's work session
SELECT * FROM workdays WHERE date = date('now');

-- Today's tasks
SELECT * FROM tasks WHERE date(timestamp) = date('now');

-- Today's pauses
SELECT * FROM pauses WHERE date(start) = date('now');

-- Task completion statistics
SELECT 
    COUNT(*) as total_tasks,
    SUM(CASE WHEN completeness = 100 THEN 1 ELSE 0 END) as completed,
    AVG(completeness) as avg_completion
FROM tasks 
WHERE date(timestamp) = date('now');

Data Export

Export specific data:

# Export workdays
sqlite3 kasl.db "SELECT * FROM workdays;" > workdays.csv

# Export tasks with tags
sqlite3 kasl.db "
SELECT t.name, t.completeness, GROUP_CONCAT(tag.name) as tags
FROM tasks t
LEFT JOIN task_tags tt ON t.id = tt.task_id
LEFT JOIN tags tag ON tt.tag_id = tag.id
GROUP BY t.id
ORDER BY t.timestamp DESC;
" > tasks_with_tags.csv

Custom Queries

Create custom reports:

-- Weekly summary
SELECT 
    date,
    COUNT(*) as tasks,
    AVG(completeness) as avg_completion
FROM tasks 
WHERE date(timestamp) >= date('now', '-7 days')
GROUP BY date
ORDER BY date;

-- Tag usage statistics
SELECT 
    tag.name,
    COUNT(*) as usage_count
FROM tags tag
JOIN task_tags tt ON tag.id = tt.tag_id
GROUP BY tag.id
ORDER BY usage_count DESC;

Development

Kasl Documentation Style Guide

This style guide defines standards for writing comments, module documentation, and API documentation for the kasl project.

Brevity and Clarity - Comments should be informative but not excessive
Consistency - Use consistent patterns throughout the project
Relevance - Documentation should match the code
Practicality - Focus on what developers need to know

Terminology

Use consistent terminology:

Task - A unit of work
Workday - A work session
Pause - A break in work
Tag - Task categorization
Template - Task template

📚 Module Documentation

Standard Structure

#![allow(unused)]
fn main() {
//! [Brief module name]
//! 
//! [Brief description in one sentence]
//! 
//! ## Features
//! 
//! - [List of main capabilities]
//! 
//! ## Usage
//! 
//! [Usage examples]
//! 
//! ## Architecture
//! 
//! [Architecture description, if applicable]
}

Examples

✅ Good:

#![allow(unused)]
fn main() {
//! Task management database operations.
//! 
//! Provides core functionality for managing tasks within the kasl application.
//! Handles all database interactions for task creation, modification, deletion,
//! and retrieval with support for advanced filtering, tagging, and relationship management.
//! 
//! ## Features
//! 
//! - **CRUD Operations**: Complete Create, Read, Update, Delete functionality
//! - **Advanced Filtering**: Multi-criteria task querying with date, completion, and tag filters
//! - **Batch Operations**: Efficient bulk deletion and modification operations
//! - **Tag Integration**: Seamless integration with the tagging system for categorization
//! 
//! ## Usage
//! 
//! ```rust
//! use kasl::db::tasks::{Tasks, TaskFilter};
//! use kasl::libs::task::Task;
//! 
//! let mut tasks = Tasks::new()?;
//! let task = Task::new("Review code", "Check PR #123", Some(75));
//! tasks.insert(&task)?;
//! ```
}

❌ Bad:

#![allow(unused)]
fn main() {
//! Comprehensive task management database operations and querying.
//! 
//! This module provides the core functionality for managing tasks within the kasl
//! application. It handles all database interactions for task creation, modification,
//! deletion, and retrieval with support for advanced filtering, tagging, and
//! relationship management.
//! 
//! ## Task Management Features
//! 
//! - **CRUD Operations**: Complete Create, Read, Update, Delete functionality
//! - **Advanced Filtering**: Multi-criteria task querying with date, completion, and tag filters  
//! - **Batch Operations**: Efficient bulk deletion and modification operations
//! - **Tag Integration**: Seamless integration with the tagging system for categorization
//! - **Task Hierarchies**: Support for parent-child task relationships
//! - **Search Capabilities**: Flexible task discovery and filtering mechanisms
}

🔧 Function Documentation

Standard Structure

#![allow(unused)]
fn main() {
/// [Brief function description]
///
/// [Detailed description if necessary]
///
/// # Arguments
///
/// * `param` - [parameter description]
///
/// # Returns
///
/// [return value description]
///
/// # Errors
///
/// [possible errors description]
///
/// # Examples
///
/// ```rust
/// [usage example]
/// ```
}

Examples

✅ Good:

#![allow(unused)]
fn main() {
/// Performs authentication and returns a session identifier.
///
/// Handles API authentication using stored credentials and returns a session ID
/// for subsequent API calls.
///
/// # Returns
///
/// Session identifier on success, error on failure
///
/// # Errors
///
/// Returns an error if:
/// - Network connection fails
/// - Credentials are invalid
/// - API returns an unexpected response format
}

❌ Bad:

#![allow(unused)]
fn main() {
/// Performs authentication and returns a session identifier.
///
/// This method handles the actual API authentication process using stored
/// credentials. The returned session ID can be used for subsequent API calls.
///
/// # Returns
///
/// * `Result<String>` - Session identifier on success, error on failure
///
/// # Errors
///
/// Returns an error if:
/// - Network connection fails
/// - Credentials are invalid
/// - API returns an unexpected response format
}

🏗️ Struct Documentation

Standard Structure

#![allow(unused)]
fn main() {
/// [Brief struct description]
///
/// [Detailed description of purpose and usage]
///
/// ## Fields
///
/// - `field1`: [field description]
/// - `field2`: [field description]
///
/// ## Usage
///
/// [usage examples]
}

Examples

✅ Good:

#![allow(unused)]
fn main() {
/// Task representation with all associated metadata.
///
/// Represents a single work item with progress tracking, categorization,
/// and relationship capabilities.
///
/// ## Fields
///
/// - `id`: Database primary key for unique identification
/// - `name`: Human-readable task title
/// - `completeness`: Progress percentage (0-100)
/// - `tags`: Collection of categorization labels
}

📝 Field Documentation

Standard Structure

#![allow(unused)]
fn main() {
/// [Brief field description]
///
/// [Detailed description of purpose, values, and usage]
///
/// ## Values
///
/// - `value1`: [value description]
/// - `value2`: [value description]
///
/// ## Examples
///
/// [usage examples]
}

Examples

✅ Good:

#![allow(unused)]
fn main() {
/// Database primary key for task identification.
///
/// Automatically assigned when the task is first saved. Used for database
/// queries and cross-referencing with other application data.
///
/// ## Values
///
/// - `Some(id)`: Task exists in database with assigned ID
/// - `None`: New task not yet saved to database
pub id: Option<i32>,

/// Task completion percentage indicating progress from 0% to 100%.
///
/// Tracks the task's progress through its lifecycle, providing quantitative
/// measurement of work completion.
///
/// ## Values
///
/// - `Some(0)`: Task not started
/// - `Some(1-99)`: Task in progress
/// - `Some(100)`: Task completed
/// - `None`: Progress not tracked or unknown
pub completeness: Option<i32>,
}

❌ Bad:

#![allow(unused)]
fn main() {
/// Database primary key for task identification and relationships.
///
/// This field contains the unique identifier assigned by the database
/// when the task is first saved. It's used for:
/// - Database queries and updates
/// - Foreign key relationships (tags, time tracking)
/// - Cross-referencing with other application data
///
/// **Values:**
/// - `Some(id)`: Task exists in database with assigned ID
/// - `None`: New task not yet saved to database
pub id: Option<i32>,
}

🔗 Constants and SQL

SQL Constants

#![allow(unused)]
fn main() {
/// SQL schema for the [table_name] table.
///
/// Defines the complete structure for storing [description] with support for:
/// - [feature 1]
/// - [feature 2]
/// - [feature 3]
const SCHEMA_[TABLE]: &str = "...";

/// [Operation description] query.
///
/// [Detailed description of purpose and usage]
const [OPERATION]_[TABLE]: &str = "...";
}

Examples

✅ Good:

#![allow(unused)]
fn main() {
/// SQL schema for the tasks table.
///
/// Defines the complete structure for storing task information with support for:
/// - Unique identification and hierarchical relationships
/// - Temporal tracking with automatic timestamp generation
/// - Progress monitoring through completion percentages
const SCHEMA_TASKS: &str = "...";

/// Insert a new task with full field specification.
///
/// Creates a task record with automatic timestamp generation and immediate
/// ID return for further operations.
const INSERT_TASK: &str = "...";
}

🧪 Test Documentation

Standard Structure

#![allow(unused)]
fn main() {
/// [Brief test description]
///
/// [Detailed description of what is being tested and how]
///
/// ## Test Setup
///
/// [test setup description]
///
/// ## Assertions
///
/// [assertions description]
}

Examples

✅ Good:

#![allow(unused)]
fn main() {
/// Test context providing isolated environment for configuration tests.
///
/// Sets up temporary directories and environment variables to ensure
/// tests don't interfere with each other or the user's actual configuration.
struct ConfigTestContext {
    _temp_dir: TempDir,
    // ... other fields
}

/// Verifies that default configuration is created correctly.
///
/// Ensures that when no configuration exists, the system creates
/// appropriate default values for all configuration sections.
#[test]
fn test_default_config() {
    // ... test implementation
}
}

❌ Bad:

#![allow(unused)]
fn main() {
/// Test context to ensure a clean environment for each config test.
/// It sets up a temporary directory to act as the user's home/appdata directory.
struct ConfigTestContext {
    _temp_dir: TempDir,
    // ... other fields
}

#[test]
fn test_default_config(_ctx: &mut ConfigTestContext) {
    // ... test implementation
}
}

📖 Examples

Complete Module Example

#![allow(unused)]
fn main() {
//! Task management database operations.
//! 
//! Provides core functionality for managing tasks within the kasl application.
//! Handles all database interactions for task creation, modification, deletion,
//! and retrieval with support for advanced filtering, tagging, and relationship management.
//! 
//! ## Features
//! 
//! - **CRUD Operations**: Complete Create, Read, Update, Delete functionality
//! - **Advanced Filtering**: Multi-criteria task querying with date, completion, and tag filters
//! - **Batch Operations**: Efficient bulk deletion and modification operations
//! - **Tag Integration**: Seamless integration with the tagging system for categorization
//! 
//! ## Usage
//! 
//! ```rust
//! use kasl::db::tasks::{Tasks, TaskFilter};
//! use kasl::libs::task::Task;
//! 
//! let mut tasks = Tasks::new()?;
//! let task = Task::new("Review code", "Check PR #123", Some(75));
//! tasks.insert(&task)?;
//! 
//! let today_tasks = tasks.fetch(TaskFilter::Date(Local::now().date_naive()))?;
//! ```

/// Task representation with all associated metadata.
///
/// Represents a single work item with progress tracking, categorization,
/// and relationship capabilities.
#[derive(Debug, Clone)]
pub struct Task {
    /// Database primary key for task identification.
    ///
    /// Automatically assigned when the task is first saved. Used for database
    /// queries and cross-referencing with other application data.
    ///
    /// ## Values
    ///
    /// - `Some(id)`: Task exists in database with assigned ID
    /// - `None`: New task not yet saved to database
    pub id: Option<i32>,

    /// Task completion percentage indicating progress from 0% to 100%.
    ///
    /// Tracks the task's progress through its lifecycle, providing quantitative
    /// measurement of work completion.
    ///
    /// ## Values
    ///
    /// - `Some(0)`: Task not started
    /// - `Some(1-99)`: Task in progress
    /// - `Some(100)`: Task completed
    /// - `None`: Progress not tracked or unknown
    pub completeness: Option<i32>,
}

impl Task {
    /// Creates a new task with the specified properties.
    ///
    /// Initializes a task with the given name, comment, and completion status.
    /// The task will be assigned an ID when saved to the database.
    ///
    /// # Arguments
    ///
    /// * `name` - Task title or description
    /// * `comment` - Optional detailed description
    /// * `completeness` - Initial completion percentage
    ///
    /// # Examples
    ///
    /// ```rust
    /// let task = Task::new("Fix bug", "Critical security issue", Some(0));
    /// ```
    pub fn new(name: &str, comment: &str, completeness: Option<i32>) -> Self {
        // ... implementation
    }
}

/// SQL schema for the tasks table.
///
/// Defines the complete structure for storing task information with support for:
/// - Unique identification and hierarchical relationships
/// - Temporal tracking with automatic timestamp generation
/// - Progress monitoring through completion percentages
const SCHEMA_TASKS: &str = "CREATE TABLE IF NOT EXISTS tasks (
    id INTEGER NOT NULL PRIMARY KEY,
    task_id INTEGER NOT NULL ON CONFLICT REPLACE DEFAULT 0,
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    name TEXT NOT NULL,
    comment TEXT,
    completeness INTEGER NOT NULL ON CONFLICT REPLACE DEFAULT 100,
    excluded_from_search BOOLEAN NOT NULL ON CONFLICT REPLACE DEFAULT FALSE
);";
}

🔄 Implementation Process

Priorities

High Priority: Standardize module comments (//!)
Medium Priority: Unify function comments (///)
Low Priority: Update test documentation

Implementation Recommendations

Start with new files - Apply standards to new code
Gradual updates - Update existing files when they are modified
Compliance checking - Use cargo doc to verify documentation
Code review - Include documentation review in the review process

📚 Additional Resources

This document should be updated as the project evolves and documentation needs change.

Contributing

Thank you for your interest in contributing to kasl! This guide will help you get started.

Getting Started

Prerequisites

Rust: 1.70 or higher
Git: Latest version
SQLite: Development headers (usually included with Rust)
Platform-specific tools:
- Windows: Visual Studio Build Tools
- macOS: Xcode Command Line Tools
- Linux: Build essentials

Development Setup

Clone the repository:

git clone https://github.com/lacodda/kasl.git
cd kasl

Install dependencies:
```
cargo build
```

Run tests:

cargo test --lib --tests -- --test-threads=1

Build documentation:
```
cargo doc --open
```

Development Workflow

Code Style

Follow the Style Guide for all code contributions:

Documentation: Comprehensive module and function documentation
Formatting: Use rustfmt for consistent formatting
Linting: Address all clippy warnings
Tests: Write tests for new functionality

Branch Strategy

Create feature branch:

git checkout -b feature/your-feature-name

Make changes:
- Follow the style guide
- Write tests
- Update documentation

Test thoroughly:

cargo test --lib --tests -- --test-threads=1
cargo clippy
cargo fmt --check

Commit changes:

git add .
git commit -m "feat: add new feature description"

Push and create PR:

git push origin feature/your-feature-name

Commit Messages

Follow Conventional Commits:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes
refactor: Code refactoring
test: Test changes
chore: Maintenance tasks

Examples:

feat: add GitLab commit import functionality
fix: resolve database connection timeout issue
docs: update API integration guide
test: add comprehensive task management tests

Project Structure

Core Modules

src/main.rs: Application entry point
src/lib.rs: Library root and module organization
src/commands/: CLI command implementations
src/db/: Database layer and migrations
src/libs/: Core library functionality
src/api/: External API integrations

Key Components

Activity Monitor: src/libs/monitor.rs
Task Management: src/db/tasks.rs
Configuration: src/libs/config.rs
Database: src/db/db.rs
API Clients: src/api/

Testing

Unit Tests: In same file as implementation
Integration Tests: tests/ directory
Test Contexts: Use test-context crate for isolation

Development Guidelines

Code Quality

Documentation: Document all public APIs
Error Handling: Use anyhow for error propagation
Logging: Use tracing for structured logging
Testing: Aim for high test coverage
Performance: Profile and optimize critical paths

Database Changes

Migrations: Always create migrations for schema changes
Backward Compatibility: Maintain compatibility when possible
Testing: Test migrations thoroughly
Documentation: Update database documentation

API Integrations

Session Management: Implement the Session trait
Error Handling: Handle network and authentication errors
Rate Limiting: Respect API rate limits
Testing: Mock external APIs in tests

Configuration

Backward Compatibility: Don't break existing configurations
Validation: Validate configuration on load
Documentation: Update configuration documentation
Defaults: Provide sensible defaults

Testing

Running Tests

# All tests
cargo test --lib --tests -- --test-threads=1

# Specific test file
cargo test --test config

# Specific test
cargo test test_save_and_read_config

# With output
cargo test -- --nocapture

Test Guidelines

Isolation: Each test should be independent
Cleanup: Clean up after tests
Mocking: Mock external dependencies
Coverage: Test error conditions and edge cases

Test Contexts

Use test contexts for setup and teardown:

#![allow(unused)]
fn main() {
struct TestContext {
    temp_dir: TempDir,
}

impl TestContext {
    fn setup() -> Self {
        // Setup test environment
    }
    
    fn teardown(self) {
        // Cleanup
    }
}
}

Debugging

Debug Mode

Enable debug logging:

RUST_LOG=kasl=debug cargo run -- watch --foreground

Database Debugging

# Direct database access
sqlite3 ~/.local/share/lacodda/kasl/kasl.db

# Check migrations
kasl migrations status

Performance Profiling

# Build with profiling
cargo build --release

# Profile with perf (Linux)
perf record --call-graph=dwarf ./target/release/kasl watch
perf report

Building

Release Build

cargo build --release

Cross-Platform Build

# Windows
cargo build --release --target x86_64-pc-windows-msvc

# macOS
cargo build --release --target x86_64-apple-darwin

# Linux
cargo build --release --target x86_64-unknown-linux-gnu

Docker Build

docker build -t kasl .
docker run --rm kasl --version

Documentation

Code Documentation

Modules: Document with //! comments
Functions: Document with /// comments
Structs: Document fields and usage
Examples: Include usage examples

User Documentation

Commands: Document all CLI commands
Configuration: Document all options
Examples: Provide practical examples
Troubleshooting: Include common issues

Building Documentation

# Build docs
cargo doc

# Build book
cd docs
mdbook build
mdbook serve

Release Process

Version Management

Update version in Cargo.toml
Update changelog in CHANGELOG.md
Create release tag:
```
git tag v0.8.0
git push origin v0.8.0
```

Release Checklist

All tests pass
Documentation updated
Changelog updated
Version bumped
Release tag created
GitHub release created
Binaries uploaded

Getting Help

Resources

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: kasl.lacodda.com

Communication

Bug Reports: Use GitHub Issues
Feature Requests: Use GitHub Discussions
Questions: Use GitHub Discussions
Security: Email lahtachev@gmail.com

Code of Conduct

Our Standards

Be respectful and inclusive
Focus on constructive feedback
Help others learn and grow
Respect different perspectives

Enforcement

Report violations to maintainers
Maintainers will address issues promptly
Consequences may include warnings or bans

License

By contributing to kasl, you agree that your contributions will be licensed under the MIT License.

Troubleshooting

This guide helps you resolve common issues with kasl.

kasl watch fails to start
No work sessions detected
Error messages about permissions

Solutions:

Check permissions:

# Linux/macOS
ls -la ~/.local/share/lacodda/kasl/

# Windows
dir "%LOCALAPPDATA%\lacodda\kasl"

Run in foreground for debugging:
```
kasl watch --foreground
```

Check for existing processes:

# Linux/macOS
ps aux | grep kasl

# Windows
tasklist | findstr kasl

Stop existing processes:
```
kasl watch --stop
```

Problem: False activity detection

Symptoms:

Work sessions start unexpectedly
Pauses not detected properly
Inconsistent timing

Solutions:

Adjust configuration:

kasl init  # Reconfigure monitor settings

Increase thresholds:

{
  "monitor": {
    "activity_threshold": 60,    // Increase from 30
    "pause_threshold": 120,      // Increase from 60
    "min_pause_duration": 30     // Increase from 20
  }
}

Check for background processes:

# Linux/macOS
ps aux | grep -E "(mouse|keyboard|input)"

Database Issues

Problem: Database locked

Symptoms:

"database is locked" errors
Cannot access data
Application crashes

Solutions:

Stop all kasl processes:
```
kasl watch --stop
```

Check file permissions:

# Linux/macOS
ls -la ~/.local/share/lacodda/kasl/kasl.db

# Windows
dir "%LOCALAPPDATA%\lacodda\kasl\kasl.db"

Fix permissions:

# Linux/macOS
chmod 600 ~/.local/share/lacodda/kasl/kasl.db
chmod 700 ~/.local/share/lacodda/kasl/

Check for corruption:

sqlite3 ~/.local/share/lacodda/kasl/kasl.db "PRAGMA integrity_check;"

Problem: Migration failures

Symptoms:

"migration failed" errors
Database schema issues
Application won't start

Solutions:

Check migration status:
```
kasl migrations status
```
View migration history:
```
kasl migrations history
```

Backup and reset:

# Backup current database
cp ~/.local/share/lacodda/kasl/kasl.db kasl_backup.db

# Remove database (will be recreated)
rm ~/.local/share/lacodda/kasl/kasl.db

# Restart kasl
kasl watch

Configuration Issues

Problem: Configuration not found

Symptoms:

"configuration not found" errors
Default settings used
Cannot save configuration

Solutions:

Check configuration location:

# Linux/macOS
ls -la ~/.local/share/lacodda/kasl/config.json

# Windows
dir "%LOCALAPPDATA%\lacodda\kasl\config.json"

Recreate configuration:
```
kasl init
```

Create directory manually:

# Linux/macOS
mkdir -p ~/.local/share/lacodda/kasl

# Windows
mkdir "%LOCALAPPDATA%\lacodda\kasl"

Problem: Invalid configuration

Symptoms:

"invalid configuration" errors
Application crashes on startup
Settings not applied

Solutions:

Validate JSON syntax:

# Using Python
python -m json.tool ~/.local/share/lacodda/kasl/config.json

# Using jq
jq . ~/.local/share/lacodda/kasl/config.json

Reset configuration:
```
kasl init --delete
kasl init
```

Check for syntax errors:

# Common issues:
# - Missing commas
# - Extra commas
# - Unquoted strings
# - Invalid JSON types

API Integration Issues

Problem: Authentication failures

Symptoms:

"authentication failed" errors
Cannot connect to APIs
Session expired messages

Solutions:

Clear cached sessions:

# Remove session files
rm ~/.local/share/lacodda/kasl/.gitlab_session
rm ~/.local/share/lacodda/kasl/.jira_session
rm ~/.local/share/lacodda/kasl/.si_session

Reconfigure integration:
```
kasl init
```
Check credentials:
- Verify API tokens are valid
- Check username/password
- Confirm API URLs

Test connectivity:

# Test GitLab
curl -H "Authorization: Bearer YOUR_TOKEN" https://gitlab.com/api/v4/user

# Test Jira
curl -u "username:password" https://jira.company.com/rest/api/2/myself

Problem: Network connectivity

Symptoms:

"connection failed" errors
Timeout errors
Cannot reach APIs

Solutions:

Check network connectivity:

# Test basic connectivity
ping gitlab.com
ping jira.company.com

# Test HTTPS
curl -I https://gitlab.com

Check proxy settings:

# Set proxy environment variables
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

Check firewall settings:
- Ensure outbound HTTPS (443) is allowed
- Check corporate firewall rules
- Verify VPN connection if required

Task Management Issues

Problem: Tasks not found

Symptoms:

Empty task lists
"task not found" errors
Tasks not saving

Solutions:

Check database:

sqlite3 ~/.local/share/lacodda/kasl/kasl.db "SELECT * FROM tasks;"

Verify task creation:

# Create test task
kasl task --name "Test task" --completeness 0

# List tasks
kasl task --show

Check for database issues:

sqlite3 ~/.local/share/lacodda/kasl/kasl.db "PRAGMA integrity_check;"

Problem: Tag issues

Symptoms:

Tags not saving
Tag associations lost
Tag filtering not working

Solutions:

Check tag tables:

sqlite3 ~/.local/share/lacodda/kasl/kasl.db "SELECT * FROM tags;"
sqlite3 ~/.local/share/lacodda/kasl/kasl.db "SELECT * FROM task_tags;"

Recreate tags:

kasl tag create --name "test" --color "red"
kasl tag list

Check foreign key constraints:

sqlite3 ~/.local/share/lacodda/kasl/kasl.db "PRAGMA foreign_keys = ON;"

Report Issues

Problem: Reports not generating

Symptoms:

Empty reports
Missing data
Report generation errors

Solutions:

Check workday data:

sqlite3 ~/.local/share/lacodda/kasl/kasl.db "SELECT * FROM workdays ORDER BY date DESC LIMIT 5;"

Check pause data:

sqlite3 ~/.local/share/lacodda/kasl/kasl.db "SELECT * FROM pauses ORDER BY start DESC LIMIT 5;"

Generate report manually:
```
kasl report --last
```

Problem: Report submission failures

Symptoms:

"report send failed" errors
Reports not reaching server
Authentication issues

Solutions:

Check API configuration:

# Verify SiServer configuration
cat ~/.local/share/lacodda/kasl/config.json | jq .si

Test API connectivity:

# Test SiServer connection
curl -X POST https://api.company.com/health

Check authentication:

# Clear session and retry
rm ~/.local/share/lacodda/kasl/.si_session
kasl report --send

Debug Mode

Enable Debug Logging

# Enable debug mode
RUST_LOG=kasl=debug kasl watch --foreground

# Enable trace logging
RUST_LOG=kasl=trace kasl watch --foreground

# Enable SQLite logging
RUST_LOG=kasl=debug kasl report

Debug Information

Debug mode shows:

Configuration loading
Database operations
API requests/responses
Error details
Performance metrics

Common Debug Commands

# Check configuration
RUST_LOG=kasl=debug kasl init

# Debug task operations
RUST_LOG=kasl=debug kasl task --show

# Debug report generation
RUST_LOG=kasl=debug kasl report

# Debug API operations
RUST_LOG=kasl=debug kasl task --find

Performance Issues

High CPU Usage

Symptoms:

High CPU usage
System slowdown
Battery drain

Solutions:

Increase poll interval:

{
  "monitor": {
    "poll_interval": 1000  // Increase from 500
  }
}

Check for multiple instances:
```
ps aux | grep kasl
kasl watch --stop
```

Profile performance:

# Linux
perf record --call-graph=dwarf ./target/release/kasl watch
perf report

High Memory Usage

Symptoms:

High memory consumption
Memory leaks
Application crashes

Solutions:

Check memory usage:

# Linux/macOS
ps aux | grep kasl

# Windows
tasklist | findstr kasl

Restart application:
```
kasl watch --stop
kasl watch
```

Check for memory leaks:

# Use valgrind (Linux)
valgrind --leak-check=full ./target/release/kasl watch

Check Task Scheduler:
- Open Task Scheduler
- Look for kasl tasks
- Verify task is enabled

Check Registry:

reg query "HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run" /v kasl

Run as Administrator:
```
kasl autostart enable
```

Problem: Permission denied

Solutions:

Run as Administrator:
- Right-click Command Prompt
- "Run as administrator"
Check file permissions:
```
icacls "%LOCALAPPDATA%\lacodda\kasl"
```

macOS Issues

Problem: Input monitoring permissions

Solutions:

Grant Accessibility permissions:
- System Preferences → Security & Privacy → Privacy → Accessibility
- Add kasl to the list
Grant Input Monitoring permissions:
- System Preferences → Security & Privacy → Privacy → Input Monitoring
- Add kasl to the list

Problem: Autostart not working

Solutions:

Check LaunchAgents:
```
ls -la ~/Library/LaunchAgents/
```

Load LaunchAgent manually:

launchctl load ~/Library/LaunchAgents/com.lacodda.kasl.plist

Linux Issues

Problem: Input device access

Solutions:

Check user groups:
```
groups $USER
```
Add user to input group:
```
sudo usermod -a -G input $USER
```
Check device permissions:
```
ls -la /dev/input/
```

Problem: systemd service issues

Solutions:

Check service status:
```
systemctl --user status kasl
```

Enable service:

systemctl --user enable kasl
systemctl --user start kasl

Getting Help

Before Asking for Help

Check this guide for your specific issue
Enable debug logging and check output
Try the solutions provided above
Gather information about your system

Information to Provide

When reporting issues, include:

Operating system and version
kasl version (kasl --version)
Error messages (with debug logging)
Steps to reproduce
System configuration

Support Channels

GitHub Issues: https://github.com/lacodda/kasl/issues
Email: lahtachev@gmail.com
Documentation: https://kasl.lacodda.com

Keyboard shortcuts

kasl documentation