Kimai Time Tracking Skill

Complete API integration for Kimai 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)
• INLINECODE2 - 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, INLINECODE8
• INLINECODE9 (for viewing other users' entries)
• INLINECODE10, edit_customer, INLINECODE12
• INLINECODE13, edit_project, INLINECODE15
• INLINECODE16, edit_activity, INLINECODE18
• INLINECODE19, edit_team, create_team, INLINECODE22
• INLINECODE23 (for invoice operations)
• INLINECODE24 (for user management)

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

Workflow

1. Quick Time Tracking

CODEBLOCK0

2. Data Management Workflow

CODEBLOCK1

3. Export/Invoice Workflow

CODEBLOCK2

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)
• INLINECODE28 - Fetch single entry
• INLINECODE29 - Create manual entry or start timer (omit --end for active tracking)
• INLINECODE30 - Patch existing entry
• INLINECODE31 - Requires confirmation (destructive)
• INLINECODE32 - Stop active timer
• INLINECODE33 - Restart finished entry (creates new)
• INLINECODE34 - Copy entry (resets export status)
• INLINECODE35 - List currently running timers
• INLINECODE36 - Recent unique working sets (last activity per project/activity combination)
• INLINECODE37 - Toggle export/lock status

Customers (customers)

• - list - List customers (filter: visible, term)
• INLINECODE40 - Fetch customer details
• INLINECODE41 - Create new customer
• INLINECODE42 - Update customer
• INLINECODE43 - Requires confirmation (cascades to projects/activities/timesheets)
• INLINECODE44 - Update custom fields
• INLINECODE45 - Manage customer-specific rates

Projects (projects)

• - list - List projects (filter: customer, visible, date range)
• INLINECODE48 - Fetch project
• INLINECODE49 - Create project (requires customer ID)
• INLINECODE50 - Update project
• INLINECODE51 - Requires confirmation (cascades to activities/timesheets)
• INLINECODE52 - Manage project rates

Activities (activities)

• - list - List activities (filter: project, visible, global only)
• INLINECODE55 - Fetch activity
• INLINECODE56 - Create activity (can be global or project-specific)
• INLINECODE57 - Update activity
• INLINECODE58 - Requires confirmation (cascades to timesheets)
• INLINECODE59 - Manage activity rates

Teams (teams)

• - list, get, create, update, INLINECODE65
• INLINECODE66 - Add team member
• INLINECODE67 - Remove member
• INLINECODE68 - Grant customer access
• INLINECODE69 - Grant project access
• INLINECODE70 - Grant activity access

Users (users)

• - list - List users (requires view_user permission)
• INLINECODE73 - Current user info
• INLINECODE74 - User details
• INLINECODE75 - Create user (admin)
• INLINECODE76 - Update user

Invoices (invoices)

• - list - List invoices (filter: date range, customer, status)
• INLINECODE79 - Invoice details

System (system)

• - ping - Test connectivity
• INLINECODE82 - Kimai version info
• INLINECODE83 - Installed plugins
• INLINECODE84 - Timesheet configuration
• INLINECODE85 - 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

CODEBLOCK3

List and export non-exported hours

CODEBLOCK4

Update custom fields (meta)

CODEBLOCK5

Create team and assign resources

CODEBLOCK6

Error Handling

Common HTTP codes:

• - 200 - Success
• INLINECODE98 - Created
• INLINECODE99 - No content (successful delete)
• INLINECODE100 - Bad request (validation error, missing fields)
• INLINECODE101 - Unauthorized (invalid/expired token)
• INLINECODE102 - Forbidden (insufficient permissions)
• INLINECODE103 - Not found (invalid ID)
• INLINECODE104 - 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:

CODEBLOCK7

Test API connectivity:

CODEBLOCK8

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)