Kimai Time Tracking

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

Security Scan

The skill's code and instructions match the Kimai API integration it advertises, but there is an inconsistency between the registry metadata and the runtime requirements (the SKILL.md and script require Kimai credentials while the registry lists none); you should verify environment-variable handling and token scope before installing.

Purpose & Capability

Name/description, SKILL.md, and the included scripts/kimai_cli.py consistently implement a Kimai REST API client (timesheets, customers, projects, activities, teams, invoices, etc.). However the package metadata in the registry lists no required environment variables while the SKILL.md and script clearly require KIMAI_BASE_URL and KIMAI_API_TOKEN — this metadata mismatch is an incoherence that should be corrected or explained.

Instruction Scope

Runtime instructions and the CLI exclusively describe interacting with a Kimai instance via its REST API, starting/stopping timers, listing/exporting data, and performing administrative actions. The instructions do not ask the agent to read unrelated system files or to transmit data to endpoints outside of the configured KIMAI_BASE_URL.

Install Mechanism

No install spec is provided (instruction-only plus an included Python script). This is low-risk from an install perspective — nothing is downloaded from external URLs during install. The script will run with the agent's runtime permissions when invoked.

Credentials

The runtime requires only KIMAI_BASE_URL and KIMAI_API_TOKEN (and an optional KIMAI_WORKSPACE). Those are appropriate for a Kimai API client. The concern is the registry metadata did not declare these required env vars — that mismatch could confuse users and automated permission checks. Also verify you provide a least-privilege API token (limit admin scopes if possible).

Persistence & Privilege

The skill is not marked always:true and does not request persistent platform-level privileges. It does not modify other skills' configuration in the provided files. Model invocation/autonomy is allowed (platform default); this is normal but be mindful of the agent issuing API calls autonomously.

What to consider before installing

This skill appears to be a legitimate Kimai API client, but before installing: 1) confirm the registry metadata is corrected to list the required environment variables (KIMAI_BASE_URL and KIMAI_API_TOKEN); 2) only provide a Kimai token with the minimum permissions needed (avoid full admin tokens unless necessary); 3) review the full scripts/kimai_cli.py for any code paths that write files or invoke external hosts (the visible portion makes API calls only to the base URL); 4) run the CLI in a sandbox or with isolated credentials first; and 5) ask the publisher/maintainer for provenance (homepage/source) since the registry lists unknown/none — that helps establish trust. If you need higher assurance, request a line-by-line review of the entire script and any truncated sections.

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)
• 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

# 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

# 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

# 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)
• update <id> - Update project
• delete <id> - Requires confirmation (cascades to activities/timesheets)
• rates <id> - Manage project rates

Activities (activities)

• list - List activities (filter: project, visible, global only)
• get <id> - Fetch activity
• create - Create activity (can be global or project-specific)
• update <id> - Update activity
• delete <id> - Requires confirmation (cascades to timesheets)
• rates <id> - Manage activity rates

Teams (teams)

• list, get, create, update, delete
• member-add <team-id> <user-id> - Add team member
• member-remove <team-id> <user-id> - Remove member
• grant-customer <team-id> <customer-id> - Grant customer access
• grant-project <team-id> <project-id> - Grant project access
• grant-activity <team-id> <activity-id> - Grant activity access

Users (users)

• list - List users (requires view_user permission)
• me - Current user info
• get <id> - User details
• create - Create user (admin)
• update <id> - Update user

Invoices (invoices)

• list - List invoices (filter: date range, customer, status)
• get <id> - 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

./scripts/kimai_cli.py timesheets create \
  --project 5 \
  --activity 12 \
  --description "Client meeting - requirements analysis" \
  --tags "meeting,urgent"

List and export non-exported hours

# 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)

./scripts/kimai_cli.py customers meta 42 \
  --name "order_number" \
  --value "PO-2024-001"

Create team and assign resources

./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:

skills-ref validate ./kimai-time-tracking

Test API connectivity:

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)