High-Level Architecture Design
Relevant source files
The following files were used as context for generating this wiki page:
ollacc is a specialized shell-based launcher designed to interface the Anthropic Claude Code CLI directly with the Ollama Cloud API. Its primary architectural purpose is to bypass local Ollama server installations, routing traffic straight to https://ollama.com by configuring the environment variables expected by the Anthropic SDK.
The system is structured as a modular Bash application, separating concerns into configuration management, authentication, model catalog resolution, and interactive menu systems. By acting as a thin wrapper, it ensures that Claude Code sessions operate in an OpenAI-compatible mode targeting remote cloud models without local resource overhead.
Sources: README.md:1-24, lib/auth.sh:44-49
Core System Components
The architecture consists of the main ollacc launcher (which orchestrates the flow) and several supporting library modules.
Component Overview
| Component | Responsibility | Relevant Files |
|---|---|---|
| Installer | Handles environment setup, directory creation, and shell alias injection. | install.sh |
| Config Manager | Manages persistent settings in ~/.ollacc/config using safe string escaping. | lib/config.sh |
| Auth Handler | Manages API key prompts and exports SDK-compatible environment variables. | lib/auth.sh |
| Catalog Resolver | Scrapes popular models and intersects them with user-authorized tags. | lib/catalog.sh |
| Menu System | Provides an interactive CLI for model selection and default setting. | lib/menu.sh |
Sources: install.sh:10-50, lib/config.sh:1-60, lib/auth.sh:1-49, lib/catalog.sh:1-85, lib/menu.sh:1-65
Data Flow and Orchestration
The system follows a linear execution path during a typical run, transitioning from state initialization to environment preparation and finally to the execution of the claude binary.
Initialization Flow
The following diagram illustrates the initialization process, including flag handling and configuration loading.
Authentication and Environment Configuration
A critical architectural requirement for ollacc is the specific configuration of the Anthropic SDK to redirect requests to Ollama Cloud. This is achieved through three environment variables.
ANTHROPIC_BASE_URL: Set tohttps://ollama.com.ANTHROPIC_AUTH_TOKEN: Contains the Ollama Cloud Bearer token.ANTHROPIC_API_KEY: Explicitly set to an empty string. This is required because the Anthropic SDK prioritizes this variable; if it is populated, theANTHROPIC_AUTH_TOKENis ignored.
Sources: lib/auth.sh:44-49, README.md:162-171
Model Catalog Resolution
The catalog_resolve function implements a multi-stage fallback logic to ensure the user can select a model even during partial network failures.
- Authorized Tags: Queries
https://ollama.com/api/tagsusing the Bearer token to identify models the user is authorized to use. - Popular Scrape: Scrapes
https://ollama.com/search?c=cloudto determine current trending models. - Intersection: Filters the popular list against the authorized list to ensure selected models are actually callable.
- Fallback 1: If scraping fails, it defaults to the order provided by the authorized tags API.
- Fallback 2: If all network requests fail, it uses a hardcoded "last-resort" list of known models.
Sources: lib/catalog.sh:22-85
Configuration Management
Configuration is stored in ~/.ollacc/config as a shell-sourceable file. To prevent injection attacks or shell breakage when variables are sourced, the system uses a bash_escape utility.
Configuration Schema
| Variable | Description | Security |
|---|---|---|
ANTHROPIC_AUTH_TOKEN | The user's API Bearer token. | chmod 600 |
ANTHROPIC_BASE_URL | The target API endpoint (default: ollama.com). | chmod 600 |
OLLAMA_CLAUDE_DEFAULT_MODEL | The model slug to use automatically. | chmod 600 |
The config_set function uses awk to perform idempotent updates, ensuring that comments are preserved and keys are correctly updated or appended.
Sources: lib/config.sh:40-60, install.sh:56-61
Installation and Uninstallation
The system architecture emphasizes idempotency and minimal footprint.
- Install: Creates the directory structure, copies library files, and injects an alias into the user's shell profile (
.zshrc,.bashrc, etc.) using a# ollacc: aliasmarker for future identification. - Uninstall: Uses the marker to surgically remove the alias and optionally deletes the
~/.ollaccconfiguration directory.
Sources: install.sh:75-101, uninstall.sh:25-50
Conclusion
The high-level architecture of ollacc leverages a modular shell-script design to provide a robust, zero-local-overhead interface for Claude Code. By managing environment variables and implementing a resilient model discovery system, it ensures seamless integration with the Ollama Cloud infrastructure while maintaining a secure, user-configurable local environment.