# virattt/dexter architecture

> Architecture diagram of the GitHub repository virattt/dexter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/virattt/dexter
- Repository: https://github.com/virattt/dexter

## Overview

1. **What this repository is**
Dexter is a Bun/TypeScript autonomous research agent focused on financial analysis. The core product is not a web app; it is an agent runtime that can be driven from an interactive local CLI/TUI, a WhatsApp gateway, an eval harness, and cron-style background jobs.

2. **Top-level execution surfaces**
The main entry points are `src/cli.ts` and `src/index.tsx` for the local interactive experience, `src/gateway/gateway.ts` for message-driven operation, `src/evals/run.ts` for benchmark runs, and the cron runner under `src/cron/runner.ts`. All of these ultimately delegate into shared agent orchestration rather than duplicating business logic.

3. **Shared agent core**
The main reasoning loop lives in `src/agent/*`. It includes planning, prompting, token counting, scratchpad logging, compacting/micro-compacting context, tool execution, and run-context management. This layer is the central “brain” that decides what to do next, calls tools, and synthesizes final answers.

4. **Model/provider boundary**
Model selection and provider abstraction are separated from the agent logic. `src/model/llm.ts`, `src/providers.ts`, and utilities under `src/utils/model.ts` adapt to multiple LLM backends such as OpenAI, Anthropic, Google, xAI, OpenRouter, and local Ollama. The agent asks for capabilities; provider code handles the concrete API/runtime differences.

5. **Tool execution layer**
Tools are a major architectural boundary in `src/tools/*`. They are grouped by domain: finance data, web/search, filesystem, browser, memory, cron, heartbeat, and skill helpers. The agent does not access external systems directly; it emits tool calls, and the tool registry/executor mediates all side effects and external I/O.

6. **Financial data and research integrations**
The finance toolset is the most important external dependency for Dexter’s domain. It exposes market data, fundamentals, filings, earnings, estimates, insider trades, news, stock prices, screening, and crypto helpers. The README highlights Financial Datasets as the primary institutional-grade data source, with search tools like Exa, Tavily, Perplexity, and X search as auxiliary research inputs.

7. **Memory and persistence**
`src/memory/*` provides long-term retrieval and persistence. It includes embeddings, chunking, indexing, search, MMR ranking, temporal decay, session file handling, and a backing database/store. This layer lets the agent recall prior work and relevant facts across turns, distinct from the short-lived per-run scratchpad.

8. **Skills as curated domain knowledge**
`src/skills/*` contains packaged research skills such as DCF and X-research. These are loaded and registered separately from tools, acting like reusable knowledge modules or playbooks that the agent can reference during analysis.

9. **Interactive UI and controller flow**
The local user experience is built from `src/components/*` and `src/controllers/*`. Controllers manage input history, model selection, and agent-run lifecycle, while components render chat logs, answer boxes, approval prompts, tool events, and debug/status panels. The UI layer collects user input, sends it into the shared agent runner, and streams progress/results back.

10. **WhatsApp gateway architecture**
The gateway under `src/gateway/*` turns Dexter into a conversational service over WhatsApp. It includes channel management, route resolution, access control, session persistence, deduplication, group/mention handling, heartbeat support, and a channel-specific WhatsApp implementation. Messages are ingested, normalized, routed to the agent runner, and then sent back outbound through the same channel abstraction.

11. **Operational safety and background workflows**
Several subsystems exist to keep the agent reliable: loop/step limits and self-validation in the agent core, approval prompts in the UI, heartbeat suppression and scheduling in gateway/cron, and logging/scratchpad files for traceability. This indicates a design that prioritizes controlled autonomy rather than unconstrained tool use.

12. **Evaluation and quality loop**
`src/evals/*` is a separate benchmark path, not part of user-facing inference. It runs the agent against a financial question dataset, shows progress/stats via its own components, and reports results with LangSmith and LLM-as-judge scoring. This creates a feedback loop for measuring agent quality without affecting production flows.

13. **Cross-cutting utilities and test boundary**
`src/utils/*` holds shared helpers for logging, caching, concurrency, token counting, markdown/table formatting, message queues, progress indicators, and history management. Tests are colocated around critical boundaries like access control, routing, dedupe, and agent runner behavior, which suggests the main architectural risk areas are orchestration and integration correctness.

14. **How data flows through the system**
A typical request enters through CLI/TUI or WhatsApp, is normalized by the controller/gateway, then handed to the agent runner. The agent consults prompts, memory, and skills, chooses tools, gathers external financial/search/file data, stores useful traces in memory/scratchpad, and finally returns a synthesized answer to the originating surface. The same core loop is reused across interactive use, gateway use, and evaluation runs.

Main entry points: [`src/agent/agent.ts`](https://github.com/virattt/dexter/blob/main/src/agent/agent.ts) (Agent runtime), [`src/tools/registry.ts`](https://github.com/virattt/dexter/blob/main/src/tools/registry.ts) (Tool registry), [`src/controllers/agent-runner.ts`](https://github.com/virattt/dexter/blob/main/src/controllers/agent-runner.ts) (UI controller), [`src/gateway/channels/whatsapp/index.ts`](https://github.com/virattt/dexter/blob/main/src/gateway/channels/whatsapp/index.ts) (WhatsApp)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry surfaces"]
  node_src_cli["CLI<br/>entrypoint<br/>[cli.ts]"]
  node_src_index["TUI app<br/>entrypoint<br/>[index.tsx]"]
  node_src_gateway["Gateway<br/>entrypoint<br/>[gateway.ts]"]
  node_src_cron_runner["Cron runner<br/>entrypoint<br/>[runner.ts]"]
  node_src_evals_run["Eval runner<br/>entrypoint<br/>[run.ts]"]
end

subgraph group_agent["Agent core"]
  node_agent_runtime{{"Agent runtime<br/>orchestrator<br/>[agent.ts]"}}
  node_agent_prompts["Prompts<br/>prompting<br/>[prompts.ts]"]
  node_agent_run_context[("Run context<br/>state<br/>[run-context.ts]")]
  node_agent_tool_executor{{"Tool executor<br/>[tool-executor.ts]"}}
  node_agent_scratchpad["Scratchpad<br/>trace<br/>[scratchpad.ts]"]
  node_agent_compaction["Context compacting<br/>memory-control<br/>[compact.ts]"]
  node_agent_token_counter(("Token counter<br/>telemetry<br/>[token-counter.ts]"))
end

subgraph group_integrations["Integrations"]
  node_llm_boundary{{"LLM boundary<br/>model-adapter<br/>[llm.ts]"}}
  node_provider_adapters["Providers<br/>model-adapter<br/>[providers.ts]"]
  node_memory_stack[("Memory stack<br/>persistence<br/>[index.ts]")]
  node_skills_registry["Skills<br/>knowledge-pack<br/>[index.ts]"]
  node_tool_registry{{"Tool registry<br/>boundary<br/>[registry.ts]"}}
  node_finance_tools["Finance tools<br/>domain-tools<br/>[index.ts]"]
  node_search_tools["Search tools<br/>research-tools<br/>[index.ts]"]
  node_filesystem_tools["Filesystem tools<br/>io-tools<br/>[index.ts]"]
  node_browser_tools["Browser tools<br/>io-tools<br/>[index.ts]"]
  node_memory_tools["Memory tools<br/>io-tools<br/>[index.ts]"]
  node_heartbeat_tools(("Heartbeat tools<br/>ops-tools<br/>[heartbeat-tool.ts]"))
end

subgraph group_interfaces["Interfaces"]
  node_ui_controller{{"UI controller<br/>[agent-runner.ts]"}}
  node_ui_components["UI components<br/>presentation<br/>[index.ts]"]
  node_gateway_channels["Channels<br/>channel-layer<br/>[index.ts]"]
  node_gateway_routing{{"Route resolver<br/>routing<br/>[resolve-route.ts]"}}
  node_gateway_whatsapp["WhatsApp<br/>channel-impl<br/>[index.ts]"]
end

subgraph group_ops["Operations"]
  node_cron_engine["Cron engine<br/>scheduler<br/>[executor.ts]"]
  node_heartbeat_suppression(("Heartbeat guard<br/>safety<br/>[suppression.ts]"))
  node_eval_ui["Eval UI<br/>reporting<br/>[eval-app.ts]"]
end

node_src_cli -->|"starts"| node_ui_controller
node_src_index -->|"starts"| node_ui_controller
node_ui_controller -->|"renders"| node_ui_components
node_ui_controller -->|"runs"| node_agent_runtime
node_src_gateway -->|"uses"| node_gateway_channels
node_src_gateway -->|"routes"| node_gateway_routing
node_gateway_routing -->|"dispatches"| node_agent_runtime
node_gateway_channels -->|"implements"| node_gateway_whatsapp
node_gateway_whatsapp -->|"ingests"| node_gateway_routing
node_gateway_whatsapp -->|"guards"| node_heartbeat_suppression
node_src_cron_runner -->|"schedules"| node_cron_engine
node_cron_engine -->|"triggers"| node_agent_runtime
node_src_evals_run -->|"reports"| node_eval_ui
node_src_evals_run -->|"benchmarks"| node_agent_runtime
node_agent_runtime -->|"builds"| node_agent_prompts
node_agent_runtime -->|"tracks"| node_agent_run_context
node_agent_runtime -->|"executes"| node_agent_tool_executor
node_agent_runtime -->|"logs"| node_agent_scratchpad
node_agent_runtime -->|"compresses"| node_agent_compaction
node_agent_runtime -->|"measures"| node_agent_token_counter
node_agent_runtime -->|"queries"| node_llm_boundary
node_llm_boundary -->|"adapts"| node_provider_adapters
node_agent_runtime -->|"selects"| node_tool_registry
node_tool_registry -->|"includes"| node_finance_tools
node_tool_registry -->|"includes"| node_search_tools
node_tool_registry -->|"includes"| node_filesystem_tools
node_tool_registry -->|"includes"| node_browser_tools
node_tool_registry -->|"includes"| node_memory_tools
node_tool_registry -->|"includes"| node_heartbeat_tools
node_agent_runtime -->|"retrieves"| node_memory_stack
node_agent_runtime -->|"loads"| node_skills_registry

click node_src_cli "https://github.com/virattt/dexter/blob/main/src/cli.ts"
click node_src_index "https://github.com/virattt/dexter/blob/main/src/index.tsx"
click node_src_gateway "https://github.com/virattt/dexter/blob/main/src/gateway/gateway.ts"
click node_src_cron_runner "https://github.com/virattt/dexter/blob/main/src/cron/runner.ts"
click node_src_evals_run "https://github.com/virattt/dexter/blob/main/src/evals/run.ts"
click node_agent_runtime "https://github.com/virattt/dexter/blob/main/src/agent/agent.ts"
click node_agent_prompts "https://github.com/virattt/dexter/blob/main/src/agent/prompts.ts"
click node_agent_run_context "https://github.com/virattt/dexter/blob/main/src/agent/run-context.ts"
click node_agent_tool_executor "https://github.com/virattt/dexter/blob/main/src/agent/tool-executor.ts"
click node_agent_scratchpad "https://github.com/virattt/dexter/blob/main/src/agent/scratchpad.ts"
click node_agent_compaction "https://github.com/virattt/dexter/blob/main/src/agent/compact.ts"
click node_agent_token_counter "https://github.com/virattt/dexter/blob/main/src/agent/token-counter.ts"
click node_llm_boundary "https://github.com/virattt/dexter/blob/main/src/model/llm.ts"
click node_provider_adapters "https://github.com/virattt/dexter/blob/main/src/providers.ts"
click node_memory_stack "https://github.com/virattt/dexter/blob/main/src/memory/index.ts"
click node_skills_registry "https://github.com/virattt/dexter/blob/main/src/skills/index.ts"
click node_tool_registry "https://github.com/virattt/dexter/blob/main/src/tools/registry.ts"
click node_finance_tools "https://github.com/virattt/dexter/blob/main/src/tools/finance/index.ts"
click node_search_tools "https://github.com/virattt/dexter/blob/main/src/tools/search/index.ts"
click node_filesystem_tools "https://github.com/virattt/dexter/blob/main/src/tools/filesystem/index.ts"
click node_browser_tools "https://github.com/virattt/dexter/blob/main/src/tools/browser/index.ts"
click node_memory_tools "https://github.com/virattt/dexter/blob/main/src/tools/memory/index.ts"
click node_heartbeat_tools "https://github.com/virattt/dexter/blob/main/src/tools/heartbeat/heartbeat-tool.ts"
click node_ui_controller "https://github.com/virattt/dexter/blob/main/src/controllers/agent-runner.ts"
click node_ui_components "https://github.com/virattt/dexter/blob/main/src/components/index.ts"
click node_gateway_channels "https://github.com/virattt/dexter/blob/main/src/gateway/channels/index.ts"
click node_gateway_routing "https://github.com/virattt/dexter/blob/main/src/gateway/routing/resolve-route.ts"
click node_gateway_whatsapp "https://github.com/virattt/dexter/blob/main/src/gateway/channels/whatsapp/index.ts"
click node_cron_engine "https://github.com/virattt/dexter/blob/main/src/cron/executor.ts"
click node_heartbeat_suppression "https://github.com/virattt/dexter/blob/main/src/gateway/heartbeat/suppression.ts"
click node_eval_ui "https://github.com/virattt/dexter/blob/main/src/evals/components/eval-app.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_cli,node_src_index,node_src_gateway,node_src_cron_runner,node_src_evals_run toneBlue
class node_agent_runtime,node_agent_prompts,node_agent_run_context,node_agent_tool_executor,node_agent_scratchpad,node_agent_compaction,node_agent_token_counter toneAmber
class node_llm_boundary,node_provider_adapters,node_memory_stack,node_skills_registry,node_tool_registry,node_finance_tools,node_search_tools,node_filesystem_tools,node_browser_tools,node_memory_tools,node_heartbeat_tools toneMint
class node_ui_controller,node_ui_components,node_gateway_channels,node_gateway_routing,node_gateway_whatsapp toneRose
class node_cron_engine,node_heartbeat_suppression,node_eval_ui toneIndigo
```

## Components

### Entry surfaces

User-facing and scheduled entry points into the shared agent runtime.

- [CLI](https://github.com/virattt/dexter/blob/main/src/cli.ts): entrypoint · Local command-line entry into the agent experience. · `src/cli.ts`
- [TUI app](https://github.com/virattt/dexter/blob/main/src/index.tsx): entrypoint · Interactive terminal UI and app bootstrap. · `src/index.tsx`
- [Gateway](https://github.com/virattt/dexter/blob/main/src/gateway/gateway.ts): entrypoint · Message-driven service entry point. · `src/gateway/gateway.ts`
- [Cron runner](https://github.com/virattt/dexter/blob/main/src/cron/runner.ts): entrypoint · Scheduled background execution entry point. · `src/cron/runner.ts`
- [Eval runner](https://github.com/virattt/dexter/blob/main/src/evals/run.ts): entrypoint · Benchmark execution entry point. · `src/evals/run.ts`

### Agent core

Planning, prompting, execution control, and run-state management.

- [Agent runtime](https://github.com/virattt/dexter/blob/main/src/agent/agent.ts): orchestrator · Central reasoning loop coordinating planning, tools, and responses. · `src/agent/agent.ts`
- [Prompts](https://github.com/virattt/dexter/blob/main/src/agent/prompts.ts): prompting · System and task prompt construction for the agent loop. · `src/agent/prompts.ts`
- [Run context](https://github.com/virattt/dexter/blob/main/src/agent/run-context.ts): state · Per-run state, lifecycle, and execution metadata. · `src/agent/run-context.ts`
- [Tool executor](https://github.com/virattt/dexter/blob/main/src/agent/tool-executor.ts): executor · Dispatches tool calls and mediates side effects. · `src/agent/tool-executor.ts`
- [Scratchpad](https://github.com/virattt/dexter/blob/main/src/agent/scratchpad.ts): trace · Run notes and intermediate reasoning trace storage. · `src/agent/scratchpad.ts`
- [Context compacting](https://github.com/virattt/dexter/blob/main/src/agent/compact.ts): memory-control · Compacting and micro-compacting of long running context. · `src/agent/compact.ts`
- [Token counter](https://github.com/virattt/dexter/blob/main/src/agent/token-counter.ts): telemetry · Token accounting for prompts and tool outputs. · `src/agent/token-counter.ts`

### Integrations

External model, data, search, browser, filesystem, and memory boundaries.

- [LLM boundary](https://github.com/virattt/dexter/blob/main/src/model/llm.ts): model-adapter · Provider abstraction and model capability selection. · `src/model/llm.ts`
- [Providers](https://github.com/virattt/dexter/blob/main/src/providers.ts): model-adapter · Backend-specific adapters for model runtime differences. · `src/providers.ts`
- [Memory stack](https://github.com/virattt/dexter/blob/main/src/memory/index.ts): persistence · Embeddings, indexing, search, and durable retrieval across sessions. · `src/memory/index.ts`
- [Skills](https://github.com/virattt/dexter/blob/main/src/skills/index.ts): knowledge-pack · Curated domain playbooks such as DCF and X research. · `src/skills/index.ts`
- [Tool registry](https://github.com/virattt/dexter/blob/main/src/tools/registry.ts): boundary · Central tool catalog and registration layer. · `src/tools/registry.ts`
- [Finance tools](https://github.com/virattt/dexter/blob/main/src/tools/finance/index.ts): domain-tools · Market data, filings, estimates, news, screening, and crypto helpers. · `src/tools/finance/index.ts`
- [Search tools](https://github.com/virattt/dexter/blob/main/src/tools/search/index.ts): research-tools · External web and research search providers. · `src/tools/search/index.ts`
- [Filesystem tools](https://github.com/virattt/dexter/blob/main/src/tools/filesystem/index.ts): io-tools · Sandboxed file read and write operations. · `src/tools/filesystem/index.ts`
- [Browser tools](https://github.com/virattt/dexter/blob/main/src/tools/browser/index.ts): io-tools · Browser-backed navigation and retrieval utilities. · `src/tools/browser/index.ts`
- [Memory tools](https://github.com/virattt/dexter/blob/main/src/tools/memory/index.ts): io-tools · Agent-accessible retrieval and update operations for durable memory. · `src/tools/memory/index.ts`
- [Heartbeat tools](https://github.com/virattt/dexter/blob/main/src/tools/heartbeat/heartbeat-tool.ts): ops-tools · Liveness and heartbeat signaling used by automation surfaces. · `src/tools/heartbeat/heartbeat-tool.ts`

### Interfaces

Interactive UI and message gateway layers that drive the agent.

- [UI controller](https://github.com/virattt/dexter/blob/main/src/controllers/agent-runner.ts): controller · Coordinates input history, model selection, and agent-run lifecycle. · `src/controllers/agent-runner.ts`
- [UI components](https://github.com/virattt/dexter/blob/main/src/components/index.ts): presentation · Chat, approvals, tool events, status, and debug rendering. · `src/components/index.ts`
- [Channels](https://github.com/virattt/dexter/blob/main/src/gateway/channels/index.ts): channel-layer · Channel abstraction for WhatsApp and other message surfaces. · `src/gateway/channels/index.ts`
- [Route resolver](https://github.com/virattt/dexter/blob/main/src/gateway/routing/resolve-route.ts): routing · Message routing, access control, sessions, and deduplication flow. · `src/gateway/routing/resolve-route.ts`
- [WhatsApp](https://github.com/virattt/dexter/blob/main/src/gateway/channels/whatsapp/index.ts): channel-impl · WhatsApp-specific inbound, outbound, login, session, and reconnect flow. · `src/gateway/channels/whatsapp/index.ts`

### Operations

Evaluation, cron automation, and reliability-related workflows.

- [Cron engine](https://github.com/virattt/dexter/blob/main/src/cron/executor.ts): scheduler · Scheduled job execution and store management. · `src/cron/executor.ts`
- [Heartbeat guard](https://github.com/virattt/dexter/blob/main/src/gateway/heartbeat/suppression.ts): safety · Suppresses or controls heartbeat-driven activity. · `src/gateway/heartbeat/suppression.ts`
- [Eval UI](https://github.com/virattt/dexter/blob/main/src/evals/components/eval-app.ts): reporting · Evaluation progress, stats, and recent-result presentation. · `src/evals/components/eval-app.ts`

## Connections

- CLI → UI controller: starts · CLI delegates runs into the shared agent controller.
- TUI app → UI controller: starts · Interactive TUI routes requests through the same controller.
- UI controller → UI components: renders · Controller streams state into presentation components.
- UI controller → Agent runtime: runs · Controller invokes the shared agent loop for each turn.
- Gateway → Channels: uses · Gateway boots the channel abstraction.
- Gateway → Route resolver: routes · Gateway normalizes inbound messages and resolves execution routes.
- Route resolver → Agent runtime: dispatches · Routed messages are handed to the shared agent runner.
- Channels → WhatsApp: implements · WhatsApp is the concrete channel implementation.
- WhatsApp → Route resolver: ingests · WhatsApp inbound messages enter through routing and dedupe.
- WhatsApp → Heartbeat guard: guards · Channel flow cooperates with heartbeat suppression controls.
- Cron runner → Cron engine: schedules · Cron entry point executes the scheduler engine.
- Cron engine → Agent runtime: triggers · Scheduled jobs can invoke the shared agent loop.
- Eval runner → Eval UI: reports · Eval runs surface progress and results through eval components.
- Eval runner → Agent runtime: benchmarks · Evaluation harness executes the same agent core.
- Agent runtime → Prompts: builds · The core loop constructs prompts before model calls.
- Agent runtime → Run context: tracks · Run state is maintained across steps and tool calls.
- Agent runtime → Tool executor: executes · The agent delegates all external actions to the tool executor.
- Agent runtime → Scratchpad: logs · Intermediate notes and traces are written to scratchpad.
- Agent runtime → Context compacting: compresses · Long contexts are compacted during extended runs.
- Agent runtime → Token counter: measures · Token usage is tracked for prompt and output budgeting.
- Agent runtime → LLM boundary: queries · The core loop requests model capabilities and responses.
- LLM boundary → Providers: adapts · Provider code handles backend-specific model behavior.
- Agent runtime → Tool registry: selects · Tool execution is mediated through the registry layer.
- Tool registry → Finance tools: includes · Finance tools are the main domain integration.
- Tool registry → Search tools: includes · Research search providers are exposed as tools.
- Tool registry → Filesystem tools: includes · Filesystem access is wrapped as tools.
- Tool registry → Browser tools: includes · Browser-based retrieval is available through tools.
- Tool registry → Memory tools: includes · Memory retrieval and updates are tool-mediated.
- Tool registry → Heartbeat tools: includes · Heartbeat signaling is exposed through the tool layer.
- Agent runtime → Memory stack: retrieves · Long-term memory is consulted separately from scratchpad state.
- Agent runtime → Skills: loads · Curated skills are available as reusable knowledge modules.
