---
summary: "Kimi provider notes: cookie auth, quotas, and rate-limit parsing."
read_when:
  - Adding or modifying the Kimi provider
  - Debugging Kimi cookie import or usage parsing
  - Adjusting Kimi menu labels or settings
---

# Kimi Code Provider

Tracks usage for [Kimi For Coding](https://www.kimi.com/code) in CodexBar.

Kimi Code is distinct from the Moonshot/Kimi Open Platform. China-issued Open Platform keys and balance
belong under **Moonshot / Kimi Open Platform** with the China mainland region selected; they are not Kimi
Code subscription credentials.

## Features

- Displays weekly request quota (from membership tier)
- Shows current 5-hour rate limit usage
- Enriches Code API/CLI usage with the monthly membership pool when a web session is available
- API-key, Kimi Code CLI, automatic cookie, and manual cookie authentication methods
- Automatic refresh countdown

## Setup

Choose one of four authentication methods:

### Method 1: Kimi Code API Key (Recommended)

Create an API key in the [Kimi Code Console](https://www.kimi.com/code/console), then save it in CodexBar:

```bash
codexbar config set-api-key --provider kimi --api-key "kimi-api-key-here"
```

Or provide it through the environment:

```bash
export KIMI_CODE_API_KEY="kimi-code-api-key-here"
```

CodexBar calls `GET https://api.kimi.com/coding/v1/usages` with the API key. Set
`KIMI_CODE_BASE_URL` only when testing a compatible HTTPS proxy or alternate host with an explicit API key.
CodexBar never forwards a Kimi Code CLI credential to an endpoint override.

### Method 2: Kimi Code CLI

If you are signed in with the official Kimi Code CLI, Auto mode can reuse its fresh access token from
`~/.kimi-code/credentials/kimi-code.json`. CodexBar sends the same device identity headers as the CLI,
including the local hostname, OS details, and stable `~/.kimi-code/device_id` value. If that device ID is
missing, CodexBar creates it with private file permissions to match the official client.

CodexBar treats CLI-owned authentication as read-only: it never uses the refresh token and never rewrites
the credential file. When the access token expires, sign in again with Kimi Code CLI or configure an API
key. Set `KIMI_CODE_HOME` only when the official CLI uses a non-default home directory.

Custom `KIMI_CODE_BASE_URL`, `KIMI_CODE_OAUTH_HOST`, and `KIMI_OAUTH_HOST` values disable CLI credential
reuse; use an explicit API key for endpoint-override testing.

### Method 3: Automatic Browser Import

**No setup needed!** If you're already logged in to Kimi in Arc, Chrome, Safari, Edge, Brave, or Chromium:

1. Open CodexBar settings → Providers → Kimi
2. Set "Cookie source" to "Automatic"
3. Enable the Kimi provider toggle
4. CodexBar will automatically find your session

**Note**: Requires Full Disk Access to read browser cookies (System Settings → Privacy & Security → Full Disk Access → CodexBar).

Automatic mode also checks the official Kimi Desktop app before importing browser cookies. Its Chromium
Cookies database is opened read-only: active WAL databases use SQLite's normal WAL-aware path, while idle
WAL-mode databases with no sidecars use an immutable read-only fallback. CodexBar never creates or modifies
Kimi Desktop database files.

### Method 4: Manual Token Entry

For advanced users or when automatic import fails:

1. Open CodexBar settings → Providers → Kimi
2. Set "Cookie source" to "Manual"
3. Visit `https://www.kimi.com/code/console` in your browser
4. Open Developer Tools (F12 or Cmd+Option+I)
5. Go to **Application** → **Cookies**
6. Copy the `kimi-auth` cookie value (JWT token)
7. Paste it into the "Auth Token" field in CodexBar

### Cookie Environment Variable

Alternatively, set the `KIMI_AUTH_TOKEN` environment variable:

```bash
export KIMI_AUTH_TOKEN="jwt-token-here"
```

## Authentication Priority

When multiple sources are available, CodexBar uses this order:

1. API key (`providers[].apiKey` or `KIMI_CODE_API_KEY`) in Auto mode
2. Fresh Kimi Code CLI access token (`~/.kimi-code/credentials/kimi-code.json`)
3. Manual cookie/token (from Settings UI) when web fallback is used
4. Cookie environment variable (`KIMI_AUTH_TOKEN`)
5. Kimi Desktop `kimi-auth` cookie
6. Browser cookies (Arc → Chrome → Safari → Edge → Brave → Chromium)

For Code API and CLI results, sources 3–6 are best-effort enrichment only: the required Code usage remains
available if the membership request fails. Setting **Cookie source** to **Off** disables this enrichment and
does not inspect Kimi Desktop or browser cookies.

**Note**: Browser cookie import requires Full Disk Access permission.

Setting **Cookie source** to **Off** prevents browser import on every Kimi path. Context-free token resolution is
limited to explicit environment values; only the provider's settings-aware web strategy may inspect browsers.

## API Details

### Kimi Code API key

**Endpoint**: `GET https://api.kimi.com/coding/v1/usages`

**Authentication**: Bearer token (from `providers[].apiKey`, `KIMI_CODE_API_KEY`, or a fresh Kimi Code CLI credential)

**Response**:
```json
{
  "usage": {
    "limit": "2048",
    "used": "214",
    "remaining": "1834",
    "resetTime": "2026-01-09T15:23:13.716839300Z"
  },
  "limits": [{
    "window": {"duration": 300, "timeUnit": "TIME_UNIT_MINUTE"},
    "detail": {
      "limit": "200",
      "used": "139",
      "remaining": "61",
      "resetTime": "2026-01-06T13:33:02.717479433Z"
    }
  }]
}
```

### Kimi web cookie fallback

**Endpoint**: `POST https://www.kimi.com/apiv2/kimi.gateway.billing.v1.BillingService/GetUsages`

**Authentication**: Bearer token (from `kimi-auth` cookie)

**Response**:
```json
{
  "usages": [{
    "scope": "FEATURE_CODING",
    "detail": {
      "limit": "2048",
      "used": "214",
      "remaining": "1834",
      "resetTime": "2026-01-09T15:23:13.716839300Z"
    },
    "limits": [{
      "window": {"duration": 300, "timeUnit": "TIME_UNIT_MINUTE"},
      "detail": {
        "limit": "200",
        "used": "139",
        "remaining": "61",
        "resetTime": "2026-01-06T13:33:02.717479433Z"
      }
    }]
  }]
}
```

## Membership Tiers

| Tier | Price | Weekly Quota |
|------|-------|--------------|
| Andante | ¥49/month | 1,024 requests |
| Moderato | ¥99/month | 2,048 requests |
| Allegretto | ¥199/month | 7,168 requests |

All tiers have a rate limit of 200 requests per 5 hours.

## Troubleshooting

### "Kimi auth token is missing"
- Ensure "Cookie source" is set correctly
- If using Automatic mode, verify you're logged in to Kimi in your browser
- Grant Full Disk Access permission if using browser cookies
- Try Manual mode and paste your token directly

### "Kimi auth token is invalid or expired"
- Your token has expired. Paste a new token from your browser
- If using Automatic mode, log in to Kimi again in your browser

### "No Kimi session cookies found"
- You're not logged in to Kimi in any supported browser
- Grant Full Disk Access to CodexBar in System Settings

### "Failed to parse Kimi usage data"
- The API response format may have changed. Please report this issue.

## Implementation

- **Core files**: `Sources/CodexBarCore/Providers/Kimi/`
- **UI files**: `Sources/CodexBar/Providers/Kimi/`
- **Login flow**: `Sources/CodexBar/KimiLoginRunner.swift`
- **Tests**: `Tests/CodexBarTests/KimiProviderTests.swift`
