toggl

# Toggl Plugin

Toggl time tracking integration for Claude Code - manage time entries and generate productivity reports.

## Features

- **Timer Control**: Start and stop time entries with descriptions and projects
- **Smart Reports**: Daily, weekly, and project-based time summaries
- **Project Tracking**: Organize time by projects and workspaces
- **Intelligent Caching**: Fast performance with automatic data caching

## Installation

```bash
claude /plugin install ./plugins/toggl
```

## Configuration

Set the following environment variable:

```bash
export TOGGL_API_TOKEN="your-api-token"
```

### Getting an API Token

1. Log into your Toggl account
2. Go to Profile Settings
3. Find "API Token" at the bottom
4. Copy the token

## Commands

| Command | Description |
| ------- | ----------- |
| `/time-start [description]` | Start a new timer |
| `/time-stop` | Stop the current timer |
| `/time-report [period]` | Generate time report |

## Available MCP Tools

- `toggl_start_timer` - Start a new time entry
- `toggl_stop_timer` - Stop current timer
- `toggl_get_current_entry` - Check running timer
- `toggl_get_time_entries` - Get entries with date range
- `toggl_daily_report` - Daily breakdown
- `toggl_weekly_report` - Weekly summary
- `toggl_project_summary` - Hours by project
- `toggl_workspace_summary` - Hours by workspace
- `toggl_list_workspaces` - List workspaces
- `toggl_list_projects` - List projects
- `toggl_list_clients` - List clients
- `toggl_check_auth` - Verify connection
- `toggl_warm_cache` - Pre-load data for performance

## Example Usage

```text
# Start tracking
/time-start Working on authentication feature

# Stop current timer
/time-stop

# View today's work
/time-report today

# Weekly summary
/time-report week

# Natural language
"What am I working on right now?"
"How many hours did I work this week?"
"Start a timer for code review"
```

## Report Periods

- `today` - Current day
- `yesterday` - Previous day
- `week` - Current week (Mon-Sun)
- `last-week` - Previous week
- `month` - Current month

## License

MIT