How to Set Up Dexter Financial Research Agent: Complete Installation and Configuration Guide

Install Bun v1.0+, clone the virattt/dexter repository, run bun install, configure your .env file with OpenAI and Financial Datasets API keys, and launch with bun start to begin autonomous financial research.

Dexter is an open-source, CLI-based autonomous agent designed to answer complex finance questions through iterative tool execution and LLM reasoning. This guide walks you through setting up the Dexter financial research agent from the virattt/dexter repository, covering installation, configuration, and your first query.

Prerequisites for Setting Up Dexter

Before installing Dexter, ensure your environment meets the following requirements.

Install Bun Runtime

Dexter requires Bun v1.0 or higher as its JavaScript runtime and package manager. Install it via the official installer:

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

For macOS, Linux, or Windows-specific instructions, refer to the repository's README.

Obtain Required API Keys

You need API keys for the following services:

• OpenAI API key – Required for LLM inference
• Financial Datasets API key – Required for stock data and SEC filings
• Exa or Tavily API key – Optional, enables the web_search tool for broader research

Clone and Install the Repository

Once prerequisites are satisfied, download the source code and install dependencies:

git clone https://github.com/virattt/dexter.git
cd dexter
bun install

The bun install command resolves all TypeScript dependencies and creates the node_modules directory.

Configure Environment Variables

Dexter uses environment variables to manage API keys and feature flags. Copy the example configuration file and edit it with your credentials:

cp env.example .env

Edit .env and add your keys:

OPENAI_API_KEY=sk-...
FINANCIAL_DATASETS_API_KEY=...
EXASEARCH_API_KEY=...  # Optional

The CLI reads these variables at startup via src/utils/env.ts. Missing required keys trigger clear runtime errors in the LLM factory (src/model/llm.ts lines 53-58).

Launch Dexter and Run Your First Query

Start the interactive CLI interface:

bun start

This command launches the Ink-based terminal UI defined in src/cli.tsx. You’ll see a welcome screen, model selector (if no model is cached), and an input prompt ready for financial queries.

Understanding the Agent Loop

The core intelligence resides in src/agent/agent.ts, which implements an iterative agent-loop pattern:

1. System prompt construction – Combines the selected LLM provider configuration with registered tool descriptions from src/tools/registry.ts.
2. Iteration cycle – The agent calls the LLM, parses tool invocations, and executes them via AgentToolExecutor.
3. Scratchpad management – Results accumulate in a scratchpad. When context exceeds token limits, manageContextThreshold discards the oldest tool results to maintain performance.
4. Final synthesis – Once no more tool calls are required, the agent generates a definitive answer using the complete scratchpad context.

Example Financial Research Query

Try this query to test the setup:

> What was Apple's revenue growth YoY for the last 5 years?

Dexter will:

• Plan – Determine it needs financial_search and financial_metrics tools
• Execute – Call the Financial Datasets API via src/tools/finance/financial-search.ts and financial-metrics.ts
• Iterate – Fetch additional data if initial results are incomplete
• Finalize – Return a concise analysis of Apple's 5-year revenue trajectory

Intermediate tool calls are logged to .dexter/scratchpad/ for debugging purposes.

Changing Models and Exiting

• Switch models – Type /model at any prompt to enter the provider-selection flow (defined in src/cli.tsx lines 90-98 and src/hooks/useModelSelection.ts)
• Exit – Type exit or quit to close the session

Optional: Connect Dexter via WhatsApp

To interact with Dexter from your mobile device, enable the WhatsApp gateway:

bun run gateway:login   # Scan the QR code with your phone

bun run gateway         # Start the listener

Messages you send to yourself on WhatsApp will receive responses prefixed with [Dexter]. Detailed configuration steps are documented in src/gateway/channels/whatsapp/README.md.

Programmatic Usage and Custom Tools

Using the Agent API Directly

You can integrate Dexter into existing Node.js applications without the CLI:

import { Agent } from './src/agent/agent.js';

async function main() {
  const agent = Agent.create({ model: 'gpt-4o' });
  const query = "What is Nvidia's 2023 free cash flow?";

  for await (const event of agent.run(query)) {
    if (event.type === 'thinking') console.log('🧠', event.message);
    if (event.type === 'tool_result') console.log('🔧', event.toolName, event.result);
    if (event.type === 'answer_start') console.log('📢 Answer:');
    if (event.type === 'done') console.log(event.answer);
  }
}

main();

This uses the public Agent class (see src/agent/agent.ts lines 21-30).

Registering Custom Tools

Extend Dexter's capabilities by adding custom data sources:

// src/tools/custom/my-tool.ts
import { StructuredTool } from '@langchain/core/tools';

export const myTool = new StructuredTool({
  name: 'my_tool',
  description: 'Returns a static message for demo purposes.',
  async func(_: { }) {
    return 'Hello from my custom tool!';
  },
});

// Register it in src/tools/registry.ts
tools.push({
  name: 'my_tool',
  tool: myTool,
  description: 'Custom demo tool.',
});

After rebuilding (bun install), the LLM can invoke my_tool just like the built-in financial data sources.

Summary

• Dexter is a CLI-based autonomous agent that answers finance questions through iterative tool execution and LLM reasoning.
• Installation requires Bun v1.0+, API keys for OpenAI and Financial Datasets, and a simple bun install.
• Configuration happens via .env file, validated at runtime in src/model/llm.ts and src/utils/env.ts.
• Architecture follows an agent-loop pattern in src/agent/agent.ts with scratchpad management and automatic context threshold handling.
• Extensibility allows custom tools via src/tools/registry.ts and programmatic usage through the Agent class API.

Frequently Asked Questions

What API keys are required to set up Dexter financial research agent?

You need an OpenAI API key and a Financial Datasets API key to run Dexter. These are mandatory for LLM inference and financial data access respectively. Optionally, you can add an Exa or Tavily API key to enable the web search tool for broader research capabilities.

Can I use Dexter without the interactive CLI interface?

Yes. You can import the Agent class directly from src/agent/agent.ts and invoke it programmatically in Node.js applications. The Agent.create() method accepts a model configuration, and agent.run() returns an async iterator yielding thinking events, tool results, and final answers.

How does Dexter handle long-running financial research tasks?

Dexter implements context management in src/agent/agent.ts through the manageContextThreshold function. When the scratchpad accumulates tool results that approach the LLM's token limit, the system automatically discards the oldest entries while preserving the most recent context, allowing the agent to continue iterative research without hitting context windows.

Is it possible to add custom financial data sources to Dexter?

Yes. You can extend Dexter by creating a new StructuredTool class and registering it in src/tools/registry.ts. The registry dynamically discovers available tools based on environment variables and skill files, making custom integrations immediately available to the LLM for autonomous invocation during research tasks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}