Tags
Attach key:value metadata to requests, then filter or compare usage, cost, and analytics by project, environment, team, or another reporting dimension.
Tags attach custom key:value metadata to requests sent through Kimchi. Use the Usage and Analytics filters to report on those requests by project, environment, experiment, cost center, or another dimension you choose.
For chargeback reporting, apply a consistent key and set of values to every relevant request. For example, use a tag such as project:checkout to group requests for one project.
Tags do not change native ownership. A team:platform tag does not set a request's native team ID, change a user's membership, or assign a team budget. A user:alice tag creates a reporting grouping; it does not authenticate Alice or assign native user ownership.
How tags get onto requests
Tags reach a request in one of two ways, and both surfaces feed the same console filters:
- Coding sessions: the Kimchi TUI resolves default tags from your environment, repository, and global config. It applies them to every request in the session. See Tag sessions by project to set this up.
- Direct API requests: pass tags in the request body or an HTTP header. See Tag API requests.
Tag format
Tags follow a key:value format validated against the following pattern:
^[a-zA-Z0-9]([a-zA-Z0-9._-]*[a-zA-Z0-9])?:[a-zA-Z0-9]([a-zA-Z0-9._@-]*[a-zA-Z0-9])?$| Constraint | Limit |
|---|---|
| Format | key:value |
| Key length | 1-64 characters |
| Value length | 1-64 characters |
| Tags per request | 10 maximum |
| First/last character | Must be alphanumeric (a-z, A-Z, 0-9) |
| Interior characters | Letters, numbers, hyphens (-), underscores (_), dots (.), and @ inside a direct API tag value |
The gateway allows @ inside a value, not at its start or end.
The /tags command in Kimchi TUI rejects @ in tag keys and values. To reuse a tag in direct API requests and Coding sessions, avoid @ so both surfaces accept it.
Valid examples:
env:prod,team:capers,persona:non-grata,project.v2:run-42,user:[email protected]through the gateway
Manage tags with the /tags command
Inside a Kimchi Coding session, use the /tags command to view and change the active tags:
| Command | What it does |
|---|---|
/tags | List all currently active tags |
/tags add key:value ... | Add one or more tags |
/tags remove tag ... | Remove one or more user-defined tags |
/tags clear | Remove all user-defined tags at once |
The TUI saves tags added with /tags add to ~/.config/kimchi/tags.json. They persist across sessions until you remove them with /tags remove or /tags clear.
The
/tagscommand cannot modify static tags from theKIMCHI_TAGSenvironment variable. It can remove only user-defined tags that you added with/tags add.
Limits and automatic tags
| Rule | Behavior |
|---|---|
| 10 tags per request | The cap counts resolved defaults plus session tags. /tags add fails with an error when the set is full. |
Automatic model: tag | Kimchi adds model:{model_id} to every request automatically. Kimchi reserves this tag and excludes it from the 10-tag cap. |
Automatic phase: tag | Kimchi adds phase:{phase} only while a session's phase is active (explore, plan, build, review, research). Kimchi reserves this tag and excludes it from the cap. |
Tag query API
Three endpoints let you look up tags used across your organization. All endpoints require authentication through the X-API-Key header and return at most 50 results.
| Endpoint | Description |
|---|---|
SearchTagKeys | Returns tag keys used in your organization, ranked by popularity. Supports filtering by key prefix. |
SearchTagValues | Returns values for a specific tag key, ranked by popularity. Supports filtering by value prefix. |
SearchTags | Returns full key:value tag combinations, ranked by popularity. Supports filtering by key prefix. |
CEL filter syntax
The GenerateAnalytics and GenerateLatestInferenceSummaries API endpoints accept a filter field that uses CEL (Common Expression Language) syntax to narrow results by tag.
| Expression | Meaning | Example |
|---|---|---|
tags["key"] == "value" | Match requests with an exact key:value tag | tags["env"] == "prod" |
"key" in tags | Match requests that have any value for the key | "env" in tags |
expr1 && expr2 | Combine multiple conditions with AND | tags["env"] == "prod" && tags["team"] == "capers" |
The following expression combines two conditions. It matches production requests that have any experiment tag:
tags["env"] == "prod" && "experiment" in tagsFilter and compare tags
In Usage → By user and Usage → By team, use Tags to select the key:value tags to include. The Teams filter remains a separate native-team control.
Select tags
Open Usage → By tag. Select at least two full key:value tags under Select tags to compare.
Compare the tags
Select Compare, then use Requests, Tokens, and Cost to inspect the comparison.
A request with multiple selected tags can appear under more than one row. Do not add the individual rows to calculate an organization total. See Compare tags.
For programmatic chargeback reporting, use Generate Cost Breakdown by Dimension with dimension=BREAKDOWN_DIMENSION_TAG_KEY and your chosen tagKey. This groups records by a custom tag without changing native ownership.
Related resources
Updated about 17 hours ago