Tags
Attach custom key:value metadata to Kimchi requests and slice usage, cost, and analytics by those tags across the console.
Tags let you attach custom key:value metadata to requests sent through Kimchi. Once attached, tags appear in the console's Usage and Analytics reporting pages, where you filter usage and cost data by any combination of tags.
Use tags to attribute spend and traffic to whatever dimension your organization tracks: a project, a team, an environment, an experiment, a cost center. They are the link between how requests are made and how you report on them.
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 CLI 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: you 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 (.) |
Valid examples:
env:prod,team:capers,persona:non-grata,project.v2:run-42
Managing tags with /tags
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 |
Tags added with /tags add are saved to ~/.config/kimchi/tags.json and persist across sessions. They remain active until you explicitly remove them with /tags remove or /tags clear.
Static tags set via the
KIMCHI_TAGSenvironment variable cannot be modified with/tags. Only user-defined tags (added with/tags add) can be removed this way.
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. It is reserved and does not count toward the 10-tag cap. |
Automatic phase: tag | When a session's work phase is set (explore, plan, build, review, research), Kimchi adds phase:{phase}. It is a reserved tag and does not count toward the cap. It appears only while a phase is active. |
Tag query API
Three endpoints let you look up tags used across your organization. All endpoints require authentication via 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" |
Expressions can be combined freely. For example, to match production requests that have any experiment tag:
tags["env"] == "prod" && "experiment" in tagsFilter reporting by tags
After requests carry tags, use the Tags filter on the Usage and Analytics pages to break down usage and cost data by any tag. To get per-project rows there, tag sessions by project: see Tag sessions by project.
See also
Updated 7 days ago