Skip to content

READMEv2.md

Latest commit

 

History

History
498 lines (385 loc) · 14.4 KB

READMEv2.md

File metadata and controls

498 lines (385 loc) · 14.4 KB

Quounter

GitHub License Version

Quounter is a cross-platform desktop application for managing multiple AI coding assistant accounts, tracking quota usage, and proxying requests across providers. Built with Tauri 2.x, React, and Rust.

🎯 Key Features

📊 Quota Management

  • Real-time quota tracking for all connected AI providers
  • Persistent request history with unlimited storage
  • Export/Import request logs for backup and analysis
  • Account sorting by name with visual quota indicators
  • Quota aggregation with customizable display modes (used/remaining)
  • Automatic quota detection for .quota_out and .disabled accounts

🔄 Smart Request Routing

  • Multiple routing strategies: Round-robin, random, quota-based, sticky session
  • Automatic failover when quota is exceeded
  • Retry mechanism with configurable intervals
  • Streaming support with keepalive and bootstrap retries
  • Upstream proxy support (HTTP/HTTPS/SOCKS5)

🔐 Multi-Provider Authentication

Supports authentication for:

  • ✅ Gemini CLI (OAuth)
  • ✅ Claude (OAuth)
  • ✅ Codex/OpenAI (OAuth)
  • ✅ GitHub Copilot (Device code flow)
  • ✅ Antigravity (OAuth)
  • 🔜 Qwen (OAuth - coming soon)
  • 🔜 iFlow (OAuth - coming soon)
  • 🔜 Kiro (Multiple auth methods - coming soon)

🛠️ CLI Agent Configuration

  • Auto-detection of installed AI coding agents (Cursor, Windsurf, Trae, etc.)
  • One-click configuration for detected agents
  • Custom agent support with manual configuration
  • API key management for agent authentication

🎨 Modern UI/UX

  • Dark mode interface optimized for developers
  • System tray integration with quick access menu
  • Consistent design across all 10 screens
  • Real-time updates with auto-refresh
  • Privacy mode to hide sensitive information

🌐 Operating Modes

1. Monitor Only (Default)

  • Track quota usage from IDE accounts
  • No proxy server needed
  • Perfect for monitoring Cursor/Windsurf usage

2. Local Proxy

  • Run a local proxy server (default port: 8318)
  • Route requests through multiple accounts
  • Automatic quota-based failover
  • Configure CLI agents automatically

3. Remote Proxy (Experimental)

  • Connect to self-hosted CLIProxyAPI server
  • Share accounts across machines
  • Centralized management

📸 Screenshots

Dashboard
Dashboard - Overview of all providers and quota status

Quota Screen
Quota Screen - Detailed quota tracking by provider

Accounts
Accounts Screen - Manage authentication files

Agents
CLI Agents - Auto-detect and configure AI coding tools

Logs
Logs Screen - Request history with export/import

🚀 Quick Start

Prerequisites

Required Software

System Dependencies

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install libwebkit2gtk-4.1-dev \
  build-essential \
  curl \
  wget \
  file \
  libssl-dev \
  libgtk-3-dev \
  libayatana-appindicator3-dev \
  librsvg2-dev \
  patchelf

macOS

xcode-select --install

Windows

Installation

# Clone the repository
git clone https://github.com/bigidulka/quounter.git
cd quounter

# Install dependencies
npm install

# Run in development mode
npm run tauri:dev

# Build for production
npm run tauri:build

Download Pre-built Binaries

Download the latest release from GitHub Releases:

  • Linux (Debian/Ubuntu): Quounter_1.0.0_amd64.deb (8.9 MB)
  • Linux (Fedora/RHEL): Quounter-1.0.0-1.x86_64.rpm (8.9 MB)
  • Linux (Universal): Quounter_1.0.0_amd64.AppImage (79 MB)

📖 User Guide

First-Time Setup

  1. Launch Quounter - The app will start in "Monitor Only" mode by default
  2. Choose Operating Mode - Go to Settings → Operating Mode
    • Monitor Only: Track quotas without running a proxy
    • Local Proxy: Run a local proxy server for routing requests
    • Remote Proxy: Connect to a remote server (experimental)
  3. Add Accounts - Navigate to Accounts screen
    • Click "Scan Local Files" to auto-detect accounts from IDEs
    • Or manually authenticate via OAuth for each provider

Managing Accounts

Accounts Screen provides:

  • List of all authenticated accounts by provider
  • Enable/disable accounts with toggle
  • Mark accounts as "quota_out" to exclude from routing
  • Delete accounts when no longer needed
  • Real-time quota status indicators

Configuring CLI Agents

Agents Screen features:

  • Auto-detection of installed AI coding agents
  • One-click configuration for:
    • Cursor
    • Windsurf
    • Trae
    • Custom agents
  • View current configuration
  • Reconfigure when needed

Viewing Logs

Logs Screen offers two tabs:

Requests Tab:

  • View all proxied requests with full details
  • Filter by provider, model, or search text
  • Export history to JSON for backup
  • Import previously exported logs
  • Statistics: total requests, success rate, token usage
  • Persistent storage - unlimited request history

Proxy Logs Tab:

  • Real-time proxy server logs
  • Filter by log level (info, warn, error, debug)
  • Auto-refresh with pause/resume
  • Search through logs

Routing & Strategy

Strategy Screen allows configuration of:

Routing Strategy:

  • Round-robin: Distribute requests evenly
  • Random: Random account selection
  • Quota-based: Prefer accounts with higher quota
  • Sticky session: Use same account for a session

Quota Exceeded Behavior:

  • Switch to different project
  • Switch to preview model
  • Retry with different account

Request Retry:

  • Configurable retry count (0-10)
  • Max retry interval (1-120 seconds)

Streaming Options:

  • Keepalive interval (0-60 seconds)
  • Bootstrap retries (0-10)

Upstream Proxy:

  • Route through HTTP/HTTPS/SOCKS5 proxy
  • Test connection before applying
  • View latency and status

API Keys Management

API Keys Screen:

  • Generate secure API keys for agent authentication
  • View, copy, edit, or delete keys
  • Keys are required for proxy server requests
  • Auto-generate random keys with one click

Models Management

Models Screen:

  • View all available models from connected providers
  • Enable/disable models for routing
  • Drag to reorder model priority
  • Search and filter by provider or model name

Virtual Models (Coming Soon)

Virtual Models Screen:

  • Create virtual model endpoints
  • Aggregate multiple provider models
  • Custom routing per virtual model
  • Test virtual model configurations

Settings

Settings Screen includes:

Operating Mode:

  • Choose between Monitor, Local Proxy, or Remote Proxy
  • View features for each mode
  • Switch modes (requires proxy restart)

Local Proxy Server:

  • View proxy status and port
  • Configure management key
  • Copy proxy URL for agent configuration

Remote Proxy Server:

  • Add remote server connection
  • Test connection before saving
  • View connection status

Upstream Proxy:

  • Configure HTTP/HTTPS/SOCKS5 proxy
  • Test connection with latency display

Logging:

  • Enable/disable file logging
  • Enable request log for debugging
  • Enable debug mode for verbose output

Privacy:

  • Hide sensitive information (emails, account names)

System:

  • Launch at login (autostart)
  • Auto-start proxy server on launch

Notifications:

  • Enable desktop notifications
  • Low quota alerts with threshold
  • Cooling period notifications
  • Proxy crash alerts

🏗️ Architecture

Tech Stack

Frontend:

  • React 19.1
  • TypeScript 5.8
  • Tailwind CSS 3.4
  • Zustand (state management)
  • Lucide React (icons)
  • @tanstack/react-virtual (virtualization)
  • @dnd-kit (drag & drop)

Backend:

  • Rust (stable)
  • Tauri 2.x
  • tokio (async runtime)
  • serde (serialization)
  • reqwest (HTTP client)

Project Structure

quounter/
├── src/                      # React frontend
│   ├── components/          # Reusable UI components
│   ├── lib/                 # Stores, API, utilities
│   ├── screens/             # Main application screens
│   └── main.tsx             # App entry point
├── src-tauri/               # Rust backend
│   ├── src/
│   │   ├── services/       # Core services
│   │   │   ├── quota_fetchers/  # Provider quota fetchers
│   │   │   ├── auth_service.rs  # Authentication
│   │   │   ├── proxy_manager.rs # Proxy lifecycle
│   │   │   └── agent_detection.rs # CLI agent detection
│   │   ├── models/         # Data models
│   │   └── lib.rs          # Tauri commands
│   └── Cargo.toml
├── screenshots/             # App screenshots
├── CLIProxyDocs.md         # CLIProxy API documentation
└── README.md

State Management

The app uses Zustand for state management with persistence:

  • useAppStore: Global app state, proxy status
  • useQuotaStore: Quota data, refresh logic
  • useAccountsStore: Account management
  • useSettingsStore: User preferences, operating mode
  • useLogsStore: Request history, proxy logs
  • useModelsStore: Available models, ordering
  • useAgentsStore: Detected CLI agents
  • useAuthFileManager: Auth file operations

Tauri Commands

72 Tauri commands expose Rust functionality to the frontend:

Proxy Management:

  • start_proxy, stop_proxy, toggle_proxy
  • get_proxy_status, restart_proxy
  • is_binary_installed, download_binary, update_binary

Authentication:

  • authenticate, start_oauth, get_oauth_status
  • submit_oauth_callback, authenticate_kiro
  • fetch_auth_files, delete_auth_file, toggle_auth_file

Quota Management:

  • fetch_direct_quotas, fetch_usage_stats
  • set_auth_file_quota_out

Configuration:

  • set_routing_strategy, get_routing_strategy
  • get_fallback_config, set_fallback_config
  • fetch_api_keys, add_api_key, delete_api_key, update_api_key

Logging:

  • fetch_logs, clear_logs, set_debug_mode
  • fetch_request_history, clear_request_history

CLI Agents:

  • detect_agents, configure_agent

Virtual Models:

  • get_virtual_models, set_virtual_models_enabled

🔧 Development

Running Tests

# Frontend type checking
npm run build

# Backend compilation
cd src-tauri && cargo build

Building for Production

# Build all platform bundles
npm run tauri:build

# Outputs:
# - Linux: .deb, .rpm, .AppImage
# - macOS: .dmg, .app
# - Windows: .msi, .exe

Code Style

The project follows strict UI consistency standards documented in STYLE_AUDIT.md:

  • Buttons: bg-blue-600 hover:bg-blue-500 rounded-lg px-3 py-2 text-sm
  • Headers: flex items-center justify-between mb-6
  • Typography: Consistent text sizes and colors
  • Spacing: Standardized margins and gaps

📊 Testing Status

Platform Support

Platform Build Run Notes
Linux (x86_64) ✅ ✅ Tested on Ubuntu
Linux (ARM64) ⬜ ⬜ Not tested
macOS (Intel) ⬜ ⬜ Not tested
macOS (Apple M1/M2) ⬜ ⬜ Not tested
Windows 10 ⬜ ⬜ Not tested
Windows 11 ⬜ ⬜ Not tested

Provider Support

Provider Auth Quota Notes
Gemini CLI ✅ ✅ OAuth flow
Claude ✅ ✅ OAuth flow
Codex (OpenAI) ✅ ✅ OAuth flow
GitHub Copilot ✅ ✅ Device code flow
Antigravity ✅ ✅ OAuth flow
Qwen 🔜 🔜 Coming soon
iFlow 🔜 🔜 Coming soon
Kiro 🔜 🔜 Multiple auth methods

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Follow the established code style (see STYLE_AUDIT.md)
  4. Ensure TypeScript and Rust code compiles without errors
  5. Test your changes thoroughly
  6. Commit with descriptive messages
  7. Push to your fork and submit a pull request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • Built with Tauri - Rust-powered desktop app framework
  • UI powered by React and Tailwind CSS
  • Icons from Lucide
  • Inspired by the need for better AI coding assistant account management

📞 Support

🗺️ Roadmap

  • Complete Qwen provider integration
  • Complete iFlow provider integration
  • Complete Kiro provider integration
  • Virtual Models functionality
  • macOS and Windows builds
  • Auto-update mechanism
  • Plugin system for custom providers
  • Multi-language support
  • Advanced analytics dashboard
  • Cloud sync for settings

Made with ❤️ by the Quounter Team