# codeaashu/free-claude-code architecture

> Architecture diagram of the GitHub repository codeaashu/free-claude-code, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codeaashu/free-claude-code
- Repository: https://github.com/codeaashu/free-claude-code

## Overview

Free Claude Code is an Anthropic-compatible proxy that lets Claude Code use configurable hosted or local model providers, with optional Discord/Telegram remote-coding workflows. The primary flow is Claude Code request → API route/service → model selection and provider transport → Anthropic-compatible response. The bot flow accepts platform messages, queues conversation work, drives CLI sessions, and reports progress. README capabilities such as optimization, thinking/tool handling, rate limiting, and voice are represented where supported by the tree; unsampled internals and exact wiring are omitted.

Main entry points: [`providers/base.py`](https://github.com/codeaashu/free-claude-code/blob/main/providers/base.py) (Provider transport), [`api/services.py`](https://github.com/codeaashu/free-claude-code/blob/main/api/services.py) (Proxy service), [`messaging/handler.py`](https://github.com/codeaashu/free-claude-code/blob/main/messaging/handler.py) (Message handler), [`api/routes.py`](https://github.com/codeaashu/free-claude-code/blob/main/api/routes.py) (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_proxy["Proxy API"]
  node_api_app["FastAPI app<br/>[app.py]"]
  node_api_routes["API routes<br/>[routes.py]"]
  node_proxy_service["Proxy service<br/>[services.py]"]
  node_optimization["Request optimization"]
  node_anthropic_core["Anthropic compatibility"]
  node_token_count["Token counting<br/>[tokens.py]"]
end

subgraph group_routing["Model Providers"]
  node_model_router["Model routing<br/>[model_router.py]"]
  node_provider_registry["Provider registry<br/>[registry.py]"]
  node_provider_base["Provider transport<br/>[base.py]"]
  node_nim["NVIDIA NIM<br/>[client.py]"]
  node_openrouter["OpenRouter<br/>[client.py]"]
  node_deepseek["DeepSeek<br/>[client.py]"]
  node_lmstudio["LM Studio<br/>[client.py]"]
  node_llamacpp["llama.cpp<br/>[client.py]"]
end

subgraph group_messaging["Remote Coding"]
  node_platform_adapters["Platform adapters"]
  node_message_handler["Message handler<br/>[handler.py]"]
  node_tree_queue["Conversation queue<br/>[queue_manager.py]"]
  node_cli_manager["CLI sessions<br/>[manager.py]"]
  node_cli_session["Claude CLI process<br/>[session.py]"]
  node_session_store[("Session persistence<br/>[session.py]")]
end

subgraph group_runtime["Configuration"]
  node_settings["Settings<br/>[settings.py]"]
end

node_claude(("Claude Code"))
node_provider_services["External model APIs"]
node_messaging_platform(("Discord / Telegram"))

node_claude -->|"sends requests"| node_api_app
node_api_app -->|"mounts routes"| node_api_routes
node_api_routes -->|"handles messages"| node_proxy_service
node_api_routes -->|"counts tokens"| node_token_count
node_proxy_service -->|"intercepts trivial calls"| node_optimization
node_proxy_service -->|"selects model"| node_model_router
node_proxy_service -->|"resolves provider"| node_provider_registry
node_proxy_service -->|"formats messages"| node_anthropic_core
node_model_router -->|"reads mappings"| node_settings
node_provider_registry -->|"creates transports"| node_provider_base
node_provider_base -->|"dispatches"| node_nim
node_provider_base -->|"dispatches"| node_openrouter
node_provider_base -->|"dispatches"| node_deepseek
node_provider_base -->|"dispatches"| node_lmstudio
node_provider_base -->|"dispatches"| node_llamacpp
node_nim -.->|"calls provider"| node_provider_services
node_openrouter -.->|"calls provider"| node_provider_services
node_deepseek -.->|"calls provider"| node_provider_services
node_lmstudio -.->|"calls local service"| node_provider_services
node_llamacpp -.->|"calls local service"| node_provider_services
node_messaging_platform -->|"delivers messages"| node_platform_adapters
node_platform_adapters -->|"forwards messages"| node_message_handler
node_message_handler -->|"queues work"| node_tree_queue
node_message_handler -->|"runs conversations"| node_cli_manager
node_cli_manager -->|"creates sessions"| node_cli_session
node_message_handler -->|"updates progress"| node_platform_adapters
node_message_handler -->|"persists trees"| node_session_store
node_cli_session -->|"uses proxy API"| node_api_app

click node_api_app "https://github.com/codeaashu/free-claude-code/blob/main/api/app.py"
click node_api_routes "https://github.com/codeaashu/free-claude-code/blob/main/api/routes.py"
click node_proxy_service "https://github.com/codeaashu/free-claude-code/blob/main/api/services.py"
click node_optimization "https://github.com/codeaashu/free-claude-code/blob/main/api/optimization_handlers.py"
click node_anthropic_core "https://github.com/codeaashu/free-claude-code/tree/main/core/anthropic"
click node_token_count "https://github.com/codeaashu/free-claude-code/blob/main/core/anthropic/tokens.py"
click node_settings "https://github.com/codeaashu/free-claude-code/blob/main/config/settings.py"
click node_model_router "https://github.com/codeaashu/free-claude-code/blob/main/api/model_router.py"
click node_provider_registry "https://github.com/codeaashu/free-claude-code/blob/main/providers/registry.py"
click node_provider_base "https://github.com/codeaashu/free-claude-code/blob/main/providers/base.py"
click node_nim "https://github.com/codeaashu/free-claude-code/blob/main/providers/nvidia_nim/client.py"
click node_openrouter "https://github.com/codeaashu/free-claude-code/blob/main/providers/open_router/client.py"
click node_deepseek "https://github.com/codeaashu/free-claude-code/blob/main/providers/deepseek/client.py"
click node_lmstudio "https://github.com/codeaashu/free-claude-code/blob/main/providers/lmstudio/client.py"
click node_llamacpp "https://github.com/codeaashu/free-claude-code/blob/main/providers/llamacpp/client.py"
click node_platform_adapters "https://github.com/codeaashu/free-claude-code/tree/main/messaging/platforms"
click node_message_handler "https://github.com/codeaashu/free-claude-code/blob/main/messaging/handler.py"
click node_tree_queue "https://github.com/codeaashu/free-claude-code/blob/main/messaging/trees/queue_manager.py"
click node_cli_manager "https://github.com/codeaashu/free-claude-code/blob/main/cli/manager.py"
click node_cli_session "https://github.com/codeaashu/free-claude-code/blob/main/cli/session.py"
click node_session_store "https://github.com/codeaashu/free-claude-code/blob/main/messaging/session.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_app,node_api_routes,node_proxy_service,node_optimization,node_anthropic_core,node_token_count toneBlue
class node_model_router,node_provider_registry,node_provider_base,node_nim,node_openrouter,node_deepseek,node_lmstudio,node_llamacpp toneAmber
class node_platform_adapters,node_message_handler,node_tree_queue,node_cli_manager,node_cli_session,node_session_store,node_provider_services toneMint
class node_settings toneRose
class node_claude,node_messaging_platform toneIndigo
```

## Components

### Proxy API

- [FastAPI app](https://github.com/codeaashu/free-claude-code/blob/main/api/app.py): `api/app.py`
- [API routes](https://github.com/codeaashu/free-claude-code/blob/main/api/routes.py): `api/routes.py`
- [Proxy service](https://github.com/codeaashu/free-claude-code/blob/main/api/services.py): `api/services.py`
- [Request optimization](https://github.com/codeaashu/free-claude-code/blob/main/api/optimization_handlers.py): `api/optimization_handlers.py`
- [Anthropic compatibility](https://github.com/codeaashu/free-claude-code/tree/main/core/anthropic): `core/anthropic`
- [Token counting](https://github.com/codeaashu/free-claude-code/blob/main/core/anthropic/tokens.py): `core/anthropic/tokens.py`

### Model Providers

- [Model routing](https://github.com/codeaashu/free-claude-code/blob/main/api/model_router.py): `api/model_router.py`
- [Provider registry](https://github.com/codeaashu/free-claude-code/blob/main/providers/registry.py): `providers/registry.py`
- [Provider transport](https://github.com/codeaashu/free-claude-code/blob/main/providers/base.py): `providers/base.py`
- [NVIDIA NIM](https://github.com/codeaashu/free-claude-code/blob/main/providers/nvidia_nim/client.py): `providers/nvidia_nim/client.py`
- [OpenRouter](https://github.com/codeaashu/free-claude-code/blob/main/providers/open_router/client.py): `providers/open_router/client.py`
- [DeepSeek](https://github.com/codeaashu/free-claude-code/blob/main/providers/deepseek/client.py): `providers/deepseek/client.py`
- [LM Studio](https://github.com/codeaashu/free-claude-code/blob/main/providers/lmstudio/client.py): `providers/lmstudio/client.py`
- [llama.cpp](https://github.com/codeaashu/free-claude-code/blob/main/providers/llamacpp/client.py): `providers/llamacpp/client.py`

### Remote Coding

- [Platform adapters](https://github.com/codeaashu/free-claude-code/tree/main/messaging/platforms): `messaging/platforms`
- [Message handler](https://github.com/codeaashu/free-claude-code/blob/main/messaging/handler.py): `messaging/handler.py`
- [Conversation queue](https://github.com/codeaashu/free-claude-code/blob/main/messaging/trees/queue_manager.py): `messaging/trees/queue_manager.py`
- [CLI sessions](https://github.com/codeaashu/free-claude-code/blob/main/cli/manager.py): `cli/manager.py`
- [Claude CLI process](https://github.com/codeaashu/free-claude-code/blob/main/cli/session.py): `cli/session.py`
- [Session persistence](https://github.com/codeaashu/free-claude-code/blob/main/messaging/session.py): `messaging/session.py`

### Configuration

- [Settings](https://github.com/codeaashu/free-claude-code/blob/main/config/settings.py): `config/settings.py`

### Other components

- **Claude Code**
- **External model APIs**
- **Discord / Telegram**

## Connections

- Claude Code → FastAPI app: sends requests
- FastAPI app → API routes: mounts routes
- API routes → Proxy service: handles messages
- API routes → Token counting: counts tokens
- Proxy service → Request optimization: intercepts trivial calls
- Proxy service → Model routing: selects model
- Proxy service → Provider registry: resolves provider
- Proxy service → Anthropic compatibility: formats messages
- Model routing → Settings: reads mappings
- Provider registry → Provider transport: creates transports
- Provider transport → NVIDIA NIM: dispatches
- Provider transport → OpenRouter: dispatches
- Provider transport → DeepSeek: dispatches
- Provider transport → LM Studio: dispatches
- Provider transport → llama.cpp: dispatches
- NVIDIA NIM → External model APIs: calls provider
- OpenRouter → External model APIs: calls provider
- DeepSeek → External model APIs: calls provider
- LM Studio → External model APIs: calls local service
- llama.cpp → External model APIs: calls local service
- Discord / Telegram → Platform adapters: delivers messages
- Platform adapters → Message handler: forwards messages
- Message handler → Conversation queue: queues work
- Message handler → CLI sessions: runs conversations
- CLI sessions → Claude CLI process: creates sessions
- Message handler → Platform adapters: updates progress
- Message handler → Session persistence: persists trees
- Claude CLI process → FastAPI app: uses proxy API