--- name: kimai-time-tracking description: Complete Kimai time-tracking API integration. Manage timesheets, customers, projects, activities, teams, invoices and exports via REST API. Supports time tracking workflows, reporting, and administrative operations. Keywords - kimai, zeiterfassung, timesheet, tracking, project, customer, activity, invoice, export, timer, stunden --- # 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 ` - Fetch single entry - `create` - Create manual entry or start timer (omit --end for active tracking) - `update ` - Patch existing entry - `delete ` - **Requires confirmation** (destructive) - `stop ` - Stop active timer - `restart ` - Restart finished entry (creates new) - `duplicate ` - Copy entry (resets export status) - `active` - List currently running timers - `recent` - Recent unique working sets (last activity per project/activity combination) - `export ` - Toggle export/lock status ### Customers (`customers`) - `list` - List customers (filter: visible, term) - `get ` - Fetch customer details - `create` - Create new customer - `update ` - Update customer - `delete ` - **Requires confirmation** (cascades to projects/activities/timesheets) - `meta ` - Update custom fields - `rates ` - Manage customer-specific rates ### Projects (`projects`) - `list` - List projects (filter: customer, visible, date range) - `get ` - Fetch project - `create` - Create project (requires customer ID) - `update ` - Update project - `delete ` - **Requires confirmation** (cascades to activities/timesheets) - `rates ` - Manage project rates ### Activities (`activities`) - `list` - List activities (filter: project, visible, global only) - `get ` - Fetch activity - `create` - Create activity (can be global or project-specific) - `update ` - Update activity - `delete ` - **Requires confirmation** (cascades to timesheets) - `rates ` - Manage activity rates ### Teams (`teams`) - `list`, `get`, `create`, `update`, `delete` - `member-add

` - Add team member - `member-remove

` - Remove member - `grant-customer

` - Grant customer access - `grant-project

` - Grant project access - `grant-activity

` - Grant activity access ### Users (`users`) - `list` - List users (requires view_user permission) - `me` - Current user info - `get ` - User details - `create` - Create user (admin) - `update ` - Update user ### Invoices (`invoices`) - `list` - List invoices (filter: date range, customer, status) - `get ` - Invoice details ### System (`system`) - `ping` - Test connectivity - `version` - Kimai version info - `plugins` - Installed plugins - `config` - Timesheet configuration - `colors` - Color codes ## Safety & Boundaries **⚠️ DESTRUCTIVE OPERATIONS** - `delete` operations on customers, projects, activities, timesheets, teams, or tags **require explicit user confirmation**. - Deleting customers cascades to all linked projects, activities, and timesheets [1]. - Deleting projects cascades to activities and timesheets [1]. - The CLI will show a preview of affected data and require "yes" confirmation. **API Security:** - API token is passed via `Authorization: Bearer` header [1]. - Token is never logged or stored in CLI output. - Use `--dry-run` flag for testing (simulates API calls without executing). **Rate Limiting & Pagination:** - API returns paginated results (default 50 items) [1]. - CLI auto-handles pagination for `list` commands (fetches all pages or respects `--limit`). - Use `--page` and `--size` for manual pagination control. **Data Privacy:** - Timesheet data may contain sensitive information. - Export files are saved to workspace with restricted permissions (600). - Redact personal data (emails, names) when sharing debug output. **Workspace Safety:** - All file exports (CSV, JSON) default to `KIMAI_WORKSPACE` or `~/.openclaw/workspace/kimai`. - Never write to system directories outside workspace without explicit confirmation. ## Input/Output Specifications **Inputs:** - Entity IDs (integers) - ISO 8601 datetime strings (YYYY-MM-DDTHH:mm:ss) - JSON data for create/update operations (via --json file or CLI args) - Filter parameters (customer, project, activity IDs, date ranges, visibility) **Outputs:** - JSON (default, pipe-friendly) - Table format (`--format table` for human readability) - CSV (`--format csv` for exports) - Exit codes: 0 (success), 1 (API error), 2 (validation error), 3 (cancelled by user) **Success Criteria:** - HTTP 200/201 for successful operations - Valid JSON response structure matching API schemas [1] - For exports: File created in workspace with expected record count ## Examples ### Start tracking with description ```bash ./scripts/kimai_cli.py timesheets create \ --project 5 \ --activity 12 \ --description "Client meeting - requirements analysis" \ --tags "meeting,urgent" ``` ### List and export non-exported hours ```bash # Find billable hours not yet exported ./scripts/kimai_cli.py timesheets list \ --exported 0 \ --billable 1 \ --begin "2024-01-01T00:00:00" \ --end "2024-01-31T23:59:59" \ --format csv > january_hours.csv ``` ### Update custom fields (meta) ```bash ./scripts/kimai_cli.py customers meta 42 \ --name "order_number" \ --value "PO-2024-001" ``` ### Create team and assign resources ```bash ./scripts/kimai_cli.py teams create --name "Development Team" --members '[{"user": 1, "teamlead": true}]' ./scripts/kimai_cli.py teams grant-project 1 5 ``` ## Error Handling **Common HTTP codes:** - `200` - Success - `201` - Created - `204` - No content (successful delete) - `400` - Bad request (validation error, missing fields) - `401` - Unauthorized (invalid/expired token) - `403` - Forbidden (insufficient permissions) - `404` - Not found (invalid ID) - `409` - Conflict (overlapping timesheet if not allowed by config) **CLI behavior:** - Validates required fields before API call (e.g., project+activity for timesheets [1]) - Pretty-prints validation errors from API - Suggests fixes (e.g., "Did you mean to use 'PATCH' instead of DELETE? Try setting visible=false to hide instead of delete") ## Validation Validate this skill using the Openclaw skills validator: ```bash skills-ref validate ./kimai-time-tracking ``` Test API connectivity: ```bash export KIMAI_BASE_URL="https://your-kimai.example.com" export KIMAI_API_TOKEN="your-api-token" ./kimai-time-tracking/scripts/kimai_cli.py system ping ``` ## References - Kimai REST API Docs: https://www.kimai.org/documentation/rest-api.html - Pagination Guide: https://www.kimai.org/documentation/api-pagination.html - API Spec: `references/api-reference.json` (complete OpenAPI schema)

kimai-time-tracking

Scan your own AI components