If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/router-for-me/CLIProxyAPI shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 16 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 66% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live router-for-me/CLIProxyAPI repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/router-for-me/CLIProxyAPI.

What it runs against: a local clone of router-for-me/CLIProxyAPI — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in router-for-me/CLIProxyAPI | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of router-for-me/CLIProxyAPI. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/router-for-me/CLIProxyAPI.git
#   cd CLIProxyAPI
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of router-for-me/CLIProxyAPI and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "router-for-me/CLIProxyAPI(\\.git)?\\b" \\
  && ok "origin remote is router-for-me/CLIProxyAPI" \\
  || miss "origin remote is not router-for-me/CLIProxyAPI (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/router-for-me/CLIProxyAPI"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

CLIProxyAPI wraps multiple AI CLI tools (Gemini, Claude Code, ChatGPT Codex, Antigravity) behind a unified OpenAI/Gemini/Claude-compatible REST API service, written in Go. It lets you access free or existing AI accounts through standard SDK interfaces without paying per-token, while supporting multi-account scenarios and local CLI access. Monolithic Go service: cmd/server/main.go is the entry point, internal/ contains core logic, examples/ holds reference implementations (custom-provider, http-request, translator), and cmd/fetch_antigravity_models/ is a utility. Configuration is YAML-based (config.example.yaml); Docker support via Dockerfile and docker-compose.yml. Structured around provider abstraction (OpenAI, Gemini, Claude, Codex handlers that likely exist in internal/).

Developers and teams who already have paid subscriptions or free access to Claude/ChatGPT/Gemini CLI tools but want to consume them via a standard OpenAI-compatible API. Also appeals to cost-conscious teams needing to consolidate multiple AI account access patterns into a single proxy.

Actively developed and production-ready. The repo shows mature CI/CD with GitHub Actions workflows (docker-image.yml, release.yaml, pr-test-build.yml), semantic versioning via .goreleaser.yml, multi-language README support (CN, JA), and go.mod indicates Go 1.26.0. Last observed state shows careful dependency management and cross-platform build support (PowerShell and Shell scripts for Docker).

Moderate risk: the project depends on OAuth flows for Claude Code and Codex (fragile to upstream API changes), integrates with multiple external CLI tools that may deprecate or alter their interfaces, and the single-maintainer pattern (no visible core team) creates knowledge concentration. Dependency surface is substantial (~50+ transitive deps) including crypto libraries (refraction-networking/utls, golang.org/x/crypto) that require careful security updates.

The repo is under active development with recent GitHub Actions workflows and a release pipeline (.goreleaser.yml). Presence of auto-retarget-main-pr-to-dev.yml and pr-path-guard.yml suggests managed branching strategy with main/dev split. No specific recent commit details visible, but the sponsorship section (FUNDING.yml) and multiple asset logos indicate sustained community and business interest.

git clone https://github.com/router-for-me/CLIProxyAPI.git
cd CLIProxyAPI
cp config.example.yaml config.yaml
cp .env.example .env
go mod download
go run ./cmd/server/main.go

Daily commands:

go run ./cmd/server/main.go
# Or with Docker:
docker-compose up
# Or cross-platform PowerShell:
.\docker-build.ps1

Server starts on default port (likely 8080, check config.example.yaml). Requires .env setup for OAuth keys and provider credentials.

• cmd/server/main.go: Entry point for the entire proxy API service; contains server initialization, routing setup, and provider configuration loading
• config.example.yaml: Template for all required configuration: provider credentials, OAuth settings, port, logging, and database connection strings
• internal/: Core business logic directory containing provider handlers (OpenAI, Gemini, Claude, Codex adapters), request/response transformations, and OAuth orchestration
• go.mod: Declares all dependencies including gin, oauth2, pgx, websocket, and version constraints; critical for reproducible builds
• Dockerfile: Defines containerized deployment; used by CI/CD pipeline and docker-compose.yml for production-like local testing
• .github/workflows/docker-image.yml: Automates Docker image building and pushing on releases; ensures consistent container artifact production
• examples/custom-provider/main.go: Demonstrates how to register and use a custom provider; serves as reference for extending the proxy with new AI services
• [docs/sdk-usage.md & docs/sdk-access.md](https://github.com/router-for-me/CLIProxyAPI/blob/main/docs/sdk-usage.md & docs/sdk-access.md): User-facing integration guides explaining how to use CLIProxyAPI with existing OpenAI/Gemini/Claude client libraries

New API provider: add handler in internal/ matching existing patterns (OpenAI, Gemini, Claude structure). Fix OAuth: examine internal/ OAuth flow code and update client IDs in config.example.yaml. Add CLI tool wrapper: mirror cmd/fetch_antigravity_models/main.go pattern. Logging changes: modify sirupsen/logrus setup in cmd/server/main.go. Examples: add new scenario to examples/ with standalone runnable code.

OAuth flow: requires valid CLIENT_ID and CLIENT_SECRET in .env for each provider (Claude, Codex); misconfiguration silently fails during token refresh. Database: go.mod includes jackc/pgx v5 but no migrations visible in file list—check if PostgreSQL schema setup is documented elsewhere or in internal/. Port binding: config.example.yaml likely defines port; verify it doesn't conflict with local services. Token counting: tiktoken-go/tokenizer model files may need downloading on first use (not bundled). Provider CLI dependency: Antigravity, Claude Code, etc. must be installed locally and in PATH; no validation at startup. Multi-account state: WebSocket connections (gorilla/websocket) may require session persistence—check if Redis or in-memory store is configured.

• OAuth 2.0 Authorization Code Flow — CLIProxyAPI uses OAuth to obtain and refresh tokens for Claude Code and Codex without storing plaintext credentials; understanding the flow (auth endpoint → code → token exchange → refresh) is critical for troubleshooting auth failures.
• Provider Adapter / Strategy Pattern — The codebase abstracts multiple AI services (OpenAI, Gemini, Claude, Codex) behind a common interface; learning how providers are swapped at runtime is essential for adding new services.
• Reverse Proxy / API Gateway — CLIProxyAPI acts as a reverse proxy, forwarding and transforming HTTP requests/responses between client SDKs and multiple backend AI services; understanding request routing and response normalization is core to the architecture.
• Token Counting (BPE / Tokenization) — The go.mod includes tiktoken-go/tokenizer for counting tokens before sending requests; this is critical for cost estimation and avoiding rate-limit overages on metered services.
• WebSocket Upgrade & Long-Polling — gorilla/websocket is included for real-time streaming (e.g., Claude Code or Codex streaming responses); understanding WebSocket lifecycle and error handling is needed for streaming endpoint debugging.
• Server-Sent Events (SSE) vs. WebSocket — Some AI APIs use SSE for streaming (e.g., Gemini), while others use WebSocket or chunked HTTP; CLIProxyAPI must adapt between these transport mechanisms transparently.
• mTLS / Custom TLS (refraction-networking/utls) — The presence of refraction-networking/utls suggests the proxy may need to impersonate specific client TLS fingerprints to bypass restrictions or access CLI tools; understanding custom cipher suites and ClientHello spoofing is relevant for advanced deployments.

• openai/openai-go — Official OpenAI Go SDK that CLIProxyAPI aims to be compatible with; understanding its request/response schema is essential for proxy design
• sashabaranov/go-openai — Popular community Go OpenAI client used by developers; CLIProxyAPI must implement compatible endpoints for this SDK to work
• anthropics/anthropic-sdk-go — Official Anthropic (Claude) SDK; CLIProxyAPI wraps Claude and must maintain API compatibility with this library
• google/generative-ai-go — Official Google Generative AI (Gemini) Go SDK; CLIProxyAPI proxies Gemini and needs to remain compatible with this SDK's expectations
• lc-net/LocalAI — Similar local/remote AI proxy approach written in Go; provides alternative model-serving patterns and architectural inspiration

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for internal/access/config_access/provider.go

The provider.go file handles critical provider configuration logic but has no corresponding test file (*_test.go). This is a high-risk area since it manages provider initialization and configuration reconciliation. Adding tests would improve reliability for the core access control system.

• [ ] Create internal/access/config_access/provider_test.go
• [ ] Write tests for provider initialization logic
• [ ] Add tests for configuration validation and reconciliation paths
• [ ] Test error handling for invalid provider configurations
• [ ] Ensure test coverage for OAuth provider setup (OpenAI, Gemini, Claude)

Add missing end-to-end tests for auth file operations in management API

The internal/api/handlers/management/ directory has several test files (auth_files_batch_test.go, auth_files_delete_test.go, auth_files_download_test.go, etc.) but is missing tests for auth_files.go itself. Additionally, config_auth_index.go has no corresponding test. These are critical for the auth management endpoint that users rely on.

• [ ] Create internal/api/handlers/management/auth_files_test.go with CRUD operation tests
• [ ] Create internal/api/handlers/management/config_auth_index_test.go
• [ ] Test authentication file upload/validation logic
• [ ] Test auth file listing and filtering
• [ ] Add tests for concurrent auth file access patterns

Add GitHub Actions workflow for Go code quality checks (golangci-lint, staticcheck)

The .github/workflows directory has agent guards and build tests, but lacks a dedicated linting/code quality workflow. Given the project is Go-based with v1.26.0, adding automated linting would catch issues early. The existing docker-image.yml and pr-test-build.yml could complement a code quality step.

• [ ] Create .github/workflows/go-lint.yml workflow
• [ ] Configure golangci-lint to run on PRs against main/dev branches
• [ ] Add staticcheck for Go-specific issues
• [ ] Configure workflow to fail on critical linting errors
• [ ] Reference specific paths: internal/, cmd/, examples/ to lint all source code
• [ ] Set up caching for faster linting runs using go-build-cache action

• Add integration tests for at least one complete provider (e.g., OpenAI) in internal/; current file list shows no *_test.go files, making this high-impact for stability.
• Document the internal provider interface contract: create docs/PROVIDER_INTERFACE.md explaining how to implement a new provider (struct, required methods, error handling patterns) to reduce friction for custom-provider contributions.
• Implement health-check endpoint (GET /health) that validates all configured providers are reachable; currently missing from visible endpoints and needed for Kubernetes / monitoring setup.

• High · Exposed Management Password in .env.example — .env.example. The .env.example file contains a commented-out MANAGEMENT_PASSWORD variable with a placeholder value 'change-me-to-a-strong-password'. While commented, this demonstrates weak password guidance and could lead users to set weak passwords. The management interface appears to control API keys and authentication files. Fix: Implement mandatory strong password policy (minimum 16 characters, complexity requirements). Consider using environment-only secrets without examples. Document password requirements explicitly.
• High · Multiple Exposed Ports in Docker Compose — docker-compose.yml. The docker-compose.yml exposes 7 ports (8317, 8085, 1455, 54545, 51121, 11451) without documentation of their purposes or network isolation. This increases the attack surface significantly. Some ports appear to be non-standard and their purpose is unclear. Fix: Document each port's purpose. Implement firewall rules to restrict access to only necessary ports. Consider using Docker networks with internal services. Bind ports only to localhost if not needed externally (e.g., 127.0.0.1:8317:8317).
• High · Unrestricted Volume Mounts — docker-compose.yml - volumes section. The docker-compose.yml mounts sensitive directories without read-only restrictions: config.yaml (contains configuration), ./auths (authentication files), and ./logs. These contain sensitive credentials and authentication tokens that could be exploited if container is compromised. Fix: Use read-only mounts where appropriate (e.g., :ro suffix). Implement proper file permissions on host (600 for credential files). Consider using Docker secrets for sensitive data instead of volume mounts. Implement log rotation and retention policies.
• High · Potential SQL Injection Risk in PostgreSQL Integration — internal/access/config_access, go.mod (jackc/pgx/v5). The codebase includes PostgreSQL token store functionality (PGSTORE_DSN, jackc/pgx/v5 dependency) for storing API keys and sensitive data. The presence of database schema references and potential dynamic query construction in token store handlers without visible parameterized query verification creates SQL injection risk. Fix: Ensure all database queries use parameterized queries/prepared statements exclusively. Implement input validation and sanitization. Use ORM frameworks that prevent SQL injection. Conduct database query code review.
• High · OAuth Callback Potential Security Issue — internal/api/handlers/management/oauth_callback.go. The presence of oauth_callback.go handler suggests OAuth integration for credential management. Without visible CSRF token validation, state parameter verification, or HTTPS enforcement visible in the file structure, this could be vulnerable to OAuth token interception and CSRF attacks. Fix: Implement mandatory HTTPS-only transport. Validate OAuth state parameters. Implement CSRF token verification. Use secure random token generation. Set secure, httponly, sameSite flags on cookies. Validate redirect URLs against whitelist.
• High · Sensitive Credential Storage in Config Files — config.example.yaml, config.yaml, docker-compose.yml. The config.example.yaml and config.yaml (mounted in docker-compose) are used to store authentication credentials for Gemini, Claude, GPT, and other services. These files are directly mounted into the container with world-readable potential permissions. Fix: Store credentials in environment variables or secure vaults (Vault, AWS Secrets Manager). Encrypt config files at rest. Implement strict file permissions (600). Never commit actual config.yaml to version control. Use .gitignore for credentials.
• Medium · Dependency Version Pinning and Update Management — go.mod, go.sum. While go.mod uses versioning, critical security-sensitive dependencies like golang.org/x/crypto, golang.org/x/oauth2, and github.com/gin-gonic/gin are pinned but may have undetected vulnerabilities. The go version 1.26.0 is extremely new and may have undiscovered issues. Fix: Implement automated dependency scanning (Dependabot, Snyk, WhiteSource). Set up CI/CD pipeline to detect vulnerable dependencies. Regularly update dependencies. Audit transitive dependencies. Consider using Go security scanner tools.
• Medium · Missing HTTPS Enforcement in API Configuration — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.