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)