Tag sessions by project

A Kimchi Coding session can carry default tags so that every request it makes is attributed to a project, team, or any other dimension. Once sessions are tagged, the console's Usage and Analytics pages can break usage and cost down by those tags.

This guide shows how to define default tags for a session and how to report on the result. It is written for team leads and engineering managers who need per-project usage and cost numbers. For tag format rules, limits, and the query API, see Tags.

Before you start

• The Kimchi CLI installed and authenticated. Default tags are resolved each time a session starts.
• A repository (or a parent directory covering several repositories) where you run Kimchi sessions.

How default tags are resolved

Kimchi resolves default tags from three sources, strongest first:

1. Environment: the KIMCHI_TAGS environment variable, comma-separated. Use this for temporary overrides or CI-specific behavior.
2. Project: the nearest ancestor .kimchi/tags.json from the working directory. The lookup walks up the tree, so subdirectories of a repository pick up the repository-level file.
3. Global: ~/.config/kimchi/tags.json. Use this for personal or machine-level defaults.

The sources are combined into one resolved set. When the same key appears in more than one tier, the stronger tier's value replaces the weaker one. Two tags with the same key within a single tier can coexist, so one project file can carry several values for the same key.

Default tags appear in /tags with their tier: [env], [project], or [global]. Tags you add during a session show as [user].

Define project tags in your repository

{
  "tags": [
    "project:heist",
    "team:capers"
  ]
}

mkdir -p .kimchi
cat > .kimchi/tags.json <<'EOF'
{
  "tags": [
    "project:heist",
    "team:capers"
  ]
}
EOF

Active tags:
  [project] project:heist
  [project] team:capers
Total: 2/10 tags

Set personal defaults

Tags you want for yourself, regardless of repository, go in ~/.config/kimchi/tags.json. Set them to whatever you want attached to every session you run, for example your own persona or team:

{
  "tags": [
    "persona:non-grata"
  ]
}

To create it:

mkdir -p ~/.config/kimchi
cat > ~/.config/kimchi/tags.json <<'EOF'
{
  "tags": [
    "persona:non-grata"
  ]
}
EOF

Global tags apply to every session, but lose to project and environment tags with the same key.

Override tags for a session or CI run

For a temporary override, such as a specific experiment, a CI run, or a one-off task, set KIMCHI_TAGS before starting the session:

export KIMCHI_TAGS="experiment:casing-the-joint,project:api"

Set the tags to whatever identifies that run. Environment tags are the strongest source while present and must be set per session. In CI, combine the variable with forced project trust so the run does not block on the trust prompt:

KIMCHI_TAGS="ci:true,team:capers" kimchi --approve

Limits and failure behavior

See Tags for the automatic model: and phase: tags, which are reserved and do not count toward the cap.

Report by project in the console

Every request carries its active tags, so the existing reporting pages answer per-project questions:

• Usage: filter by tag to see per-user and per-team rows for a project's requests, tokens, and cost.
• Analytics: filter by tag to track cost, request volume, latency, and error rate for a project.
• API: the tag query endpoints and CEL filter syntax pull per-project data programmatically.

For example, on the Usage page select your project:{name} tag in the Tags filter and set a 30-day range. Then sort by cost to see which project drives the most spend.

Quick reference

See also