Clarissa

---

Clarissa is a command-line AI agent built with Bun and Ink. It supports multiple LLM providers including cloud services (OpenRouter, OpenAI, Anthropic) and local models (Apple Intelligence, LM Studio, GGUF via node-llama-cpp). The agent can execute tools, manage files, run shell commands, and integrate with external services via the Model Context Protocol (MCP).

Features

• Multi-provider support - Cloud (OpenRouter, OpenAI, Anthropic) and local (Apple Intelligence, LM Studio, GGUF) providers
• Multi-model support - Switch between Claude, GPT-4, Gemini, Llama, DeepSeek, and 100+ models
• Apple Intelligence - On-device AI with Apple Foundation Models on macOS 26+ with full tool calling
• Local model inference - Download and run GGUF models directly via node-llama-cpp
• 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
• 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
• Auto-update - Check for and install updates with clarissa upgrade

How It Works

Clarissa implements the ReAct (Reasoning + Acting) agent pattern, where an LLM reasons about tasks and takes actions through tool execution in an iterative loop.

Architecture Overview

flowchart LR
    subgraph Input
        A[User Message]
        B[Piped Content]
    end

    subgraph Clarissa
        C[Agent Loop]
        D[LLM Client]
        E[Tool Registry]
        F[Context Manager]
        G[Provider Registry]
    end

    subgraph Cloud Providers
        H[OpenRouter]
        I[OpenAI]
        J[Anthropic]
    end

    subgraph Local Providers
        K[Apple Intelligence]
        L[LM Studio]
        M[Local GGUF]
    end

    subgraph External
        N[MCP Servers]
    end

    A --> C
    B --> C
    C <--> D
    C <--> E
    C <--> F
    D <--> G
    G <--> H
    G <--> I
    G <--> J
    G <--> K
    G <--> L
    G <--> M
    E <-.-> N

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)
3. Executes the requested tools and feeds results back to the LLM
4. Repeats until the LLM provides a final answer

The ReAct Loop

flowchart TD
    A[User Input] --> B[Add to Conversation]
    B --> C[Send to LLM]
    C --> D{Response Type?}
    D -->|Tool Calls| E[Execute Tools]
    E --> F[Add Results to History]
    F --> C
    D -->|Final Answer| G[Display Response]

This loop continues until the LLM responds without requesting any tools, indicating it has completed the task. A maximum iteration limit prevents infinite loops.

Key Concepts

Concept	Description
Tool Confirmation	Potentially dangerous tools (file writes, shell commands) require approval before execution. Use /yolo to auto-approve.
Context Management	Clarissa tracks token usage and automatically truncates older messages when approaching the model's context limit.
Session Persistence	Conversations can be saved to ~/.clarissa/sessions/ and restored later with /save and /load.
Memory System	Use /remember to store facts that persist across sessions and are included in every conversation.
MCP Extensibility	Connect to Model Context Protocol servers to add custom tools without modifying Clarissa's code.

For detailed architecture documentation, see the Architecture Guide.

Requirements

• Bun v1.0 or later (for running from source or npm install)
• At least one LLM provider:
  • OpenRouter API key (100+ models)
  • OpenAI API key (GPT models)
  • Anthropic API key (Claude models)
  • Apple Intelligence (macOS 26+ with Apple Silicon)
  • LM Studio (local server)
  • Local GGUF model (via clarissa download)

Installation

From npm (recommended)

# Using bun
bun install -g clarissa

# Using npm
npm install -g clarissa

From source

git clone https://github.com/cameronrye/clarissa.git
cd clarissa
bun install
bun link

Standalone binary

Download a pre-built binary from the releases page and add it to your PATH:

# Example for macOS ARM
chmod +x clarissa-macos-arm64
mv clarissa-macos-arm64 /usr/local/bin/clarissa

Configuration

Quick Setup

Run the interactive setup to configure your API keys:

clarissa init

This will prompt you for API keys for OpenRouter, OpenAI, and Anthropic. You can skip any provider you don't want to use.

Manual Configuration

Create a config file at ~/.clarissa/config.json:

{
  "openrouterApiKey": "sk-or-...",
  "openaiApiKey": "sk-...",
  "anthropicApiKey": "sk-ant-...",
  "provider": "openrouter",
  "model": "anthropic/claude-sonnet-4"
}

Or set API keys as environment variables:

export OPENROUTER_API_KEY=sk-or-...
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...

Configuration Options

Config Key	Env Variable	Description
openrouterApiKey	OPENROUTER_API_KEY	OpenRouter API key (100+ models)
openaiApiKey	OPENAI_API_KEY	OpenAI API key (GPT models)
anthropicApiKey	ANTHROPIC_API_KEY	Anthropic API key (Claude models)
provider	-	Preferred provider (auto-detected if not set)
model	OPENROUTER_MODEL	Default model to use
localModelPath	-	Path to local GGUF model file
maxIterations	MAX_ITERATIONS	Maximum tool iterations (default: 10)
debug	DEBUG	Enable debug logging
mcpServers	-	MCP servers to auto-load

Providers

Clarissa automatically selects the best available provider based on your configuration:

Provider	Type	Requirements
openrouter	Cloud	API key
openai	Cloud	API key
anthropic	Cloud	API key
apple-ai	Local	macOS 26+, Apple Silicon
lmstudio	Local	LM Studio running on localhost:1234
local-llama	Local	Downloaded GGUF model

Switch providers with:

clarissa providers anthropic    # CLI
/provider anthropic             # Interactive

MCP Server Configuration

Add MCP servers to your config file to auto-load them on startup:

{
  "apiKey": "your_api_key_here",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "your_token" }
    }
  }
}

Use /mcp to view connected servers and /tools to see available tools.

Usage

Interactive Mode

Start Clarissa in interactive mode:

clarissa

One-Shot Mode

Run a single command and exit:

clarissa "What files are in this directory?"

Piped Input

Pipe content from other commands:

cat error.log | clarissa "Explain this error"
git diff | clarissa "Write a commit message for these changes"

CLI Commands

Command	Description
clarissa	Start interactive mode
clarissa "<message>"	One-shot query mode
clarissa init	Set up API keys interactively
clarissa upgrade	Upgrade to the latest version
clarissa config	View current configuration
clarissa history	Show one-shot query history
clarissa providers [NAME]	List providers or switch to one
clarissa download [ID]	Download a local GGUF model
clarissa models	List downloaded models
clarissa use <FILE>	Set a downloaded model as active
clarissa app "<message>"	Open macOS app with optional question

CLI Options

Option	Description
-c, --continue	Continue the last session
-m, --model MODEL	Use a specific model
--list-models	List available models
--check-update	Check for available updates
--debug	Enable debug output
-h, --help	Show help
-v, --version	Show version

Interactive Commands

Command	Description
/help	Show available commands
/new	Start a new conversation
/last	Load the most recent session
/save [NAME]	Save current session
/sessions	List saved sessions
/load ID	Load a saved 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
/provider [NAME]	Show or switch the LLM provider
/mcp CMD ARGS	Connect to a stdio MCP server
/mcp sse URL	Connect to an HTTP/SSE MCP server
/tools	List available tools
/context	Show context window usage
/yolo	Toggle auto-approve mode
/version	Show version info
/upgrade	Upgrade to latest version
/exit	Exit Clarissa

Keyboard Shortcuts

Shortcut	Action
Ctrl+C	Cancel current operation / Exit
Ctrl+P	Enhance prompt with AI
Up/Down	Navigate input history

Built-in Tools

File Operations

• read_file - Read file contents
• write_file - Write or create files
• patch_file - Apply patches to files
• list_directory - List directory contents
• search_files - Search for files by pattern

Git Integration

• git_status - Show repository status
• git_diff - Show changes
• git_log - View commit history
• git_add - Stage files
• git_commit - Commit changes
• git_branch - Manage branches

System

• bash - Execute shell commands
• calculator - Perform calculations

Web

• web_fetch - Fetch and parse web pages

File Context References

Reference files directly in your prompts using @filename syntax:

Explain what @src/index.ts does
Review @package.json:1-20 for issues
Compare @README.md with @CHANGELOG.md

MCP Integration

Connect to Model Context Protocol servers to extend Clarissa with additional tools:

# Stdio server (local process)
/mcp npx -y @modelcontextprotocol/server-filesystem /path/to/directory

# HTTP/SSE server (remote URL)
/mcp sse https://mcp.example.com/api

Development

Run with hot reloading:

bun run dev

Run tests:

bun test

Building Binaries

Build for your current platform:

bun run build:current

Build for all platforms:

bun run build:all

Binaries are output to the dist/ directory.

Publishing to npm

npm publish

Project Structure

src/
  index.tsx        # CLI entry point
  agent.ts         # ReAct agent loop implementation
  update.ts        # Auto-update functionality
  config/          # Environment configuration
  history/         # One-shot query history
  llm/             # LLM client and context management
    providers/     # Multi-provider abstraction (OpenRouter, OpenAI, Anthropic, Apple, etc.)
  mcp/             # MCP client integration
  memory/          # Long-term memory persistence
  models/          # Local model download and management
  preferences/     # User preferences persistence
  session/         # Session persistence
  tools/           # Tool definitions
  ui/              # Ink UI components

License

MIT

---

Made with ❤️ by Cameron Rye