# Hermes Kimi Code Bypass

> Kimi Code OAuth subscription bypass for Hermes Agent — zero pay-per-token, zero ToS risk. Companion to kristianvast/hermes-claude-auth.

- **Type:** MCP server
- **Install:** `agentstack add mcp-lckx777-hermes-kimi-code-bypass`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [lckx777](https://agentstack.voostack.com/s/lckx777)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [lckx777](https://github.com/lckx777)
- **Source:** https://github.com/lckx777/hermes-kimi-code-bypass

## Install

```sh
agentstack add mcp-lckx777-hermes-kimi-code-bypass
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# hermes-kimi-code-bypass

Hermes Agent provider plugin that reuses **Kimi Code OAuth subscription** credentials (managed by the official `kimi` CLI) to route inference through `api.kimi.com/coding/v1` — zero pay-per-token, zero ToS violation, zero anti-bot dependency.

Companion to [`kristianvast/hermes-claude-auth`](https://github.com/kristianvast/hermes-claude-auth) (Anthropic bypass Q8) and the `openai-codex` bundled provider (ChatGPT subscription OAuth). Together they enable a fully subscription-only multi-provider Hermes squad.

## Why this exists

The Hermes Agent ships `kimi-coding` as a built-in provider, but it only accepts **static API keys** prefixed `sk-kimi-*` (paid Kimi Code dashboard keys). Users who already have a Kimi Code **subscription** (paid app/CLI access) have OAuth credentials in `~/.kimi/credentials/kimi-code.json` — but the bundled provider can't refresh them.

This plugin closes the gap:

- Reads OAuth credentials from the `kimi` CLI's credential file
- Auto-refreshes via the official OAuth endpoint (`https://auth.kimi.com/api/oauth/token`) when the access token is within 5min of expiry
- Saves refreshed tokens back to the CLI's file (keeps `kimi` CLI in sync)
- Seeds `KIMI_API_KEY` + `KIMI_BASE_URL` for the bundled chat_completions transport
- Self-registers in both `ProviderProfile` (runtime) and `PROVIDER_REGISTRY` (auth-side)

The Hermes routes inference at `api.kimi.com/coding/v1` using the Anthropic Messages API surface (Kimi Code endpoint is Anthropic-compatible).

## Architecture

```
Hermes provider 'kimi-code-bypass'
    -> reads ~/.kimi/credentials/kimi-code.json (managed by kimi CLI)
    -> auto-refresh if access_token within 5min of expiry via
       POST https://auth.kimi.com/api/oauth/token (grant_type=refresh_token)
    -> seeds KIMI_API_KEY + KIMI_BASE_URL in os.environ on plugin import
    -> Anthropic Messages API surface at https://api.kimi.com/coding/v1/messages
```

This is **NOT** a web-scraping bypass. It is the same OAuth flow the official `kimi` CLI uses.

## Prerequisites

- Hermes Agent installed (`hermes` CLI working)
- `kimi` CLI installed: `uv tool install kimi-cli` (or whatever your distribution method)
- `kimi auth login` ran at least once (credential file populated)

## Install

```bash
git clone https://github.com/lckx777/hermes-kimi-code-bypass.git
cd hermes-kimi-code-bypass
./install.sh
```

The installer copies the plugin into `~/.hermes/plugins/model-providers/kimi-code-bypass/` and runs a one-shot discovery check.

## Verify

After install, in a new Hermes session:

```bash
hermes auth status kimi-code-bypass
# expect: "logged in"

hermes chat -q "Reply: PING" --provider kimi-code-bypass --model kimi-for-coding -Q --max-turns 1
# expect: "PING" (or similar short response)
```

## Use as part of a subscription-only Hermes squad

Wire the 4-role squad (codex orchestrates → kimi codes → opus debugs → codex reviews) entirely via Hermes native config — no orchestrator code, no squad YAML required:

```yaml
# ~/.hermes/config.yaml

model:
  provider: openai-codex
  model: gpt-5.5
  default: gpt-5.5            # critical: oneshot reads this

delegation:
  provider: kimi-code-bypass   # this plugin
  model: kimi-for-coding

fallback_providers:
  - {provider: openai-codex,     model: gpt-5.5}
  - {provider: anthropic,        model: claude-opus-4-7}
  - {provider: kimi-code-bypass, model: kimi-for-coding}
```

Then prompt the orchestrator: "delegue debug pra opus", "delegue review pra codex". The main LLM decides per-call routing.

## Three failure modes (when something breaks)

| Cause | Symptom | Recovery | Time |
|-------|---------|----------|------|
| A (60%) — credential file missing | provider returns 401, env empty | `kimi auth login` | 2min |
| B (30%) — refresh token expired (~30d) | 401 even after fresh access_token attempt | `kimi auth login` (re-mints both tokens) | 2min |
| C (10%) — plugin not discovered / seeder didn't run | `get_provider_profile('kimi-code-bypass')` returns None | restart Hermes / check startup stderr for `[kimi-code-bypass]` warnings | 1min |

Full diagnostic procedure documented in the Hermes skill `mcp/consuming-external-cli-oauth-from-hermes-provider/references/kimi-code.md`.

## Uninstall

```bash
./uninstall.sh
```

Removes `~/.hermes/plugins/model-providers/kimi-code-bypass/`. Does NOT touch `~/.kimi/credentials/` (managed by the `kimi` CLI, not by this plugin).

## License

MIT. See `LICENSE`.

## Acknowledgments

- Architecture pattern mirrors [`kristianvast/hermes-claude-auth`](https://github.com/kristianvast/hermes-claude-auth) for Anthropic Claude Max subscription bypass.
- Hermes Agent: [NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent).
- Kimi CLI: Moonshot AI.

## Related

- `mcp/consuming-external-cli-oauth-from-hermes-provider` — Hermes skill that codifies this CLI-OAuth bypass pattern as a class
- `mcp/auditing-hermes-setup-completeness/references/multi-provider-subscription-routing.md` — validated config snapshot for the 4-role squad
- `mcp/repairing-hermes-bypass-q8-after-agent-refactor` — the Anthropic-side equivalent

---

Built by [lckx777](https://github.com/lckx777) on 2026-05-17. ZERO-CHUTE rigor — all claims empirically validated before merge.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [lckx777](https://github.com/lckx777)
- **Source:** [lckx777/hermes-kimi-code-bypass](https://github.com/lckx777/hermes-kimi-code-bypass)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-lckx777-hermes-kimi-code-bypass
- Seller: https://agentstack.voostack.com/s/lckx777
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.