feat: Apple Foundation Model with full tool calling support (v1.2.0)

- Add full tool calling support for Apple Intelligence on-device AI
- All built-in tools work with Apple Foundation Model (file ops, git, bash, web)
- Intelligent tool limit handling (max 10 tools for optimal Apple AI performance)
- Channel token parsing for clean output from thinking models
- Real-time streaming with channel token filtering
- Comprehensive Apple AI test suite (bun test:apple-ai)
- Update documentation to highlight multi-provider and local AI support
- Add Apple Intelligence feature card to documentation website

Author: cameronrye

.env.example

@@ -1,17 +1,16 @@
-# OpenRouter API Key (required)
-# Get your key at https://openrouter.ai/keys
-OPENROUTER_API_KEY=your_api_key_here
+# API Keys (backup - config file takes precedence)
+# Recommended: use ~/.clarissa/config.json instead
+# Run 'clarissa init' to set up config file
 
-# Model to use (optional, defaults to anthropic/claude-sonnet-4)
-# See available models at https://openrouter.ai/models
-OPENROUTER_MODEL=anthropic/claude-sonnet-4
+# OpenRouter - https://openrouter.ai/keys
+OPENROUTER_API_KEY=
 
-# App name (optional)
-APP_NAME=Clarissa
+# OpenAI - https://platform.openai.com/api-keys
+OPENAI_API_KEY=
 
-# Maximum agent loop iterations (optional, default: 10)
-MAX_ITERATIONS=10
+# Anthropic - https://console.anthropic.com/settings/keys
+ANTHROPIC_API_KEY=
 
-# Debug mode (optional, default: false)
+# Optional settings
+MAX_ITERATIONS=10
 DEBUG=false
-

CHANGELOG.md

@@ -5,6 +5,55 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2025-12-09
+
+### Added
+
+- **Apple Foundation Model with Tools** - Full tool calling support for Apple Intelligence
+  - Apple on-device AI now supports all built-in tools (file operations, git, bash, web fetch)
+  - Intelligent tool limit handling (max 10 tools for optimal performance)
+  - Channel token parsing for clean output from thinking models
+  - Automatic retry without tools when model returns null responses
+- **Enhanced Apple AI streaming** - Real-time streaming with channel token filtering
+- **Comprehensive test suite** - New test script for Apple AI provider (`bun test:apple-ai`)
+
+### Fixed
+
+- Apple AI responses now properly parse channel tokens (analysis, commentary, final)
+- Tool calls from Apple Foundation Model now correctly extract function arguments
+- Streaming mode properly filters internal model tokens for clean user output
+
+## [1.1.0] - 2025-12-08
+
+### Added
+
+- **Multi-provider LLM support** - Switch between different LLM providers at runtime
+  - OpenRouter (cloud) - Access to 100+ models
+  - OpenAI (cloud) - Direct GPT API access
+  - Anthropic (cloud) - Direct Claude API access
+  - Apple Intelligence (local) - On-device AI for macOS 26+
+  - LM Studio (local) - Local inference via LM Studio desktop app
+  - Local Llama (local) - Direct GGUF model inference via node-llama-cpp
+- **Provider registry** - Automatic provider detection and priority-based selection
+- **Model download system** - Download GGUF models from Hugging Face
+  - `clarissa download` command with recommended models list
+  - `clarissa models` command to list downloaded models
+  - Progress tracking during downloads
+  - Curated list of best models (Qwen 3, Gemma 3, Llama 4, DeepSeek R1, etc.)
+- **Preferences persistence** - Remember last used provider and model across sessions
+- **Auto-update system** - Check for updates and upgrade easily
+  - `clarissa upgrade` command to update to latest version
+  - Background update checking with notifications
+  - Package manager detection (bun, pnpm, npm)
+- **`/provider` command** - Switch LLM providers during a session
+- **Retry logic** - Exponential backoff with jitter for API rate limits
+
+### Changed
+
+- Refactored LLM client to use provider abstraction layer
+- Updated architecture diagram to show multi-provider support
+- Enhanced configuration options for provider-specific settings
+
 ## [1.0.2] - 2025-12-07
 
 ### Fixed

README.md

@@ -17,20 +17,22 @@
 
 ---
 
-Clarissa is a command-line AI agent built with [Bun](https://bun.sh) and [Ink](https://github.com/vadimdemedes/ink). It provides a conversational interface powered by [OpenRouter](https://openrouter.ai), enabling access to various LLMs like Claude, GPT-4, Gemini, and more. The agent can execute tools, manage files, run shell commands, and integrate with external services via the Model Context Protocol (MCP).
+Clarissa is a command-line AI agent built with [Bun](https://bun.sh) and [Ink](https://github.com/vadimdemedes/ink). It supports multiple LLM providers including cloud services like [OpenRouter](https://openrouter.ai), OpenAI, and Anthropic, as well as local inference via Apple Intelligence, LM Studio, and local GGUF models. The agent can execute tools, manage files, run shell commands, and integrate with external services via the Model Context Protocol (MCP).
 
 ## Features
 
-- **Multi-model support** - Switch between Claude, GPT-4, Gemini, Llama, DeepSeek, and other models via OpenRouter
+- **Multi-provider support** - Use cloud providers (OpenRouter, OpenAI, Anthropic) or run completely offline with local models
+- **Apple Intelligence** - On-device AI using Apple Foundation Models with full tool calling support (macOS 26+)
+- **Local model inference** - Run GGUF models locally via LM Studio or node-llama-cpp with GPU acceleration
 - **Streaming responses** - Real-time token streaming for responsive conversations
 - **Built-in tools** - File operations, Git integration, shell commands, web fetching, and more
 - **MCP integration** - Connect to external MCP servers to extend functionality
-- **Session management** - Save and restore conversation history
+- **Session management** - Auto-save on exit, quick resume with `/last`, and named sessions
 - **Memory persistence** - Remember facts across sessions with `/remember` and `/memories`
 - **Context management** - Automatic token tracking and context truncation
 - **Tool confirmation** - Approve or reject potentially dangerous operations
-- **One-shot mode** - Run single commands directly from your shell
-- **Piped input** - Pipe content from other commands for processing
+- **One-shot mode** - Run single commands directly from your shell with query history
+- **Auto-updates** - Get notified of new versions and upgrade easily with `clarissa upgrade`
 
 ## How It Works
 
@@ -52,9 +54,13 @@ flowchart LR
         F[Context Manager]
     end
 
+    subgraph Providers
+        G[Cloud: OpenRouter / OpenAI / Anthropic]
+        H[Local: Apple AI / LM Studio / GGUF]
+    end
+
     subgraph External
-        G[OpenRouter API]
-        H[MCP Servers]
+        I[MCP Servers]
     end
 
     A --> C
@@ -63,10 +69,11 @@ flowchart LR
     C <--> E
     C <--> F
     D <--> G
-    E <-.-> H
+    D <--> H
+    E <-.-> I
 ```
 
-The system connects your terminal to various LLMs through OpenRouter. When you ask Clarissa to perform a task, it:
+The system connects your terminal to various LLM providers. When you ask Clarissa to perform a task, it:
 
 1. Sends your message to the LLM along with available tool definitions
 2. Receives a response that may include tool calls (e.g., read a file, run a command)
@@ -103,7 +110,9 @@ For detailed architecture documentation, see the [Architecture Guide](https://ca
 ## Requirements
 
 - [Bun](https://bun.sh) v1.0 or later (for running from source or npm install)
-- An [OpenRouter API key](https://openrouter.ai/keys)
+- For cloud providers: API key for [OpenRouter](https://openrouter.ai/keys), [OpenAI](https://platform.openai.com/api-keys), or [Anthropic](https://console.anthropic.com/)
+- For Apple Intelligence: macOS 26+ with Apple Silicon and Apple Intelligence enabled
+- For local models: [LM Studio](https://lmstudio.ai) or download GGUF models with `clarissa download`
 
 ## Installation
 
@@ -138,25 +147,44 @@ mv clarissa-macos-arm64 /usr/local/bin/clarissa
 
 ## Configuration
 
-Create a config file at `~/.clarissa/config.json`:
+Create a config file at `~/.clarissa/config.json` or run `clarissa init` for interactive setup.
+
+### API Keys (Cloud Providers)
+
+Set one or more API keys for cloud providers:
 
 ```bash
-mkdir -p ~/.clarissa
-echo '{"apiKey": "your_api_key_here"}' > ~/.clarissa/config.json
+# Environment variables
+export OPENROUTER_API_KEY=your_key_here
+export OPENAI_API_KEY=your_key_here
+export ANTHROPIC_API_KEY=your_key_here
 ```
 
-Or set your OpenRouter API key as an environment variable:
+Or in `~/.clarissa/config.json`:
 
-```bash
-export OPENROUTER_API_KEY=your_api_key_here
+```json
+{
+  "apiKey": "your_openrouter_key",
+  "openaiApiKey": "your_openai_key",
+  "anthropicApiKey": "your_anthropic_key"
+}
 ```
 
-Optional settings (in config.json or as environment variables):
+### Local Providers (No API Key Required)
+
+- **Apple Intelligence**: Automatically detected on macOS 26+ with Apple Intelligence enabled
+- **LM Studio**: Start LM Studio and load a model - Clarissa auto-detects the local server
+- **Local GGUF**: Download models with `clarissa download` and run offline
+
+### Configuration Options
 
 | Config Key | Env Variable | Default | Description |
 |------------|--------------|---------|-------------|
-| `apiKey` | `OPENROUTER_API_KEY` | (required) | Your OpenRouter API key |
-| `model` | `OPENROUTER_MODEL` | `anthropic/claude-sonnet-4` | Default model to use |
+| `apiKey` | `OPENROUTER_API_KEY` | - | OpenRouter API key |
+| `openaiApiKey` | `OPENAI_API_KEY` | - | OpenAI API key |
+| `anthropicApiKey` | `ANTHROPIC_API_KEY` | - | Anthropic API key |
+| `model` | - | (auto) | Preferred model |
+| `preferredProvider` | - | (auto) | Preferred provider ID |
 | `maxIterations` | `MAX_ITERATIONS` | `10` | Maximum tool execution iterations |
 | `debug` | `DEBUG` | `false` | Enable debug logging |
 | `mcpServers` | - | `{}` | MCP servers to auto-load (see below) |
@@ -230,12 +258,14 @@ git diff | clarissa "Write a commit message for these changes"
 | `/save [NAME]` | Save current session |
 | `/sessions` | List saved sessions |
 | `/load ID` | Load a saved session |
+| `/last` | Resume last session |
 | `/delete ID` | Delete a saved session |
 | `/remember <fact>` | Save a memory |
 | `/memories` | List saved memories |
 | `/forget <#\|ID>` | Forget a memory |
 | `/model [NAME]` | Show or switch the current model |
-| `/mcp` | Show MCP server status |
+| `/provider [ID]` | Show or switch the LLM provider |
+| `/mcp` | Show connected MCP servers |
 | `/tools` | List available tools |
 | `/context` | Show context window usage and breakdown |
 | `/yolo` | Toggle auto-approve mode (skip tool confirmations) |

ROADMAP.md

@@ -4,6 +4,50 @@
 
 ---
 
+## Completed Features (v1.2.0)
+
+### Apple Foundation Model with Tools
+- [x] Full tool calling support for Apple Intelligence on-device AI
+- [x] All built-in tools work with Apple Foundation Model (file ops, git, bash, web fetch)
+- [x] Intelligent tool limit handling (max 10 tools for optimal Apple AI performance)
+- [x] Channel token parsing for clean output from thinking models
+- [x] Automatic retry without tools when model returns null responses
+- [x] Real-time streaming with channel token filtering
+- [x] Comprehensive Apple AI test suite (`bun test:apple-ai`)
+
+## Completed Features (v1.1.0)
+
+### Multi-Provider LLM Support
+- [x] Provider abstraction layer with unified interface
+- [x] OpenRouter provider (cloud) - 100+ models
+- [x] OpenAI provider (cloud) - Direct GPT API
+- [x] Anthropic provider (cloud) - Direct Claude API
+- [x] Apple Intelligence provider (local) - macOS 26+ on-device AI
+- [x] LM Studio provider (local) - Desktop app integration
+- [x] Local Llama provider (local) - Direct GGUF inference via node-llama-cpp
+- [x] Provider switching with `/provider` command
+- [x] Automatic provider detection and priority selection
+- [x] Preferences persistence for last used provider/model
+
+### Local Model Support
+- [x] GGUF model download from Hugging Face (`clarissa download`)
+- [x] Curated recommended models list (Qwen 3, Gemma 3, Llama 4, DeepSeek R1, etc.)
+- [x] Download progress tracking
+- [x] Model listing (`clarissa models`)
+- [x] GPU layer configuration for local inference
+- [x] Flash attention support
+
+### Auto-Update System
+- [x] Version checking against npm registry
+- [x] `clarissa upgrade` command
+- [x] Package manager detection (bun, pnpm, npm)
+- [x] Background update notifications
+
+### API Improvements
+- [x] Retry logic with exponential backoff and jitter
+- [x] Rate limit handling for all providers
+- [x] Streaming support for all providers
+
 ## Completed Features (v1.0.0)
 
 ### Core Operations
@@ -63,17 +107,20 @@
 - [ ] HTTP/SSE MCP server transport
 - [ ] File context references
 - [ ] Image/vision analysis
+- [ ] Model delete command for local models
 
 ### Medium Term
 - [ ] Codebase indexing with embeddings
 - [ ] Semantic search across codebase
 - [ ] Model comparison mode
 - [ ] Fallback model configuration
+- [ ] Provider-specific model recommendations
 
 ### Long Term
 - [ ] Integrated linting with auto-fix
 - [ ] Test runner integration
 - [ ] Project scaffolding templates
+- [ ] Multi-agent collaboration
 
 ---