How virattt/dexter works
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: agent.ts Agent runtime · registry.ts Tool registry · agent-runner.ts UI controller · index.ts WhatsApp
Components 31
Entry surfaces
User-facing and scheduled entry points into the shared agent runtime.
- CLI · Local command-line entry into the agent experience.
src/cli.ts - TUI app · Interactive terminal UI and app bootstrap.
src/index.tsx - Gateway · Message-driven service entry point.
src/gateway/gateway.ts - Cron runner · Scheduled background execution entry point.
src/cron/runner.ts - Eval runner · Benchmark execution entry point.
src/evals/run.ts
Agent core
Planning, prompting, execution control, and run-state management.
- Agent runtime · Central reasoning loop coordinating planning, tools, and responses.
src/agent/agent.ts - Prompts · System and task prompt construction for the agent loop.
src/agent/prompts.ts - Run context · Per-run state, lifecycle, and execution metadata.
src/agent/run-context.ts - Tool executor · Dispatches tool calls and mediates side effects.
src/agent/tool-executor.ts - Scratchpad · Run notes and intermediate reasoning trace storage.
src/agent/scratchpad.ts - Context compacting · Compacting and micro-compacting of long running context.
src/agent/compact.ts - Token counter · Token accounting for prompts and tool outputs.
src/agent/token-counter.ts
Integrations
External model, data, search, browser, filesystem, and memory boundaries.
- LLM boundary · Provider abstraction and model capability selection.
src/model/llm.ts - Providers · Backend-specific adapters for model runtime differences.
src/providers.ts - Memory stack · Embeddings, indexing, search, and durable retrieval across sessions.
src/memory/index.ts - Skills · Curated domain playbooks such as DCF and X research.
src/skills/index.ts - Tool registry · Central tool catalog and registration layer.
src/tools/registry.ts - Finance tools · Market data, filings, estimates, news, screening, and crypto helpers.
src/tools/finance/index.ts - Search tools · External web and research search providers.
src/tools/search/index.ts - Filesystem tools · Sandboxed file read and write operations.
src/tools/filesystem/index.ts - Browser tools · Browser-backed navigation and retrieval utilities.
src/tools/browser/index.ts - Memory tools · Agent-accessible retrieval and update operations for durable memory.
src/tools/memory/index.ts - Heartbeat 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 · Coordinates input history, model selection, and agent-run lifecycle.
src/controllers/agent-runner.ts - UI components · Chat, approvals, tool events, status, and debug rendering.
src/components/index.ts - Channels · Channel abstraction for WhatsApp and other message surfaces.
src/gateway/channels/index.ts - Route resolver · Message routing, access control, sessions, and deduplication flow.
src/gateway/routing/resolve-route.ts - WhatsApp · 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 · Scheduled job execution and store management.
src/cron/executor.ts - Heartbeat guard · Suppresses or controls heartbeat-driven activity.
src/gateway/heartbeat/suppression.ts - Eval UI · Evaluation progress, stats, and recent-result presentation.
src/evals/components/eval-app.ts
Connections 31
- 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.