{"id":36967707,"url":"https://github.com/cameronrye/clarissa","last_synced_at":"2026-02-09T01:05:08.709Z","repository":{"id":328217748,"uuid":"1111479400","full_name":"cameronrye/clarissa","owner":"cameronrye","description":"An AI-powered terminal assistant with tool execution capabilities","archived":false,"fork":false,"pushed_at":"2026-02-03T18:32:34.000Z","size":41020,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-04T07:51:00.554Z","etag":null,"topics":["agent","ai","apple-intelligence","assistant","bun","claude","cli","gpt","ink","llm","mcp","openrouter","terminal","typescript"],"latest_commit_sha":null,"homepage":"https://clarissa.run/","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cameronrye.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-07T02:37:40.000Z","updated_at":"2026-02-03T18:33:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cameronrye/clarissa","commit_stats":null,"previous_names":["cameronrye/clarissa"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/cameronrye/clarissa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cameronrye%2Fclarissa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cameronrye%2Fclarissa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cameronrye%2Fclarissa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cameronrye%2Fclarissa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cameronrye","download_url":"https://codeload.github.com/cameronrye/clarissa/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cameronrye%2Fclarissa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29252667,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-08T22:49:53.206Z","status":"ssl_error","status_checked_at":"2026-02-08T22:49:51.384Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","apple-intelligence","assistant","bun","claude","cli","gpt","ink","llm","mcp","openrouter","terminal","typescript"],"created_at":"2026-01-13T20:40:29.173Z","updated_at":"2026-02-09T01:05:08.662Z","avatar_url":"https://github.com/cameronrye.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo.svg\" alt=\"Clarissa\" width=\"128\" height=\"128\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eClarissa\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  An AI-powered terminal assistant with tool execution capabilities\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/clarissa\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/clarissa\" alt=\"npm version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/clarissa\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/clarissa\" alt=\"npm downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/cameronrye/clarissa/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/npm/l/clarissa\" alt=\"license\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/cameronrye/clarissa/actions/workflows/release.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/cameronrye/clarissa/release.yml\" alt=\"build status\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://bun.sh\"\u003e\u003cimg src=\"https://img.shields.io/badge/runtime-Bun-f9f1e1?logo=bun\" alt=\"Bun\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.typescriptlang.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/TypeScript-5.x-blue?logo=typescript\" alt=\"TypeScript\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg src=\"https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey\" alt=\"platform\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg src=\"https://img.shields.io/badge/macOS-signed%20%26%20notarized-success\" alt=\"macOS signed\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/cameronrye/clarissa\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/cameronrye/clarissa\" alt=\"GitHub stars\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/cameronrye/clarissa/issues\"\u003e\u003cimg src=\"https://img.shields.io/github/issues/cameronrye/clarissa\" alt=\"issues\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/cameronrye/clarissa\"\u003e\u003cimg src=\"https://img.shields.io/github/last-commit/cameronrye/clarissa\" alt=\"last commit\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/cameronrye/clarissa/pulls\"\u003e\u003cimg src=\"https://img.shields.io/badge/PRs-welcome-brightgreen\" alt=\"PRs welcome\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nClarissa 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 (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).\n\n## Features\n\n- **Multi-provider support** - Cloud (OpenRouter, OpenAI, Anthropic) and local (Apple Intelligence, LM Studio, GGUF) providers\n- **Multi-model support** - Switch between Claude, GPT-4, Gemini, Llama, DeepSeek, and 100+ models\n- **Apple Intelligence** - On-device AI with Apple Foundation Models on macOS 26+ with full tool calling\n- **Local model inference** - Download and run GGUF models directly via node-llama-cpp\n- **Streaming responses** - Real-time token streaming for responsive conversations\n- **Built-in tools** - File operations, Git integration, shell commands, web fetching, and more\n- **MCP integration** - Connect to external MCP servers to extend functionality\n- **Session management** - Save and restore conversation history\n- **Memory persistence** - Remember facts across sessions with `/remember` and `/memories`\n- **Context management** - Automatic token tracking and context truncation\n- **Tool confirmation** - Approve or reject potentially dangerous operations\n- **One-shot mode** - Run single commands directly from your shell\n- **Piped input** - Pipe content from other commands for processing\n- **Auto-update** - Check for and install updates with `clarissa upgrade`\n\n## How It Works\n\nClarissa implements the **ReAct (Reasoning + Acting) agent pattern**, where an LLM reasons about tasks and takes actions through tool execution in an iterative loop.\n\n### Architecture Overview\n\n```mermaid\nflowchart LR\n    subgraph Input\n        A[User Message]\n        B[Piped Content]\n    end\n\n    subgraph Clarissa\n        C[Agent Loop]\n        D[LLM Client]\n        E[Tool Registry]\n        F[Context Manager]\n        G[Provider Registry]\n    end\n\n    subgraph Cloud Providers\n        H[OpenRouter]\n        I[OpenAI]\n        J[Anthropic]\n    end\n\n    subgraph Local Providers\n        K[Apple Intelligence]\n        L[LM Studio]\n        M[Local GGUF]\n    end\n\n    subgraph External\n        N[MCP Servers]\n    end\n\n    A --\u003e C\n    B --\u003e C\n    C \u003c--\u003e D\n    C \u003c--\u003e E\n    C \u003c--\u003e F\n    D \u003c--\u003e G\n    G \u003c--\u003e H\n    G \u003c--\u003e I\n    G \u003c--\u003e J\n    G \u003c--\u003e K\n    G \u003c--\u003e L\n    G \u003c--\u003e M\n    E \u003c-.-\u003e N\n```\n\nThe system connects your terminal to various LLM providers. When you ask Clarissa to perform a task, it:\n\n1. Sends your message to the LLM along with available tool definitions\n2. Receives a response that may include tool calls (e.g., read a file, run a command)\n3. Executes the requested tools and feeds results back to the LLM\n4. Repeats until the LLM provides a final answer\n\n### The ReAct Loop\n\n```mermaid\nflowchart TD\n    A[User Input] --\u003e B[Add to Conversation]\n    B --\u003e C[Send to LLM]\n    C --\u003e D{Response Type?}\n    D --\u003e|Tool Calls| E[Execute Tools]\n    E --\u003e F[Add Results to History]\n    F --\u003e C\n    D --\u003e|Final Answer| G[Display Response]\n```\n\nThis loop continues until the LLM responds without requesting any tools, indicating it has completed the task. A maximum iteration limit prevents infinite loops.\n\n### Key Concepts\n\n| Concept | Description |\n|---------|-------------|\n| **Tool Confirmation** | Potentially dangerous tools (file writes, shell commands) require approval before execution. Use `/yolo` to auto-approve. |\n| **Context Management** | Clarissa tracks token usage and automatically truncates older messages when approaching the model's context limit. |\n| **Session Persistence** | Conversations can be saved to `~/.clarissa/sessions/` and restored later with `/save` and `/load`. |\n| **Memory System** | Use `/remember` to store facts that persist across sessions and are included in every conversation. |\n| **MCP Extensibility** | Connect to [Model Context Protocol](https://modelcontextprotocol.io/) servers to add custom tools without modifying Clarissa's code. |\n\nFor detailed architecture documentation, see the [Architecture Guide](https://cameronrye.github.io/clarissa/docs/architecture/).\n\n## Requirements\n\n- [Bun](https://bun.sh) v1.0 or later (for running from source or npm install)\n- At least one LLM provider:\n  - [OpenRouter API key](https://openrouter.ai/keys) (100+ models)\n  - [OpenAI API key](https://platform.openai.com/api-keys) (GPT models)\n  - [Anthropic API key](https://console.anthropic.com/settings/keys) (Claude models)\n  - Apple Intelligence (macOS 26+ with Apple Silicon)\n  - [LM Studio](https://lmstudio.ai) (local server)\n  - Local GGUF model (via `clarissa download`)\n\n## Installation\n\n### From npm (recommended)\n\n```bash\n# Using bun\nbun install -g clarissa\n\n# Using npm\nnpm install -g clarissa\n```\n\n### From source\n\n```bash\ngit clone https://github.com/cameronrye/clarissa.git\ncd clarissa\nbun install\nbun link\n```\n\n### Standalone binary\n\nDownload a pre-built binary from the [releases page](https://github.com/cameronrye/clarissa/releases) and add it to your PATH:\n\n```bash\n# Example for macOS ARM\nchmod +x clarissa-macos-arm64\nmv clarissa-macos-arm64 /usr/local/bin/clarissa\n```\n\n## Configuration\n\n### Quick Setup\n\nRun the interactive setup to configure your API keys:\n\n```bash\nclarissa init\n```\n\nThis will prompt you for API keys for OpenRouter, OpenAI, and Anthropic. You can skip any provider you don't want to use.\n\n### Manual Configuration\n\nCreate a config file at `~/.clarissa/config.json`:\n\n```json\n{\n  \"openrouterApiKey\": \"sk-or-...\",\n  \"openaiApiKey\": \"sk-...\",\n  \"anthropicApiKey\": \"sk-ant-...\",\n  \"provider\": \"openrouter\",\n  \"model\": \"anthropic/claude-sonnet-4\"\n}\n```\n\nOr set API keys as environment variables:\n\n```bash\nexport OPENROUTER_API_KEY=sk-or-...\nexport OPENAI_API_KEY=sk-...\nexport ANTHROPIC_API_KEY=sk-ant-...\n```\n\n### Configuration Options\n\n| Config Key | Env Variable | Description |\n|------------|--------------|-------------|\n| `openrouterApiKey` | `OPENROUTER_API_KEY` | OpenRouter API key (100+ models) |\n| `openaiApiKey` | `OPENAI_API_KEY` | OpenAI API key (GPT models) |\n| `anthropicApiKey` | `ANTHROPIC_API_KEY` | Anthropic API key (Claude models) |\n| `provider` | - | Preferred provider (auto-detected if not set) |\n| `model` | `OPENROUTER_MODEL` | Default model to use |\n| `localModelPath` | - | Path to local GGUF model file |\n| `maxIterations` | `MAX_ITERATIONS` | Maximum tool iterations (default: 10) |\n| `debug` | `DEBUG` | Enable debug logging |\n| `mcpServers` | - | MCP servers to auto-load |\n\n### Providers\n\nClarissa automatically selects the best available provider based on your configuration:\n\n| Provider | Type | Requirements |\n|----------|------|--------------|\n| `openrouter` | Cloud | API key |\n| `openai` | Cloud | API key |\n| `anthropic` | Cloud | API key |\n| `apple-ai` | Local | macOS 26+, Apple Silicon |\n| `lmstudio` | Local | LM Studio running on localhost:1234 |\n| `local-llama` | Local | Downloaded GGUF model |\n\nSwitch providers with:\n\n```bash\nclarissa providers anthropic    # CLI\n/provider anthropic             # Interactive\n```\n\n### MCP Server Configuration\n\nAdd MCP servers to your config file to auto-load them on startup:\n\n```json\n{\n  \"apiKey\": \"your_api_key_here\",\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/dir\"]\n    },\n    \"github\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-github\"],\n      \"env\": { \"GITHUB_TOKEN\": \"your_token\" }\n    }\n  }\n}\n```\n\nUse `/mcp` to view connected servers and `/tools` to see available tools.\n\n## Usage\n\n### Interactive Mode\n\nStart Clarissa in interactive mode:\n\n```bash\nclarissa\n```\n\n### One-Shot Mode\n\nRun a single command and exit:\n\n```bash\nclarissa \"What files are in this directory?\"\n```\n\n### Piped Input\n\nPipe content from other commands:\n\n```bash\ncat error.log | clarissa \"Explain this error\"\ngit diff | clarissa \"Write a commit message for these changes\"\n```\n\n### CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `clarissa` | Start interactive mode |\n| `clarissa \"\u003cmessage\u003e\"` | One-shot query mode |\n| `clarissa init` | Set up API keys interactively |\n| `clarissa upgrade` | Upgrade to the latest version |\n| `clarissa config` | View current configuration |\n| `clarissa history` | Show one-shot query history |\n| `clarissa providers [NAME]` | List providers or switch to one |\n| `clarissa download [ID]` | Download a local GGUF model |\n| `clarissa models` | List downloaded models |\n| `clarissa use \u003cFILE\u003e` | Set a downloaded model as active |\n| `clarissa app \"\u003cmessage\u003e\"` | Open macOS app with optional question |\n\n### CLI Options\n\n| Option | Description |\n|--------|-------------|\n| `-c, --continue` | Continue the last session |\n| `-m, --model MODEL` | Use a specific model |\n| `--list-models` | List available models |\n| `--check-update` | Check for available updates |\n| `--debug` | Enable debug output |\n| `-h, --help` | Show help |\n| `-v, --version` | Show version |\n\n### Interactive Commands\n\n| Command | Description |\n|---------|-------------|\n| `/help` | Show available commands |\n| `/new` | Start a new conversation |\n| `/last` | Load the most recent session |\n| `/save [NAME]` | Save current session |\n| `/sessions` | List saved sessions |\n| `/load ID` | Load a saved session |\n| `/delete ID` | Delete a saved session |\n| `/remember \u003cfact\u003e` | Save a memory |\n| `/memories` | List saved memories |\n| `/forget \u003c#\\|ID\u003e` | Forget a memory |\n| `/model [NAME]` | Show or switch the current model |\n| `/provider [NAME]` | Show or switch the LLM provider |\n| `/mcp CMD ARGS` | Connect to a stdio MCP server |\n| `/mcp sse URL` | Connect to an HTTP/SSE MCP server |\n| `/tools` | List available tools |\n| `/context` | Show context window usage |\n| `/yolo` | Toggle auto-approve mode |\n| `/version` | Show version info |\n| `/upgrade` | Upgrade to latest version |\n| `/exit` | Exit Clarissa |\n\n### Keyboard Shortcuts\n\n| Shortcut | Action |\n|----------|--------|\n| `Ctrl+C` | Cancel current operation / Exit |\n| `Ctrl+P` | Enhance prompt with AI |\n| `Up/Down` | Navigate input history |\n\n### Built-in Tools\n\n**File Operations**\n- `read_file` - Read file contents\n- `write_file` - Write or create files\n- `patch_file` - Apply patches to files\n- `list_directory` - List directory contents\n- `search_files` - Search for files by pattern\n\n**Git Integration**\n- `git_status` - Show repository status\n- `git_diff` - Show changes\n- `git_log` - View commit history\n- `git_add` - Stage files\n- `git_commit` - Commit changes\n- `git_branch` - Manage branches\n\n**System**\n- `bash` - Execute shell commands\n- `calculator` - Perform calculations\n\n**Web**\n- `web_fetch` - Fetch and parse web pages\n\n### File Context References\n\nReference files directly in your prompts using `@filename` syntax:\n\n```\nExplain what @src/index.ts does\nReview @package.json:1-20 for issues\nCompare @README.md with @CHANGELOG.md\n```\n\n### MCP Integration\n\nConnect to Model Context Protocol servers to extend Clarissa with additional tools:\n\n```bash\n# Stdio server (local process)\n/mcp npx -y @modelcontextprotocol/server-filesystem /path/to/directory\n\n# HTTP/SSE server (remote URL)\n/mcp sse https://mcp.example.com/api\n```\n\n## Development\n\nRun with hot reloading:\n\n```bash\nbun run dev\n```\n\nRun tests:\n\n```bash\nbun test\n```\n\n### Building Binaries\n\nBuild for your current platform:\n\n```bash\nbun run build:current\n```\n\nBuild for all platforms:\n\n```bash\nbun run build:all\n```\n\nBinaries are output to the `dist/` directory.\n\n### Publishing to npm\n\n```bash\nnpm publish\n```\n\n## Project Structure\n\n```\nsrc/\n  index.tsx        # CLI entry point\n  agent.ts         # ReAct agent loop implementation\n  update.ts        # Auto-update functionality\n  config/          # Environment configuration\n  history/         # One-shot query history\n  llm/             # LLM client and context management\n    providers/     # Multi-provider abstraction (OpenRouter, OpenAI, Anthropic, Apple, etc.)\n  mcp/             # MCP client integration\n  memory/          # Long-term memory persistence\n  models/          # Local model download and management\n  preferences/     # User preferences persistence\n  session/         # Session persistence\n  tools/           # Tool definitions\n  ui/              # Ink UI components\n```\n\n## License\n\nMIT\n\n---\n\nMade with ❤️ by [Cameron Rye](https://rye.dev)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcameronrye%2Fclarissa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcameronrye%2Fclarissa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcameronrye%2Fclarissa/lists"}