Carlo 🤖

Carlo is an AI-powered CLI chatbot assistant built with TypeScript, Ink (React for CLI), and LangChain. It features an agentic loop with web search and browsing capabilities.

Table of Contents

• 👋 Overview
• ✅ Prerequisites
• 💻 How to Install
• 🚀 How to Run
• 🐛 How to Debug
• 📱 How to Use with WhatsApp
• 🤝 How to Contribute
• 📄 License

👋 Overview

Carlo is a general-purpose AI assistant that runs in your terminal. It can search the web, browse pages, and answer questions using an agentic tool-calling loop.

Key Capabilities:

• Agentic Tool Loop: Automatically selects and executes tools to gather information
• Web Search: Search the web for current information (via Exa, Perplexity, or Tavily)
• Web Browsing: Navigate and extract content from web pages
• Multi-Provider LLM Support: OpenAI, Anthropic, Google, xAI, OpenRouter, Ollama
• Safety Features: Built-in loop detection and step limits to prevent runaway execution

✅ Prerequisites

• Bun runtime (v1.0 or higher)
• At least one LLM API key (e.g., OpenAI, Anthropic, Google)
• Exa API key (optional, for web search)

Installing Bun

If you don't have Bun installed, you can install it using curl:

macOS/Linux:

curl -fsSL https://bun.com/install | bash

Windows:

powershell -c "irm bun.sh/install.ps1|iex"

After installation, restart your terminal and verify Bun is installed:

bun --version

💻 How to Install

1. Clone the repository:

git clone https://github.com/virattt/carlo.git
cd carlo

2. Install dependencies with Bun:

bun install

3. Set up your environment variables:

# Copy the example environment file
cp env.example .env

# Edit .env and add your API keys (if using cloud providers)
# OPENAI_API_KEY=your-openai-api-key
# ANTHROPIC_API_KEY=your-anthropic-api-key (optional)
# GOOGLE_API_KEY=your-google-api-key (optional)
# XAI_API_KEY=your-xai-api-key (optional)
# OPENROUTER_API_KEY=your-openrouter-api-key (optional)

# (Optional) If using Ollama locally
# OLLAMA_BASE_URL=http://127.0.0.1:11434

# Web Search (Exa preferred, Perplexity, or Tavily)
# EXASEARCH_API_KEY=your-exa-api-key
# PERPLEXITY_API_KEY=your-perplexity-api-key
# TAVILY_API_KEY=your-tavily-api-key

🚀 How to Run

Run Carlo in interactive mode:

bun start

Or with watch mode for development:

bun dev

🐛 How to Debug

Carlo logs all tool calls to a scratchpad file for debugging and history tracking. Each query creates a new JSONL file in .carlo/scratchpad/.

Scratchpad location:

.carlo/scratchpad/
├── 2026-01-30-111400_9a8f10723f79.jsonl
├── 2026-01-30-143022_a1b2c3d4e5f6.jsonl
└── ...

Each file contains newline-delimited JSON entries tracking:

• init: The original query
• tool_result: Each tool call with arguments, raw result, and LLM summary
• thinking: Agent reasoning steps

This makes it easy to inspect exactly what data the agent gathered and how it interpreted results.

📱 How to Use with WhatsApp

Chat with Carlo through WhatsApp by linking your phone to the gateway. Messages you send to yourself are processed by Carlo and responses are sent back to the same chat.

Quick start:

# Link your WhatsApp account (scan QR code)
bun run gateway:login

# Start the gateway (runs under Node for WhatsApp reliability)
bun run gateway

Then open WhatsApp, go to your own chat (message yourself), and ask Carlo a question.

For detailed setup instructions, configuration options, and troubleshooting, see the WhatsApp Gateway README.

🤝 How to Contribute

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

Important: Please keep your pull requests small and focused. This will make it easier to review and merge.

📄 License

This project is licensed under the MIT License.