How to Run the Dexter Agent with TypeScript: Complete Setup Guide

You can run the Dexter agent with TypeScript by installing Bun ≥1.0, cloning the virattt/dexter repository, and executing bun start to launch the interactive CLI, or by importing the Agent class from src/agent/agent.ts for custom programmatic workflows.

Dexter is an autonomous financial-research agent built with TypeScript and Ink. According to the virattt/dexter source code, the entire codebase runs natively under Bun without separate compilation steps. This guide covers both interactive CLI usage and programmatic integration so you can run the Dexter agent with TypeScript in any environment.

Prerequisites

Before running Dexter, ensure you have the following:

• Bun ≥1.0 – The runtime executes TypeScript files directly via bun commands. Install with curl -fsSL https://bun.com/install | bash (macOS/Linux) or the PowerShell command from the repository README.
• API keys – OpenAI and Financial Datasets keys are required. The LLM factory in src/model/llm.ts resolves providers based on environment variables.
• Git – To clone the source repository.

Installing the Dexter Repository

Clone the repository and install dependencies using Bun's package manager:

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

# Install TypeScript dependencies

bun install

# Configure environment variables

cp env.example .env

# Edit .env to add OPENAI_API_KEY and other required keys

All source files maintain strict TypeScript typing; no additional build configuration is necessary.

Running the Interactive CLI

The repository includes a bundled Ink-powered interface that streams the agent's thoughts and tool executions.

# Launch the interactive CLI

bun start

Under the hood, bun start executes src/index.tsx, which renders the <CLI /> component defined in src/cli.tsx. The useAgentRunner hook instantiates an Agent via Agent.create() and streams events to the terminal. The core loop lives in src/agent/agent.ts, which orchestrates LLM calls through callLlm in src/model/llm.ts and manages tool execution.

For development with hot-reloading, use:

bun dev

Programmatic Usage: Importing the Agent Class

To embed Dexter in your own TypeScript projects, import the Agent class directly. Bun's ESM resolver requires the .js extension even for TypeScript sources.

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

async function main() {
  // Initialize with model and iteration limits
  const agent = Agent.create({ model: 'gpt-4o', maxIterations: 8 });

  // Execute a research query
  for await (const event of agent.run('What is the current P/E ratio of Tesla?')) {
    switch (event.type) {
      case 'thinking':
        console.log('🤔', event.message);
        break;
      case 'answer_start':
        console.log('📝 Generating final answer...');
        break;
      case 'done':
        console.log('✅ Answer:', event.answer);
        console.log('🔧 Tools used:', event.toolCalls);
        console.log('⏱️ Total iterations:', event.iterations);
        break;
    }
  }
}

main().catch(console.error);

Execute the script with:

bun run example.ts

The Agent.create method accepts configuration options to customize model selection and iteration limits. The run() method returns an async generator yielding event objects that track the agent's internal state, identical to the behavior used by the CLI in src/hooks/useAgentRunner.ts.

Key Architecture Components

Understanding the source structure helps when running the Dexter agent with TypeScript in custom configurations:

• src/agent/agent.ts – Contains the Agent class with the run() loop, context management via manageContextThreshold, and tool execution through AgentToolExecutor.
• src/model/llm.ts – Implements callLlm() with provider detection (OpenAI, Anthropic, Google, Ollama) and prompt caching for Anthropic models.
• src/tools/registry.ts – Dynamically registers financial data tools based on available API keys in your .env file.
• src/evals/run.ts – Provides a test harness demonstrating programmatic Agent usage that you can adapt for batch processing.

Summary

• Install Bun ≥1.0 to execute TypeScript without compilation.
• Run interactively with bun start, which launches the Ink UI defined in src/index.tsx and src/cli.tsx.
• Use programmatically by importing Agent from src/agent/agent.js, calling Agent.create(), and iterating over agent.run(query).
• Configure API keys in .env before execution; the CLI prompts for missing values.
• Reference src/evals/run.ts for production-ready integration patterns.

Frequently Asked Questions

Do I need to compile the TypeScript files before running Dexter?

No. Because Dexter runs on Bun, you can execute TypeScript files directly without a separate build step. Bun handles the transpilation internally when you run bun start or bun run example.ts.

Can I run Dexter with Node.js instead of Bun?

The virattt/dexter repository is optimized for Bun's runtime and package manager. While Node.js could theoretically run the compiled output, the source code relies on Bun-specific APIs and the bun command structure defined in package.json. Using Bun ≥1.0 is the supported method.

How does the Agent class handle context limits?

The Agent class in src/agent/agent.ts implements manageContextThreshold(), which estimates token usage and drops the oldest tool results when the conversation exceeds the CONTEXT_THRESHOLD. This ensures the LLM receives relevant recent data without exceeding model context windows.

What event types does the agent.run() generator emit?

The async generator yields events with types including thinking (intermediate reasoning), answer_start (beginning final generation), and done (completion with final answer and metadata). You can handle these in a switch statement to build custom UIs or logging systems.

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