---
title: "Clarissa"
description: "An AI-powered terminal assistant with tool execution capabilities, built with Bun and Ink, featuring streaming responses, MCP integration, and session persistence."
impact: "Brings intelligent AI assistance to the command line with multi-model support and extensible tool execution"
github_url: "https://github.com/cameronrye/clarissa"
demo_url: "https://clarissa.run"
technologies: ["TypeScript", "Bun", "Ink", "React", "MCP", "OpenRouter"]
featured: true
order: 1
architecture: "flowchart LR\n    subgraph Input\n        A[User Message]\n        B[Piped Content]\n    end\n    subgraph Clarissa\n        C[Agent Loop]\n        D[LLM Client]\n        E[Tool Registry]\n        F[Context Manager]\n    end\n    subgraph External\n        G[OpenRouter API]\n        H[MCP Servers]\n    end\n    A --> C\n    B --> C\n    C <--> D\n    C <--> E\n    C <--> F\n    D <--> G\n    E -.-> H\n"
problem: "Developers need AI assistance in terminal workflows, but existing solutions lack the ability to execute tools, persist context across sessions, and extend functionality through standardized protocols. Most terminal AI tools are limited to simple chat interfaces without the ability to take action on behalf of the user."
solution: "Built an AI agent that implements the ReAct (Reasoning + Acting) pattern, enabling the LLM to reason about tasks and execute tools in an iterative loop. The agent features built-in tools for file operations, Git integration, and shell commands, with extensibility through the Model Context Protocol (MCP). Session persistence and a memory system allow context to carry across conversations."
results: ["Multi-model support via OpenRouter (Claude, GPT-4, Gemini, Llama, DeepSeek)", "Real-time streaming responses with automatic context management", "Session persistence and cross-session memory system", "MCP integration for extensibility without code changes"]
metrics: [{"label":"Built-in Tools","value":"14"}, {"label":"Supported Models","value":"10+"}, {"label":"Context Window","value":"Up to 1M"}, {"label":"Install Methods","value":"3"}]
canonical_url: https://rye.dev/projects/clarissa/
---

import MCPToolDemo from '../../components/demos/MCPToolDemo.tsx';

export const clarissaTools = [
  {
    name: 'read_file',
    description: 'Read the contents of a file',
    request: { tool: 'read_file', path: './src/agent.ts' },
    response: { content: 'import { llmClient } from "./llm/client.ts";\nimport { toolRegistry } from "./tools/index.ts";\n...', lines: 203 }
  },
  {
    name: 'bash',
    description: 'Execute shell commands',
    request: { tool: 'bash', command: 'git status --short' },
    response: { stdout: ' M src/agent.ts\n?? src/tools/new-tool.ts', exitCode: 0 }
  },
  {
    name: 'git_diff',
    description: 'Show changes in the repository',
    request: { tool: 'git_diff', staged: false },
    response: { diff: 'diff --git a/src/agent.ts b/src/agent.ts\n@@ -1,5 +1,6 @@\n+import { memoryManager } from "./memory";', files: 1 }
  },
  {
    name: 'web_fetch',
    description: 'Fetch and parse web pages',
    request: { tool: 'web_fetch', url: 'https://example.com' },
    response: { title: 'Example Domain', content: 'This domain is for use in illustrative examples...', status: 200 }
  }
];

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).

<div class="my-8 p-6 bg-white/60 dark:bg-gray-800/60 backdrop-blur-sm rounded-xl border border-gray-200/50 dark:border-gray-700/50">
  <MCPToolDemo client:visible serverName="clarissa" tools={clarissaTools} />
</div>

## Key Features

- **ReAct Agent Pattern**: Implements the Reasoning + Acting loop for intelligent task execution
- **Multi-model Support**: Switch between Claude, GPT-4, Gemini, Llama, and more via OpenRouter
- **Tool Execution**: Built-in tools for files, Git, shell commands, and web fetching
- **MCP Integration**: Extend with external tools through the Model Context Protocol
- **Session Persistence**: Save and restore conversation history across sessions
- **Memory System**: Remember facts across sessions with `/remember` and `/memories`
- **Context Management**: Automatic token tracking and intelligent context truncation
- **Tool Confirmation**: Approve or reject potentially dangerous operations

## The ReAct Loop

The agent implements an iterative loop where it:

1. Receives user input and sends it to the LLM with available tool definitions
2. If the LLM responds with tool calls, executes them and feeds results back
3. Repeats until the LLM provides a final answer without requesting tools

This pattern enables complex multi-step tasks while maintaining safety through tool confirmation.

## Usage Modes

```bash
# Interactive mode
clarissa

# One-shot mode
clarissa "What files are in this directory?"

# Piped input
git diff | clarissa "Write a commit message for these changes"
```