Clarissa

An AI-powered terminal assistant with tool execution capabilities

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:

Sends your message to the LLM along with available tool definitions
Receives a response that may include tool calls (e.g., read a file, run a command)
Executes the requested tools and feeds results back to the LLM
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

Name		Name	Last commit message	Last commit date
Latest commit History 71 Commits
.github/workflows		.github/workflows
.vscode		.vscode
apple		apple
docs		docs
scripts		scripts
shared		shared
src		src
winget		winget
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
bun.lock		bun.lock
bunfig.toml		bunfig.toml
logo.svg		logo.svg
package.json		package.json
tsconfig.json		tsconfig.json

License

cameronrye/clarissa

Folders and files

Latest commit

History

Repository files navigation

Clarissa

Features

How It Works

Architecture Overview

The ReAct Loop

Key Concepts

Requirements

Installation

From npm (recommended)

From source

Standalone binary

Configuration

Quick Setup

Manual Configuration

Configuration Options

Providers

MCP Server Configuration

Usage

Interactive Mode

One-Shot Mode

Piped Input

CLI Commands

CLI Options

Interactive Commands

Keyboard Shortcuts

Built-in Tools

File Context References

MCP Integration

Development

Building Binaries

Publishing to npm

Project Structure

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 7

Packages 0

Languages

Packages