KosmoKrator

productivity

Kimai Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Kimai KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.kimai.*. Use lua_read_doc("integrations.kimai") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Kimai workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.kimai.list_timesheets({page = 1, size = 1, user = "example_user", project = 1, begin = "example_begin", end = "example_end", state = "example_state"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("kimai"))' --json
kosmo integrations:lua --eval 'print(docs.read("kimai.list_timesheets"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua 
local kimai = app.integrations.kimai
local result = kimai.list_timesheets({page = 1, size = 1, user = "example_user", project = 1, begin = "example_begin", end = "example_end", state = "example_state"})

dump(result)
Run the workflow 
kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json
Namespace note. integrations:lua exposes app.integrations.kimai, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.kimai.default.* or app.integrations.kimai.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Kimai, use the narrower mcp:lua command.

MCP Lua command 
# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Kimai — Lua API Reference

list_timesheets

List time-tracking entries with optional filters.

Parameters

NameTypeRequiredDescription
pageintegernoPage number for pagination (default: 1)
sizeintegernoNumber of results per page (default: 50)
userstringnoFilter by user ID or username
projectintegernoFilter by project ID
beginstringnoFilter start date (ISO 8601, e.g., "2025-01-01T00:00:00")
endstringnoFilter end date (ISO 8601, e.g., "2025-01-31T23:59:59")
statestringnoFilter by state: "running" or "stopped"

Examples

-- List recent timesheets
local result = app.integrations.kimai.list_timesheets({
  size = 10
})

for _, entry in ipairs(result) do
  print(entry.id .. ": " .. entry.description)
end

-- Filter by project and date range
local result = app.integrations.kimai.list_timesheets({
  project = 5,
  begin = "2025-01-01T00:00:00",
  end = "2025-01-31T23:59:59"
})

get_timesheet

Get details of a specific timesheet entry.

Parameters

NameTypeRequiredDescription
idintegeryesThe timesheet entry ID

Example

local result = app.integrations.kimai.get_timesheet({ id = 42 })
print("Duration: " .. result.duration .. " seconds")

create_timesheet

Create a new time-tracking entry.

Parameters

NameTypeRequiredDescription
beginstringyesStart time (ISO 8601, e.g., "2025-01-15T09:00:00")
endstringnoEnd time (ISO 8601). Omit to start a running timer.
projectintegeryesProject ID to associate
activityintegernoActivity ID to categorize the entry
descriptionstringnoDescription of the work performed

Examples

-- Create a completed time entry
local result = app.integrations.kimai.create_timesheet({
  begin = "2025-01-15T09:00:00",
  end = "2025-01-15T17:00:00",
  project = 3,
  activity = 7,
  description = "Implementing login feature"
})

-- Start a running timer
local result = app.integrations.kimai.create_timesheet({
  begin = "2025-01-15T09:00:00",
  project = 3
})

list_projects

List projects with optional filters.

Parameters

NameTypeRequiredDescription
pageintegernoPage number (default: 1)
sizeintegernoResults per page (default: 50)
customerintegernoFilter by customer ID
visibleintegernoVisibility: 1 = visible, 2 = hidden, 3 = all

Example

local result = app.integrations.kimai.list_projects({
  customer = 2,
  visible = 1
})

get_project

Get details of a specific project.

Parameters

NameTypeRequiredDescription
idintegeryesThe project ID

Example

local result = app.integrations.kimai.get_project({ id = 5 })
print("Project: " .. result.name .. " (Customer: " .. result.customer.name .. ")")

list_customers

List customers with optional filters.

Parameters

NameTypeRequiredDescription
pageintegernoPage number (default: 1)
sizeintegernoResults per page (default: 50)
visibleintegernoVisibility: 1 = visible, 2 = hidden, 3 = all

Example

local result = app.integrations.kimai.list_customers({ visible = 1 })
for _, customer in ipairs(result) do
  print(customer.id .. ": " .. customer.name)
end

get_current_user

Get the currently authenticated user profile. Takes no parameters.

Example

local result = app.integrations.kimai.get_current_user({})
print("Logged in as: " .. result.displayName)

Multi-Account Usage

If you have multiple Kimai accounts configured, use account-specific namespaces:

-- Default account (always works)
app.integrations.kimai.function_name({...})

-- Explicit default (portable across setups)
app.integrations.kimai.default.function_name({...})

-- Named accounts
app.integrations.kimai.work.function_name({...})
app.integrations.kimai.freelance.function_name({...})

All functions are identical across accounts — only the credentials differ.

Raw agent markdown 
# Kimai — Lua API Reference

## list_timesheets

List time-tracking entries with optional filters.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number for pagination (default: 1) |
| `size` | integer | no | Number of results per page (default: 50) |
| `user` | string | no | Filter by user ID or username |
| `project` | integer | no | Filter by project ID |
| `begin` | string | no | Filter start date (ISO 8601, e.g., `"2025-01-01T00:00:00"`) |
| `end` | string | no | Filter end date (ISO 8601, e.g., `"2025-01-31T23:59:59"`) |
| `state` | string | no | Filter by state: `"running"` or `"stopped"` |

### Examples

```lua
-- List recent timesheets
local result = app.integrations.kimai.list_timesheets({
  size = 10
})

for _, entry in ipairs(result) do
  print(entry.id .. ": " .. entry.description)
end

-- Filter by project and date range
local result = app.integrations.kimai.list_timesheets({
  project = 5,
  begin = "2025-01-01T00:00:00",
  end = "2025-01-31T23:59:59"
})
```

---

## get_timesheet

Get details of a specific timesheet entry.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | yes | The timesheet entry ID |

### Example

```lua
local result = app.integrations.kimai.get_timesheet({ id = 42 })
print("Duration: " .. result.duration .. " seconds")
```

---

## create_timesheet

Create a new time-tracking entry.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `begin` | string | yes | Start time (ISO 8601, e.g., `"2025-01-15T09:00:00"`) |
| `end` | string | no | End time (ISO 8601). Omit to start a running timer. |
| `project` | integer | yes | Project ID to associate |
| `activity` | integer | no | Activity ID to categorize the entry |
| `description` | string | no | Description of the work performed |

### Examples

```lua
-- Create a completed time entry
local result = app.integrations.kimai.create_timesheet({
  begin = "2025-01-15T09:00:00",
  end = "2025-01-15T17:00:00",
  project = 3,
  activity = 7,
  description = "Implementing login feature"
})

-- Start a running timer
local result = app.integrations.kimai.create_timesheet({
  begin = "2025-01-15T09:00:00",
  project = 3
})
```

---

## list_projects

List projects with optional filters.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number (default: 1) |
| `size` | integer | no | Results per page (default: 50) |
| `customer` | integer | no | Filter by customer ID |
| `visible` | integer | no | Visibility: 1 = visible, 2 = hidden, 3 = all |

### Example

```lua
local result = app.integrations.kimai.list_projects({
  customer = 2,
  visible = 1
})
```

---

## get_project

Get details of a specific project.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | yes | The project ID |

### Example

```lua
local result = app.integrations.kimai.get_project({ id = 5 })
print("Project: " .. result.name .. " (Customer: " .. result.customer.name .. ")")
```

---

## list_customers

List customers with optional filters.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number (default: 1) |
| `size` | integer | no | Results per page (default: 50) |
| `visible` | integer | no | Visibility: 1 = visible, 2 = hidden, 3 = all |

### Example

```lua
local result = app.integrations.kimai.list_customers({ visible = 1 })
for _, customer in ipairs(result) do
  print(customer.id .. ": " .. customer.name)
end
```

---

## get_current_user

Get the currently authenticated user profile. Takes no parameters.

### Example

```lua
local result = app.integrations.kimai.get_current_user({})
print("Logged in as: " .. result.displayName)
```

---

## Multi-Account Usage

If you have multiple Kimai accounts configured, use account-specific namespaces:

```lua
-- Default account (always works)
app.integrations.kimai.function_name({...})

-- Explicit default (portable across setups)
app.integrations.kimai.default.function_name({...})

-- Named accounts
app.integrations.kimai.work.function_name({...})
app.integrations.kimai.freelance.function_name({...})
```

All functions are identical across accounts — only the credentials differ.
Metadata-derived Lua example 
local result = app.integrations.kimai.list_timesheets({page = 1, size = 1, user = "example_user", project = 1, begin = "example_begin", end = "example_end", state = "example_state"})
print(result)

Functions

list_timesheets Read

List time-tracking entries from Kimai. Supports filtering by user, project, date range, and state. Returns paginated results with timesheet details including duration, description, and associated project/activity.

Lua path
app.integrations.kimai.list_timesheets
Full name
kimai.kimai_list_timesheets
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
size integer no Number of results per page (default: 50).
user string no Filter by user ID or username.
project integer no Filter by project ID.
begin string no Filter start date (ISO 8601, e.g., "2025-01-01T00:00:00"). Only entries starting on or after this date.
end string no Filter end date (ISO 8601, e.g., "2025-01-31T23:59:59"). Only entries starting before or on this date.
state string no Filter by state: "running" for active timers, "stopped" for completed entries. Omit for all.
get_timesheet Read

Get details of a specific timesheet entry from Kimai. Returns the full timesheet record including begin/end timestamps, duration, description, project, activity, and user information.

Lua path
app.integrations.kimai.get_timesheet
Full name
kimai.kimai_get_timesheet
ParameterTypeRequiredDescription
id integer yes The timesheet entry ID.
create_timesheet Write

Create a new time-tracking entry in Kimai. Requires a begin timestamp and at least a project ID. Optionally specify an end time, activity, and description to categorize the time entry.

Lua path
app.integrations.kimai.create_timesheet
Full name
kimai.kimai_create_timesheet
ParameterTypeRequiredDescription
begin string yes Start time in ISO 8601 format (e.g., "2025-01-15T09:00:00").
end string no End time in ISO 8601 format (e.g., "2025-01-15T17:00:00"). Omit to start a running timer.
project integer yes The project ID to associate the time entry with.
activity integer no The activity ID to categorize the time entry (e.g., "Development", "Meeting").
description string no A description of the work performed during this time entry.
list_projects Read

List projects from Kimai. Supports filtering by customer and visibility. Returns project details including name, customer, budget, and time budget information.

Lua path
app.integrations.kimai.list_projects
Full name
kimai.kimai_list_projects
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
size integer no Number of results per page (default: 50).
customer integer no Filter by customer ID to list only projects for a specific customer.
visible integer no Visibility filter: 1 for visible projects only, 2 for hidden, 3 for all.
get_project Read

Get details of a specific project from Kimai. Returns the full project record including name, customer, comment, budget, time budget, and visibility status.

Lua path
app.integrations.kimai.get_project
Full name
kimai.kimai_get_project
ParameterTypeRequiredDescription
id integer yes The project ID.
list_customers Read

List customers from Kimai. Supports filtering by visibility. Returns customer details including name, company, contact information, and associated project count.

Lua path
app.integrations.kimai.list_customers
Full name
kimai.kimai_list_customers
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
size integer no Number of results per page (default: 50).
visible integer no Visibility filter: 1 for visible customers only, 2 for hidden, 3 for all.
get_current_user Read

Get the profile of the currently authenticated Kimai user. Returns user details including username, display name, email, timezone, and language preferences.

Lua path
app.integrations.kimai.get_current_user
Full name
kimai.kimai_get_current_user
ParameterTypeRequiredDescription
No parameters.