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

> Learn to run the Dexter agent with TypeScript. Follow our guide to install Bun, clone the repository, and launch the CLI or integrate the Agent class for custom workflows. Get started easily!

- Repository: [Virat Singh/dexter](https://github.com/virattt/dexter)
- Tags: how-to-guide
- Published: 2026-02-19

---

**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`](https://github.com/virattt/dexter/blob/main/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`](https://github.com/virattt/dexter/blob/main/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:

```bash
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.

```bash

# Launch the interactive CLI

bun start

```

Under the hood, `bun start` executes [`src/index.tsx`](https://github.com/virattt/dexter/blob/main/src/index.tsx), which renders the `<CLI />` component defined in [`src/cli.tsx`](https://github.com/virattt/dexter/blob/main/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`](https://github.com/virattt/dexter/blob/main/src/agent/agent.ts), which orchestrates LLM calls through `callLlm` in [`src/model/llm.ts`](https://github.com/virattt/dexter/blob/main/src/model/llm.ts) and manages tool execution.

For development with hot-reloading, use:

```bash
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.

```typescript
// 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:

```bash
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`](https://github.com/virattt/dexter/blob/main/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`](https://github.com/virattt/dexter/blob/main/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`](https://github.com/virattt/dexter/blob/main/src/model/llm.ts)** – Implements `callLlm()` with provider detection (OpenAI, Anthropic, Google, Ollama) and prompt caching for Anthropic models.
- **[`src/tools/registry.ts`](https://github.com/virattt/dexter/blob/main/src/tools/registry.ts)** – Dynamically registers financial data tools based on available API keys in your `.env` file.
- **[`src/evals/run.ts`](https://github.com/virattt/dexter/blob/main/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`](https://github.com/virattt/dexter/blob/main/src/index.tsx) and [`src/cli.tsx`](https://github.com/virattt/dexter/blob/main/src/cli.tsx).
- **Use programmatically** by importing `Agent` from [`src/agent/agent.js`](https://github.com/virattt/dexter/blob/main/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`](https://github.com/virattt/dexter/blob/main/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`](https://github.com/virattt/dexter/blob/main/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`](https://github.com/virattt/dexter/blob/main/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.