Skip to content

docs: unified IA + robust README + VitePress categories #694

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
KooshaPari merged 1 commit into from
Feb 27, 2026
+142 −417
Merged

docs: unified IA + robust README + VitePress categories #694

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
232 changes: 62 additions & 170 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,202 +1,94 @@
# CLIProxyAPI++ (KooshaPari Fork)
# CLIProxyAPI++

This repository works with Claude and other AI agents as autonomous software engineers.
Agent-native, multi-provider OpenAI-compatible proxy for production and local model routing.

## Quick Start
## Table of Contents

```bash
# Docker
docker run -p 8317:8317 eceasy/cli-proxy-api-plus:latest
- [Key Features](#key-features)
- [Architecture](#architecture)
- [Getting Started](#getting-started)
- [Operations and Security](#operations-and-security)
- [Testing and Quality](#testing-and-quality)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [License](#license)

# Or build from source
go build -o cliproxy ./cmd/cliproxy
./cliproxy --config config.yaml
## Key Features

# Health check
curl http://localhost:8317/health
```
- OpenAI-compatible request surface across heterogeneous providers.
- Unified auth and token handling for OpenAI, Anthropic, Gemini, Kiro, Copilot, and more.
- Provider-aware routing and model conversion.
- Built-in operational tooling for management APIs and diagnostics.

## Multi-Provider Routing
## Architecture

Route OpenAI-compatible requests to any provider:
- `cmd/server`: primary API server entrypoint.
- `cmd/cliproxyctl`: operational CLI.
- `internal/`: runtime/auth/translator internals.
- `pkg/llmproxy/`: reusable proxy modules.
- `sdk/`: SDK-facing interfaces.

```bash
# List models
curl http://localhost:8317/v1/models

# Chat completion (OpenAI)
curl -X POST http://localhost:8317/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

# Chat completion (Anthropic)
curl -X POST http://localhost:8317/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model": "claude-3-5-sonnet", "messages": [{"role": "user", "content": "Hello"}]}'
```
## Getting Started

### Provider Configuration

```yaml
providers:
openai:
api_key: ${OPENAI_API_KEY}
anthropic:
api_key: ${ANTHROPIC_API_KEY}
kiro:
enabled: true
github_copilot:
enabled: true
ollama:
enabled: true
base_url: http://localhost:11434
```

## Supported Providers

| Provider | Auth | Status |
|----------|------|--------|
| OpenAI | API Key | ✅ |
| Anthropic | API Key | ✅ |
| Azure OpenAI | API Key/OAuth | ✅ |
| Google Gemini | API Key | ✅ |
| AWS Bedrock | IAM | ✅ |
| Kiro (CodeWhisperer) | OAuth | ✅ |
| GitHub Copilot | OAuth | ✅ |
| Ollama | Local | ✅ |
| LM Studio | Local | ✅ |

## Documentation
### Prerequisites

- `docs/start-here.md` - Getting started guide
- `docs/provider-usage.md` - Provider configuration
- `docs/provider-quickstarts.md` - Per-provider guides
- `docs/api/` - API reference
- `docs/sdk-usage.md` - SDK guides
- Go 1.24+
- Docker (optional)
- Provider credentials for target upstreams

## Environment
### Quick Start

```bash
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-..."
export CLIPROXY_PORT=8317
go build -o cliproxy ./cmd/server
./cliproxy --config config.yaml
```

---

## Development Philosophy

### Extend, Never Duplicate

- NEVER create a v2 file. Refactor the original.
- NEVER create a new class if an existing one can be made generic.
- NEVER create custom implementations when an OSS library exists.
- Before writing ANY new code: search the codebase for existing patterns.

### Primitives First

- Build generic building blocks before application logic.
- A provider interface + registry is better than N isolated classes.
- Template strings > hardcoded messages. Config-driven > code-driven.

### Research Before Implementing

- Check pkg.go.dev for existing libraries.
- Search GitHub for 80%+ implementations to fork/adapt.

---

## Library Preferences (DO NOT REINVENT)
### Docker Quick Start

| Need | Use | NOT |
|------|-----|-----|
| HTTP router | chi | custom router |
| Logging | zerolog | fmt.Print |
| Config | viper | manual env parsing |
| Validation | go-playground/validator | manual if/else |
| Rate limiting | golang.org/x/time/rate | custom limiter |

---

## Code Quality Non-Negotiables

- Zero new lint suppressions without inline justification
- All new code must pass: go fmt, go vet, golint
- Max function: 40 lines
- No placeholder TODOs in committed code

### Go-Specific Rules

- Use `go fmt` for formatting
- Use `go vet` for linting
- Use `golangci-lint` for comprehensive linting
- All public APIs must have godoc comments

---

## Verifiable Constraints

| Metric | Threshold | Enforcement |
|--------|-----------|-------------|
| Tests | 80% coverage | CI gate |
| Lint | 0 errors | golangci-lint |
| Security | 0 critical | trivy scan |

---

## Domain-Specific Patterns

### What CLIProxyAPI++ Is

CLIProxyAPI++ is an **OpenAI-compatible API gateway** that translates client requests to multiple upstream LLM providers. The core domain is: provide a single API surface that routes to heterogeneous providers with auth, rate limiting, and metrics.
```bash
docker run -p 8317:8317 eceasy/cli-proxy-api-plus:latest
```

### Key Interfaces
## Operations and Security

| Interface | Responsibility | Location |
|-----------|---------------|----------|
| **Router** | Request routing to providers | `pkg/llmproxy/router/` |
| **Provider** | Provider abstraction | `pkg/llmproxy/providers/` |
| **Auth** | Credential management | `pkg/llmproxy/auth/` |
| **Rate Limiter** | Throttling | `pkg/llmproxy/ratelimit/` |
- Rate limiting and quota/cooldown controls.
- Auth flows for provider-specific OAuth/API keys.
- CI policy checks and path guards.
- Governance and security docs under `docs/operations/` and `docs/reference/`.
Copy link

@coderabbitai coderabbitai bot Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Check which documentation directories exist
for p in docs/operations docs/reference docs/wiki docs/development docs/index docs/api docs/roadmap; do
  if [ -e "$p" ]; then
    echo "FOUND   $p"
  else
    echo "MISSING $p"
  fi
done

Repository: KooshaPari/cliproxyapi-plusplus

Length of output: 221

🏁 Script executed:

# Verify the exact content at line 57 and surrounding context
sed -n '50,65p' README.md

Repository: KooshaPari/cliproxyapi-plusplus

Length of output: 447

🏁 Script executed:

# Search for all documentation path references in README.md
grep -n "docs/" README.md | head -20

Repository: KooshaPari/cliproxyapi-plusplus

Length of output: 316

Resolve inconsistency between governance docs reference and unified IA definition.

Line 57 correctly references docs/operations/ and docs/reference/ (both exist), but the "unified category IA" definition on lines 71–75 omits these directories and lists others that don't exist (docs/wiki/, docs/development/, docs/index/, docs/roadmap/). Either the unified IA should include operations and reference, or clarify why they exist outside the canonical structure. This inconsistency can confuse contributors about the actual documentation organization.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 57, The README's "unified category IA" section is
inconsistent with the earlier reference to docs/operations/ and docs/reference/;
update the "unified category IA" list (the section around the "unified category
IA" heading) to include docs/operations/ and docs/reference/, or alternatively
add a clarifying sentence there explaining that operations and reference are
intentionally maintained outside the canonical IA and why; ensure you edit the
README.md entries that enumerate documentation directories so the listed
directories and the explanatory text match.


### Request Flow
## Testing and Quality

```
1. Client Request → Router
2. Router → Auth Validation
3. Auth → Provider Selection
4. Provider → Upstream API
5. Response ← Provider
6. Metrics → Response
```bash
go test ./...
```

### Common Anti-Patterns to Avoid
Quality gates are enforced via repo CI workflows (build/lint/path guards).

- **Hardcoded provider URLs** -- Use configuration
- **Blocking on upstream** -- Use timeouts and circuit breakers
- **No fallbacks** -- Implement provider failover
- **Missing metrics** -- Always track latency/cost
## Documentation

---
Primary docs root is `docs/` with a unified category IA:

## Kush Ecosystem
- `docs/wiki/`
- `docs/development/`
- `docs/index/`
- `docs/api/`
- `docs/roadmap/`

This project is part of the Kush multi-repo system:
VitePress docs commands:

```bash
cd docs
npm install
npm run docs:dev
npm run docs:build
```
kush/
├── thegent/ # Agent orchestration
├── agentapi++/ # HTTP API for coding agents
├── cliproxy++/ # LLM proxy (this repo)
├── tokenledger/ # Token and cost tracking
├── 4sgm/ # Python tooling workspace
├── civ/ # Deterministic simulation
├── parpour/ # Spec-first planning
└── pheno-sdk/ # Python SDK
```

---
## Contributing

1. Create a worktree branch.
2. Implement and validate changes.
3. Open a PR with clear scope and migration notes.

## License

MIT License - see LICENSE file
MIT License. See `LICENSE`.
Loading
Loading