kimai-time-tracking

Files (3)

• SKILL.md
• _meta.json
• kimai_cli.py · scripts/

SKILL.md (first lines)

# Kimai Time Tracking Skill

Complete API integration for [Kimai](https://www.kimai.org/) time-tracking software. Enables full control over timesheets, projects, customers, activities, teams, invoices, and system configuration.

## When to use

**Activate this skill when the user requests:**
- Start/stop/restart time tracking (timers)
- List, filter, or export timesheets
- Manage customers, projects, or activities
- Create invoices or export data
- Administrative tasks (users, teams, rates)
- Query system status (version, plugins, config)

**Activation triggers:**
- Keywords: "kimai", "zeiterfassung", "timesheet", "timer", "stunden", "erfasse Zeit", "starte Tracking", "Projekt anlegen", "Rechnung erstellen"
- "Start tracking for project X"
- "Show my timesheets from last week"
- "Create new customer in Kimai"
- "Export timesheets to CSV"
- "List all active timers"
- "Stop current time tracking"

**Do NOT activate for:**
- General time questions ("What time is it?")
- Other time-tracking tools (Toggl, Clockify, etc.)
- Calendar/scheduling without Kimai context

## Environment Setup

**Required Environment Variables:**
- `KIMAI_BASE_URL` - Full URL to Kimai instance (e.g., `https://kimai.example.com`)
- `KIMAI_API_TOKEN` - Bearer token for authentication

**Optional:**
- `KIMAI_WORKSPACE` - Path for exports/temp files (defaults to `~/.openclaw/workspace/kimai`)

**API Permissions required depend on operation:**
- `view_own_timesheet`, `create_own_timesheet`, `edit_own_timesheet`, `delete_own_timesheet`
- `view_other_timesheet` (for viewing other users' entries)
- `view_customer`, `edit_customer`, `delete_customer`
- `view_project`, `edit_project`, `delete_project`
- `view_activity`, `edit_activity`, `delete_activity`
- `view_team`, `edit_team`, `create_team`, `delete_team`
- `view_invoice` (for invoice operations)
- `view_user` (for user management)

**Compatibility:** Requires Kimai 2.x with REST API enabled. Internet access required. Linux/macOS supported.

## Workflow

### 1. Quick Time Tracking

```bash
# List recent activities (to find project/activity IDs)
./scripts/kimai_cli.py timesheets recent

# Start tracking
./scripts/kimai_cli.py timesheets start --project 1 --activity 5 --description "Implementing API"

# Check active timers
./scripts/kimai_cli.py timesheets active

# Stop tracking
./scripts/kimai_cli.py timesheets stop --id 123
```

### 2. Data Management Workflow

```bash
# Create customer → Project → Activity hierarchy
./scripts/kimai_cli.py customers create --name "Acme Corp" --country DE --currency EUR --timezone Europe/Berlin
./scripts/kimai_cli.py projects create --name "Website Redesign" --customer 1
./scripts/kimai_cli.py activities create --name "Development" --project 1

# List with filters
./scripts/kimai_cli.py timesheets list --customer 1 --begin "2024-01-01T00:00:00" --exported 0
```

### 3. Export/Invoice Workflow

```bash
# Mark timesheets as exported (locks them)
./scripts/kimai_cli.py timesheets export --id 123

# List invoices
./scripts/kimai_cli.py invoices list --status pending --begin 2024-01-01T00:00:00
```

## CLI Tool Reference

Use `scripts/kimai_cli.py` for all operations. Structure follows API endpoints:

### Timesheets (`timesheets`)
- `list` - List entries (supports pagination, filters: user, customer, project, activity, tags, date range, exported status)
- `get <id>` - Fetch single entry
- `create` - Create manual entry or start timer (omit --end for active tracking)
- `update <id>` - Patch existing entry
- `delete <id>` - **Requires confirmation** (destructive)
- `stop <id>` - Stop active timer
- `restart <id>` - Restart finished entry (creates new)
- `duplicate <id>` - Copy entry (resets export status)
- `active` - List currently running timers
- `recent` - Recent unique working sets (last activity per project/activity combination)
- `export <id>` - Toggle export/lock status

### Customers (`customers`)
- `list` - List customers (filter: visible, term)
- `get <id>` - Fetch customer details
- `create` - Create new customer
- `update <id>` - Update customer
- `delete <id>` - **Requires confirmation** (cascades to projects/activities/timesheets)
- `meta <id>` - Update custom fields
- `rates <id>` - Manage customer-specific rates

### Projects (`projects`)
- `list` - List projects (filter: customer, visible, date range)
- `get <id>` - Fetch project
- `create` - Create project (requires customer ID)

From Trompetilla/Skills, MIT.

More from Trompetilla/Skills