clarissa (Cameronrye)

Clarissa

An AI-powered terminal assistant with tool execution capabilities

______________________________________________________________________

特性

• 多提供商支持 -云（OpenRouter、OpenAI、Anthropic）和本地（Apple Intelligence、LM Studio、GGUF）提供商
• 多型号支持 -在Claude、GPT-4、Gemini、Llama、DeepSeek和100多种型号之间切换
• 苹果智能 -在macOS 26+上使用Apple Foundation Models的设备上AI，具有完整的工具调用功能
• 局部模型推理 -直接通过节点llama cpp下载并运行GGUF模型
• 流媒体响应 -响应式对话的实时令牌流
• 内置工具 -文件操作、Git集成、shell命令、web获取等
• MCP集成 -连接到外部MCP服务器以扩展功能
• 会话管理 -保存和恢复对话历史记录
• 内存持久性 -在会话中记住事实 /remember 和 /memories
• 上下文管理 -自动令牌跟踪和上下文截断
• 工具确认 -批准或拒绝潜在危险操作
• 一次性模式 -直接从shell运行单个命令
• 管道输入 -来自其他命令的管道内容用于处理
• 自动更新 -检查并安装更新 clarissa upgrade

运作原理

Clarissa实施 ReAct（推理+代理）代理模式，其中LLM通过迭代循环中的工具执行来推理任务并采取行动。

架构概述

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

该系统将您的终端连接到各种LLM提供商。当你要求Clarissa执行任务时，它：

1. 将您的消息与可用的工具定义一起发送到LLM
2. 接收可能包括工具调用的响应（例如，读取文件、运行命令）
3. 执行请求的工具并将结果反馈给LLM
4. 重复，直到LLM提供最终答案

ReAct循环

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]

这个循环会一直持续到LLM在不请求任何工具的情况下做出响应，表明它已经完成了任务。最大迭代限制可防止无限循环。

关键概念

有关详细的体系结构文档，请参阅 架构指南.

需求

• 包子 v1.0或更高版本（用于从源代码或npm安装运行）
• 至少一个LLM提供者：

- OpenRouter API密钥 （100+型号） - OpenAI API密钥 （GPT型号） - 无烟煤API键 （克劳德模型） - 苹果智能（macOS 26+与苹果硅） - LM 工作室 （本地服务器） - 本地GGUF模型（通过 clarissa download)

安装

来自npm（推荐）

# Using bun
bun install -g clarissa

# Using npm
npm install -g clarissa

来源

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

独立二进制

从下载预构建的二进制文件 发布页面 并将其添加到您的PATH中：

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

配置

快速设置

运行交互式设置以配置API密钥：

clarissa init

这将提示您输入OpenRouter、OpenAI和Anthropic的API密钥。您可以跳过任何不想使用的提供商。

手动配置

在以下位置创建配置文件 ~/.clarissa/config.json:

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

或者将API键设置为环境变量：

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

配置选项

提供商

Clarissa会根据您的配置自动选择最佳可用提供商：

使用以下选项切换提供商：

clarissa providers anthropic    # CLI
/provider anthropic             # Interactive

MCP服务器配置

将MCP服务器添加到配置文件中，以便在启动时自动加载它们：

{
  "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" }
    }
  }
}

使用 /mcp 查看连接的服务器和 /tools 查看可用工具。

用法

交互模式

以交互模式启动Clarissa：

clarissa

一次性模式

运行一个命令并退出：

clarissa "What files are in this directory?"

管道输入

其他命令中的管道内容：

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

CLI命令

CLI选项

交互式命令

键盘快捷键

内置工具

文件操作

• read_file -读取文件内容
• write_file -写入或创建文件
• patch_file -将补丁应用于文件
• list_directory -列出目录内容
• search_files -按模式搜索文件

Git集成

• git_status -显示存储库状态
• git_diff -显示更改
• git_log -查看提交历史记录
• git_add -舞台文件
• git_commit -提交更改
• git_branch -管理分支机构

系统

• bash -执行shell命令
• calculator -执行计算

网络

• web_fetch -获取并解析网页

文件上下文引用

使用以下命令直接在提示中引用文件 @filename 语法：

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

MCP集成

连接到模型上下文协议服务器，使用其他工具扩展Clarissa：

# 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

发展

使用热重新加载运行：

bun run dev

运行测试：

bun test

构建二进制文件

为您当前的平台构建：

bun run build:current

为所有平台构建：

bun run build:all

二进制文件输出到 dist/ 目录。

发布到npm

npm publish

项目结构

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

许可证

麻省理工学院

______________________________________________________________________

由以下材料制成❤️ 通过 Cameron Rye