dexter README

The project's README from github.com/virattt/dexter. As one markdown file: README.md.

Dexter 🤖

Dexter is an autonomous financial research agent that thinks, plans, and learns as it works. It performs analysis using task planning, self-reflection, and real-time market data. Think Claude Code, but built specifically for financial research.

Screenshot 2026-04-02 at 4 16 57 PM

Table of Contents

⚠️ Disclaimer

This project is for educational, entertainment, and informational purposes only. It is not intended for real trading or investment.

By using this software, you agree to use it solely for learning and informational purposes and accept all risks associated with its use.

👋 Overview

Dexter takes complex financial questions and turns them into clear, step-by-step research plans. It runs those tasks using live market data, checks its own work, and refines the results until it has a confident, data-backed answer.

Key Capabilities:

Twitter Follow Discord

Screenshot 2026-02-18 at 12 21 25 PM

✅ Prerequisites

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/dexter.git
cd dexter
  1. Install dependencies with Bun:
bun install
  1. 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)

# Institutional-grade market data for agents
# FINANCIAL_DATASETS_API_KEY=your-financial-datasets-api-key

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

# Web Search (Exa preferred, Tavily fallback)
# EXASEARCH_API_KEY=your-exa-api-key
# TAVILY_API_KEY=your-tavily-api-key

🚀 How to Run

Run Dexter in interactive mode:

bun start

Or with watch mode for development:

bun dev

📊 How to Evaluate

Dexter includes an evaluation suite that tests the agent against a dataset of financial questions. Evals use LangSmith for tracking and an LLM-as-judge approach for scoring correctness.

Run on all questions:

bun run src/evals/run.ts

Run on a random sample of data:

bun run src/evals/run.ts --sample 10

The eval runner displays a real-time UI showing progress, current question, and running accuracy statistics. Results are logged to LangSmith for analysis.

🐛 How to Debug

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

Scratchpad location:

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

Each file contains newline-delimited JSON entries tracking:

Example scratchpad entry:

{"type":"tool_result","timestamp":"2026-01-30T11:14:05.123Z","toolName":"get_income_statements","args":{"ticker":"AAPL","period":"annual","limit":5},"result":{...},"llmSummary":"Retrieved 5 years of Apple annual income statements showing revenue growth from $274B to $394B"}

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

📱 How to Use with WhatsApp

Chat with Dexter through WhatsApp by linking your phone to the gateway. Messages you send to yourself are processed by Dexter 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
bun run gateway

Then open WhatsApp, go to your own chat (message yourself), and ask Dexter 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.

dexter (virattt/dexter)

whatsapp
Searching Database…

27.7K ·GitHub
Dexter
What is this?Dexter is an autonomous agent that researches financial questions on its own: it plans the research steps, pulls real-time market data like income statements and cash flow statements, checks its own work, and keeps refining the answer until it is confident.
Is this a simple chatbot or does it actually do multi-step analysis on its own?It is closer to an autonomous coding agent than a chatbot: it decomposes a complex financial question into a structured plan, picks and runs the right tools itself, and self-validates before giving a final answer.
How do I get it running?Install the Bun runtime, clone the repository, run the Bun install step, set your environment variables, then launch it in interactive mode (or with watch mode for development).
What API keys do I need before I can use it?You need an OpenAI API key and a Financial Datasets API key; an Exa API key is optional and only needed for web search.
Can I trust its research for real trading decisions?No. The README explicitly states outputs may be wrong or incomplete and the project is for education and entertainment only, not financial, investment, tax or legal advice.
Can I chat with Dexter through WhatsApp?Yes, it includes a WhatsApp gateway you link to your phone; messages you send yourself in WhatsApp are processed by Dexter and answered back in the same chat.
How does the project measure if its answers are actually correct?It ships an evaluation suite that runs the agent against a dataset of financial questions and scores correctness with an LLM-as-judge, logging results to LangSmith for analysis.
How can I see exactly what the agent did to reach an answer?Every query writes a JSONL scratchpad file under .dexter/scratchpad/ recording the original query, every tool call with its arguments and result, and the agent's reasoning steps.
What safety mechanisms keep the agent from running forever?Dexter has built-in loop detection and step limits specifically designed to prevent runaway execution during autonomous research.
What are similar projects?openfang, CUAWright, brigade, Raven, open_deep_research, hermes-agent, MiMo-Code, open-pstack
Which topics is it in?market-data, deep-research, whatsapp, fintech, bun, langchain, playwright, autonomous-agents, finance, agentic-ai, sqlite, anthropic
Creator
virattt
Size
1.7 MB
Stars
27.7K
Updated
CommitSep 23Releasev1.1.0Sep 23
Age
1y
Commits · 90 Days