Getting Started Guide

ollacc is a thin wrapper and launcher designed to connect the Anthropic Claude Code CLI directly to the Ollama Cloud API. By bypassing the local Ollama server (localhost:11434), it allows users to interact with cloud-hosted models without the resource overhead of a local proxy, facilitating high-concurrency workflows like "swarming". Sources: README.md:1-18

This guide details the installation process, initial configuration, and the runtime logic used to resolve and launch Claude Code with the appropriate environment and model selection.

Installation Process

The installation is handled by a dedicated script that sets up the local environment, configures file permissions, and establishes a shell alias for easy access.

Automated Setup

The install.sh script performs the following actions:

1. Environment Detection: Determines the real user and home directory, even when executed via sudo. Sources: install.sh:22-29
2. Directory Creation: Creates ~/.ollacc/ with restrictive permissions (chmod 700). Sources: install.sh:41-43
3. Binary & Library Deployment: Copies the ollacc launcher and the lib/ directory containing the modular shell logic to the installation directory. Sources: install.sh:46-54
4. Configuration Initialization: Generates a default config file (chmod 600) if it does not already exist. Sources: install.sh:61-71
5. Shell Integration: Appends an alias to the user's shell profile (checking .zshrc, .bashrc, .bash_profile, or .profile in priority order). Sources: install.sh:74-100

Installation Logic Flow

The following diagram illustrates the idempotent installation sequence:

Configuration and Authentication

On the first run, ollacc requires an API key from Ollama Cloud. This key is stored securely and used to authenticate subsequent requests.

Configuration Parameters

The system manages three primary configuration variables within ~/.ollacc/config:

Sources: install.sh:66-68, lib/auth.sh:12

Authentication Flow

When the launcher starts, it sources the configuration and checks for the existence of the authentication token. If missing, it triggers an interactive prompt.

Model Resolution and Selection

The tool dynamically discovers available cloud models by intersecting a "popular" list scraped from the Ollama website with the user's authorized catalog.

Resolution Logic

The catalog_resolve function in lib/catalog.sh follows a tiered approach:

1. Auth'd Catalog: Fetches the list of models the user is authorized to use via https://ollama.com/api/tags. Sources: lib/catalog.sh:26-34
2. Popularity Scraping: Scrapes https://ollama.com/search?c=cloud to determine the current "Popular" sort order. Sources: lib/catalog.sh:37-41
3. Intersection: Filters the popular list to only include models present in the user's authorized catalog. Sources: lib/catalog.sh:47-56
4. Fallback: If scraping fails, it falls back to the authorized catalog order; if the API is unreachable, it uses a hardcoded last-resort list. Sources: lib/catalog.sh:59-75

Interactive Menu

If no default model is set (or via manual clearing), users are presented with a numbered menu. Options include the top 10 resolved models or a custom input. Sources: lib/menu.sh:9-30

Execution Environment

Once a model is selected, ollacc exports specific environment variables required by the Anthropic SDK and executes the claude CLI.

Required Environment Variables

To route Claude Code to Ollama Cloud, the following must be set:

• ANTHROPIC_BASE_URL: Set to https://ollama.com. Sources: lib/auth.sh:12
• ANTHROPIC_AUTH_TOKEN: The stored API key. Sources: lib/auth.sh:51
• ANTHROPIC_API_KEY: Must be explicitly empty to ensure the SDK uses the AUTH_TOKEN. Sources: lib/auth.sh:52, README.md:154-164

Command Invocation

The launcher executes:

exec claude --model <selected_model> [additional_flags]

Sources: README.md:89-94, README.md:166

Maintenance and Uninstallation

Management Flags

Users can manage their state using specific flags handled before the main logic:

• --model-clear: Removes the OLLAMA_CLAUDE_DEFAULT_MODEL from the config. Sources: lib/flags.sh:13-21
• --key-clear: Removes the ANTHROPIC_AUTH_TOKEN from the config. Sources: lib/flags.sh:23-31

Uninstallation

The uninstall.sh script performs a cleanup by:

1. Removing the ollacc alias and its markers from all shell profile files (.zshrc, .bashrc, etc.). Sources: uninstall.sh:23-53
2. Optionally deleting the ~/.ollacc directory, including the stored API key. Sources: uninstall.sh:61-73

Summary: ollacc provides a streamlined, local-server-free path for Claude Code to utilize Ollama Cloud models. It automates the environment configuration and provides a dynamic model selection interface based on real-time cloud availability.