convez.ai
AgenteAutomaçãoIntermediário
Shelpuk-AI-Technology-Consulting

Kitty Bridge

Shelpuk-AI-Technology-Consulting/kitty-bridge

Use qualquer agent com qualquer provider LLM — economize até 90% em custos

Ver no GitHub
BomPluginScore · de 0 a 100

Ponte universal que conecta agentes de codificação (Claude Code, Codex, Gemini CLI) a qualquer provedor de LLM (MiniMax, GLM, OpenRouter, etc). Reduz custos em até 90% ao permitir usar modelos mais baratos ou combinar múltiplos provedores. Funciona como proxy local e determinístico, sem enviar dados além do backend escolhido.

Instalação

$npx convez-ai Shelpuk-AI-Technology-Consulting/kitty-bridge

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
16
Forks
4
Acompanhando
0
Saúde
50%
Último commit
há 3 dias
Versão
—
Issues abertas
1
Contribuidores
4

Casos de uso

  • Reduzir custos de sessões longas de codificação
  • Combinar múltiplos modelos em uma única sessão para otimizar custo-benefício
  • Usar provedores alternativos baratos (MiniMax, Novita, Fireworks) com agentes premium

Veredito

Solução prática e bem-pensada para quem usa coding agents e quer controlar custos. A abordagem de proxy local + roteamento inteligente é robusta, e a transparência sobre privacidade (tudo roda na máquina) é um ponto forte. Recomendado para desenvolvedores em produção com necessidade de otimização financeira.

README

A tradução para o português deste README ainda está na fila.

Use your favorite coding agent with any LLM provider.

Claude Code with MiniMax. Codex with GLM. Gemini CLI with OpenRouter. One command.

Why Kitty Bridge?

Frontier models are expensive. Claude Opus 4.7 costs $25 per 1M output tokens. GPT-5.5 runs $30–45 per 1M output tokens. A single long coding session can burn through dollars in minutes. And if you hit your subscription rate limits mid-task, you're stuck waiting.

Meanwhile, there are coding plans from providers like Z.AI, Novita, Fireworks, MiniMax, and others that deliver capable coding models at a fraction of the cost — often 90% cheaper than the flagship models.

Kitty Bridge gives you three ways to save:

✅ Switch to a cheaper provider — Use Claude Code with MiniMax, Codex with GLM, or Gemini CLI with OpenRouter. One command, instant savings.

✅ Use your existing subscriptions — Already paying for ChatGPT Plus or Pro? Use it through Kitty instead of buying API credits separately.

✅ Mix models with balanced profiles — Combine a powerful model like GPT-5.5 with a smaller, cheaper one in a single session. Kitty randomly distributes requests across both, giving you the reasoning power of a frontier model at roughly 20–25% of the cost.

Agent (Claude Code / Codex / Gemini / Kilo) → Kitty Bridge → any LLM provider

Kitty sits between your coding agent and the upstream provider, translating each agent's native protocol in real time. Your agent keeps its workflow — you choose the model and the price.

Kitty is also intentionally minimal:

✅ Local — Kitty runs on your machine. It does not send your prompts, code, or files to any third-party service beyond the backend LLM provider you explicitly configure.

✅ Just a bridge — Kitty only proxies and translates traffic between the coding agent and the backend model API. It does not get filesystem access, shell access, or any other extra capabilities.

✅ No AI inside Kitty — Kitty does not use an LLM, embeddings, or any other AI system internally. It is a deterministic local bridge with advanced routing, balancing, and compatibility features.

In short: Kitty is a minimal, local, and safe bridge with advanced functionality.

If you like what we're building, please ⭐ star this repo – it's a huge motivation for us to keep going!

Before You Start

You need two things to use Kitty:

  1. A coding agent installed on your machine — Claude Code, Codex CLI, Gemini CLI, or Kilo Code
  2. An account with an LLM provider — either an API key (pay per token) or a subscription/coding plan

API key vs. subscription? Some providers offer regular API access where you pay per token. Others offer subscription plans (e.g. your ChatGPT Plus subscription) that include usage quota. Kitty supports both — the setup wizard will guide you based on which provider you pick.

Quick Start

1. Install

pip install kitty-bridge

Requires Python 3.10+.

2. Set up a profile

kitty setup

An interactive wizard walks you through picking a provider, a model, and entering your API key. Takes 30 seconds.

New to this? The easiest way to start is with your existing ChatGPT Plus or Pro subscription — select "OpenAI ChatGPT Plan" during setup. No API key needed; Kitty authenticates through your browser. Alternatively, sign up at OpenRouter for a free API key that works with many models.

3. Launch your agent

kitty claude      # Claude Code → your provider
kitty codex       # Codex CLI → your provider
kitty gemini      # Gemini CLI → your provider
kitty kilo        # Kilo Code → your provider

That's it. Your coding agent now talks to the LLM you chose — not the one it was built for.

Example: Use GLM with Claude Code

$ pip install kitty-bridge
$ kitty setup
  ? Provider: openai
  ? Model: openai/gpt-5.4-pro
  ? API key: ********

$ kitty claude
  ✓ Bridge running on port <random_port>
  ✓ Claude Code launched
  > Hello! How can I help you today?

Example: Use Gemma 4 31B with Claude Code

$ pip install kitty-bridge
$ kitty setup
  ? Provider: Google AI Studio
  ? Model: gemma-4-31b-it
  ? API key: ********

$ kitty claude
  ✓ Bridge running on port <random_port>
  ✓ Claude Code launched
  > Hello! How can I help you today?

Example: Use your ChatGPT subscription with Claude Code

$ pip install kitty-bridge
$ kitty setup
  ? Provider: openai_subscription
  ? Model: gpt-5.4

  Opening browser for OpenAI authentication...

$ kitty claude
  ✓ Bridge running on port <random_port>
  ✓ Claude Code launched
  > Hello! How can I help you today?

No API key required — kitty authenticates with your ChatGPT Plus or Pro account through a browser-based OAuth flow. Each profile gets its own independent session.

Example: Use MiMo V2 Pro with Claude Code

$ pip install kitty-bridge
$ kitty setup
  ? Provider: Xiaomi MiMo
  ? Model: mimo-v2-pro
  ? API key: ********

$ kitty claude
  ✓ Bridge running on port <random_port>
  ✓ Claude Code launched
  > Hello! How can I help you today?

Balanced Profiles

A balanced profile combines multiple providers into one. Each request is sent to a randomly chosen healthy provider. If one provider goes down, the others pick up the slack automatically.

Why use it:

  • Cost savings — spread requests across cheaper providers
  • Rate limit resilience — never hit a single provider's limit
  • Fault tolerance — if one provider is down, the others keep working

How to create one:

kitty profile
# → "Create balancing profile" → select 2+ member profiles

Example: Combine MiniMax, Novita, and Z.AI into one balanced profile called my-pool, then use it with any agent:

kitty my-pool claude
kitty my-pool codex

When you run this, each request goes to a random healthy member. If MiniMax returns an error, kitty silently retries on Novita or Z.AI — your agent never sees the failure.

Bridge Mode

Bridge mode starts a standalone OpenAI-compatible API server on your machine. Use it when you want to connect tools that speak the OpenAI API — IDEs, custom scripts, anything that accepts a base URL.

kitty bridge          # use default profile
kitty my-profile bridge   # use a specific profile

Point your tool at http://localhost:<port> and it just works.

Available endpoints:

EndpointProtocolUsed by
POST /v1/chat/completionsChat CompletionsGeneral purpose
POST /v1/messagesAnthropic MessagesClaude Code
POST /v1/responsesOpenAI ResponsesCodex
POST /v1/gemini/generateContentGeminiGemini CLI
GET /healthzHealth checkMonitoring

Supported Agents

AgentCommandWhat it is
Claude Codekitty claudeAnthropic's coding agent
Codex CLIkitty codexOpenAI's coding agent
Gemini CLIkitty geminiGoogle's coding agent
Kilo Codekitty kiloOpen-source coding agent

Supported Providers

Regular API Key — sign up, get an API key, pay per token:

ProviderType IDNotes
AnthropicanthropicDirect API only (pay per token). Subscription plans (Claude Pro/Team) are not supported.
AWS BedrockbedrockUses boto3 SigV4 auth
MS AzureazureRequires deployment name
BytePlusbyteplus
Google AI Studiogoogle_aistudioGemini models via OpenAI-compatible endpoint
Google Vertex AIvertexRequires project and location
MiniMaxminimax
OpenAIopenaiDirect API (pay per token). For your ChatGPT subscription, use the plan below.
OpenRouteropenrouterMulti-provider router
Z.AIzai_regularGeneral-purpose endpoint

Coding Plans / Subscriptions — use your existing subscription or coding plan, no API key needed:

ProviderType IDNotes
Fireworks FirePassfireworks
Kimi Codekimi
Novita AInovita
Ollama Cloudollama_cloudHosted models via ollama.com API
OpenAI ChatGPT Planopenai_subscriptionUses your ChatGPT Plus/Pro subscription via OAuth
OpenCode Goopencode_go
Xiaomi MiMomimo
Z.AI Coding Planzai_codingCoding-optimized endpoint

Local LLMs:

ProviderType IDNotes
OllamaollamaLocal LLM deployment

Generic:

ProviderType IDNotes
Custom OpenAI-Compatiblecustom_openaiAny service with a /v1/chat/completions endpoint — see below

Custom OpenAI-Compatible Provider

Use the custom_openai provider to connect to any service that exposes an OpenAI-compatible Chat Completions API. This works with DeepSeek, Together AI, Groq, vLLM, LM Studio, and any other service that accepts POST /v1/chat/completions with Bearer auth and SSE streaming.

$ kitty setup
  ? Provider: Custom OpenAI-Compatible
  ? API base URL: https://api.deepseek.com/v1
  ? Model: deepseek-chat
  ? API key: ********

$ kitty claude
  ✓ Bridge running on port <random_port>
  ✓ Claude Code launched

Common endpoints:

ServiceBase URL
DeepSeekhttps://api.deepseek.com/v1
Together AIhttps://api.together.xyz/v1
Groqhttps://api.groq.com/openai/v1
Fireworkshttps://api.fireworks.ai/inference/v1
vLLM (local)http://localhost:8000/v1
LM Studiohttp://localhost:1234/v1

Both HTTPS and HTTP (local) endpoints are supported.

Commands

CommandDescription
kitty setupCreate your first profile (interactive wizard)
kitty profileManage profiles (create, edit, delete, set default, list)
kitty doctorDiagnose installation and configuration issues
kitty cleanupRestore agent config files after a crash
kitty bridgeStart a standalone API server
kitty claudeLaunch Claude Code with default profile
kitty codexLaunch Codex with default profile
kitty geminiLaunch Gemini CLI with default profile
kitty kiloLaunch Kilo Code with default profile
kitty <profile> <agent>Launch an agent with a specific profile
kitty <profile> bridgeStart bridge with a specific profile
kitty --no-validate <profile> <agent>Skip API key validation
kitty --debug <profile> <agent>Enable debug logging to ~/.cache/kitty/bridge.log
kitty --debug-file /path <profile> <agent>Write debug logs to a custom path
kitty --logging <profile> <agent>Enable token usage logging to ~/.cache/kitty/usage.log
kitty --log-file /path <profile> <agent>Write usage logs to a custom path (implies --logging)
kitty --versionPrint version
kitty --helpPrint help

Updating

pip install --upgrade kitty-bridge

Technical Details

How it works

Kitty sits between your coding agent and the upstream LLM provider. The high-level flow is the same as shown above:

Agent (Claude Code / Codex / Gemini / Kilo) → kitty bridge → upstream provider

When you run kitty claude:

  1. kitty reads your profile (provider, model, API key)
  2. Starts a local HTTP bridge on a random port
  3. Configures the agent to send requests to the bridge instead of its default endpoint
  4. The bridge translates each request to the provider's format and forwards it
  5. Responses are translated back to the agent's native format
  6. When the agent exits, kitty restores the agent's config files

Profiles

A profile binds a provider, model, and API key together. Stored in ~/.config/kitty/profiles.json.

kitty setup        # create a profile interactively
kitty profile      # manage existing profiles
kitty my-profile claude  # use a specific profile

Profile names must be 1-32 characters, lowercase letters, numbers, dashes, or underscores. Reserved words like setup, claude, codex, gemini, kilo, profile, bridge cannot be used as profile names.

Things to know about profile management:

  • Deleting a regular profile automatically removes it from all balancing profiles. If a balancing profile drops below 2 members, it is deleted entirely.
  • Deleting the default profile automatically promotes the first remaining profile as the new default.
  • Editing a profile's API key creates a new credential entry. Other profiles sharing the old key are not affected.

Pre-flight validation

Before launching, kitty checks that your profile configuration is valid and that your credentials can be resolved. If something is wrong, you get a clear error immediately — not a cryptic failure inside the agent.

kitty --no-validate my-profile claude  # skip validation (e.g. air-gapped/offline environments)

Logging

kitty has two independent logging streams, each with its own flag and optional custom path.

Token usage logs — records prompt/completion token counts per request:

# Default location: ~/.cache/kitty/usage.log
kitty --logging claude

# Custom location
kitty --log-file /tmp/my-usage.log claude

Debug logs — verbose tracing of requests, responses, and protocol translation:

# Default location: ~/.cache/kitty/bridge.log
kitty --debug claude

# Custom location
kitty --debug-file /tmp/my-debug.log claude

Both flags work in launch mode and bridge mode:

kitty --debug --log-file /tmp/usage.log my-profile bridge
kitty --debug-file /tmp/debug.log --logging my-profile codex
FlagWhat it logsDefault pathCustom path flag
--loggingToken usage~/.cache/kitty/usage.log--log-file PATH
--debugRequest/response tracing~/.cache/kitty/bridge.log--debug-file PATH

Cleanup

kitty restores agent config files after the agent exits. Three layers of cleanup:

  1. Normal exit — finally block
  2. Crash / SIGTERM — atexit handler
  3. SIGKILL / kernel OOM — run kitty cleanup manually

If your agent shows connection errors after a crash, run kitty cleanup to restore its configuration files.

Troubleshooting

Run kitty doctor to check your installation. It verifies that:

  • Agent binaries are installed and discoverable
  • A default profile exists
  • All profile credentials can be resolved

For deeper issues, use the logging flags:

kitty --debug my-profile claude          # trace requests/responses to ~/.cache/kitty/bridge.log
kitty --logging my-profile claude        # log token usage to ~/.cache/kitty/usage.log
kitty --debug --log-file /tmp/usage.log my-profile claude  # both, with custom paths

Project structure

src/kitty/
├── bridge/          # HTTP bridge + protocol translation
├── cli/             # Command-line interface
├── credentials/     # API key storage
├── launchers/       # Agent-specific adapters
├── profiles/        # Profile management
├── providers/       # Upstream provider adapters
├── tui/             # Terminal UI components
└── types.py         # Shared types

FAQ

"API Error: Unable to connect to API (ConnectionRefused)"

The agent is trying to connect to a bridge that isn't running. Usually caused by a stale config from a previous crashed session:

kitty cleanup

"API Error: 401" or "token expired or incorrect"

Your API key has expired or been revoked. Run setup again:

kitty setup

"Prompt exceeds max length" (Z.AI error 1261)

The conversation has grown beyond the model's context window. Use /clear in the agent to reset.

Can I use kitty with Cursor, Windsurf, or other IDEs?

Yes, but with caveats. Cursor uses a proprietary protocol that Kitty cannot integrate with automatically. However, you can start Kitty in bridge mode and point your IDE's "OpenAI base URL" setting at the bridge endpoint:

kitty bridge
# Then configure your IDE to use http://localhost:<port>/v1/chat/completions

This is a manual, best-effort configuration. Some IDE-specific features may not work.

Can I use my Anthropic (Claude Pro/Team) subscription with Kitty?

No. Anthropic's Terms of Service prohibit accessing their subscription APIs from third-party software. You can use Kitty with Anthropic's API directly — sign up at console.anthropic.com, create an API key, and use the anthropic provider. You will be billed per token, not through your subscription.

What is the difference between "OpenAI" and "OpenAI ChatGPT Plan"?

  • OpenAI — standard developer API. You create an API key at platform.openai.com and pay per token.
  • OpenAI ChatGPT Plan — uses your existing ChatGPT Plus or Pro subscription through a browser-based OAuth login. No API key needed; you use your subscription's included quota.

What is a "coding plan"?

Some providers offer subscription plans specifically designed for coding agents. Instead of a traditional API key with per-token billing, these plans typically authenticate via OAuth or a dedicated session and include usage quotas. Examples include Z.AI Coding Plan, Fireworks FirePass, Novita AI, and Kimi Code.

Can I run a local model?

Yes. Install Ollama, pull a model, then create a profile with provider ollama:

kitty setup
# Provider: ollama
# Base URL: http://localhost:11434/v1
# Model: llama3

What is the difference between Ollama and Ollama Cloud?

  • Ollama — connects to a local or remote Ollama instance using its OpenAI-compatible endpoint. No API key needed for local deployments.
  • Ollama Cloud — connects to ollama.com cloud models using an API key. No local GPU required. Some models require a paid subscription.

Does Kitty record my prompts or send data anywhere?

No. Kitty runs entirely on your machine. All prompts and responses pass directly between your coding agent and the upstream provider. Kitty does not send data to third parties, store conversations, or collect telemetry.

Something is broken. How do I debug it?

  1. Run kitty doctor to check your installation and credentials
  2. Run kitty cleanup if you see connection errors after a crash
  3. Use kitty --debug <profile> <agent> to trace all requests and responses to ~/.cache/kitty/bridge.log

Development

pip install -e ".[dev]"
pytest
ruff check .
mypy src/kitty

License

MIT

Ver o original no GitHub

Bom para

Relacionados