docs › Getting started

Getting started

Requirements, install, first run and dexterm doctor.

dexterm is a terminal screener for Solana memecoins with a local Claude analyst. It runs on your machine, reads public data with no key and never holds a wallet key. Trading is PAPER by default; any live swap is signed in your own Phantom wallet after you approve it (see paper trading). This page gets you from nothing to the live screener.

Requirements#

Supported platforms#

This table says what each platform has actually been through, not what we expect to work. "Tested" means the typecheck, the full offline test suite and an install smoke (npm pack, npm i -g of that tarball into an empty prefix with a fresh home, then dexterm --version and dexterm doctor) have passed there.

Known gaps on Windows (none of them affect key safety: dexterm never holds a wallet key on any platform):

• Files dexterm keeps private (tokens, the optional RPC key) are written with POSIX mode 0600. Windows ignores that mode, so on Windows they are protected only by your user profile's normal permissions.
• The analyst runs claude without a shell, so it can start Claude Code's native installer build (claude.exe) but not the claude.cmd script an npm install creates. Doctor counts only claude.exe as found, so with an npm install it reports the Claude CLI as missing.
• Voice mode has no Windows speech engine (see voice).
• Opening a token's links and the PnL card's "share to X" do not start a browser on Windows; dexterm shows the URL to open yourself.
• doctor prints its fixes as POSIX shell commands (mkdir -p, chmod); in PowerShell, do the equivalent by hand.
• dexterm kb edit and dexterm skill edit do not open $EDITOR; they print the file to edit instead.

Install#

The repository README's short path is: choose one installer, then start dexterm.

$ npm i -g dexterm-cli
$ brew install dexterm-xyz/dexterm/dexterm
$ dexterm

Do not run both install lines. The first is npm; the second is the one-line Homebrew alternative for macOS.

$ npm i -g dexterm-cli
$ dexterm doctor

The package is named dexterm-cli because npm refuses the name dexterm as too similar to xterm. The command it installs is dexterm. The package ships compiled JavaScript, so it needs no build step. Every GitHub release carries a build-provenance attestation and SHA256SUMS you can verify (see the trust page).

$ # download dexterm-0.1.4-src.tar.gz and SHA256SUMS from the releases page, then:
$ shasum -a 256 -c SHA256SUMS --ignore-missing
$ gh attestation verify dexterm-0.1.4-src.tar.gz --repo dexterm-xyz/dexterm
$ tar -xzf dexterm-0.1.4-src.tar.gz && cd dexterm-0.1.4
$ ./install.sh
$ dexterm doctor

The releases page is github.com/dexterm-xyz/dexterm/releases.

$ brew tap dexterm-xyz/dexterm
$ brew trust dexterm-xyz/dexterm
$ brew install dexterm
$ dexterm doctor

Homebrew 7 and newer load a third-party tap only after you trust it; without brew trust, brew install dexterm stops with "Refusing to load formula … from untrusted tap". Typing the full name, brew install dexterm-xyz/dexterm/dexterm, also works, because naming a formula in full trusts that one formula. The formula installs the same release tarball and runs it with Homebrew's Node. Homebrew no longer ships prebuilt packages for Intel Macs, so on Intel it builds Node and its toolchain from source, which takes a long time; the release installer above is much faster there.

The steps below are the same installer, run from a checkout.

$ cd dexterm/app
$ ./install.sh
$ dexterm doctor
$ dexterm

install.sh is user-level: no sudo, no edits to your shell profile. It checks for Node 22.18+, downloads an official build into your home directory only if none is found (verified against Node's published SHASUMS256.txt), links the app, builds the native chart window when cargo is present, and writes a dexterm launcher to ~/.local/bin. If that directory is not on your PATH it prints the one line to add and does not add it for you.

Already have Node 22.18+? You can skip the installer. dexterm has no third-party runtime dependencies, so it runs straight from the source tree:

$ npm run dexterm
$ node packages/cli/bin/dexterm.mjs doctor

npm install is optional and only pulls the dev tooling (TypeScript, @types/node).

Running the tests#

From a source checkout, npm install and then npm test runs the typecheck and three test lanes, in order (from 0.1.4, not in a release yet):

• parallel: every packages/*/test/*.test.ts file at once, one process each.
• serial (npm run test:serial, packages/*/test/serial/): the tests that drive a real terminal through a pty, run the real binary, or assert a wall-clock bound (the under-a-second quit, the 50 ms filter fuzz). They run one file at a time after the parallel lane, so they never share the CPU with it.
• perf (npm run test:perf, packages/*/test/perf/): the render budget, p95 under 16 ms per frame. It is asserted on the main thread's CPU time every run, and on wall-clock time whenever no other process held the core during the measurement.

A serial or perf test that fails gets one automatic retry, and the retry is never hidden: the run prints the first failure in full and ends with a list of every test that needed it. A test that fails twice fails the run. Set DEXTERM_TEST_NO_RETRY=1 to turn the retry off. The pty tests open a throwaway cache database, never the one in your data directory.

dexterm doctor#

Run dexterm doctor before anything else. It is non-interactive, never touches your keys, and prints one line per check with the exact fix for anything that is not a pass. Exit code 0 means the app will run (warnings are optional); 1 means something must be fixed.

dexterm doctor

  ✓  Node                     v24.20.0 (need 22.18.0+)
  !  Terminal                 not a TTY (output is being piped); the interactive UI needs a real terminal
                              → Run dexterm directly in a terminal window, not through a pipe or a non-interactive shell.
  ✓  Coin images              half-block art (unknown terminal (no TERM)); --no-images turns them off
  ✓  Claude CLI               found on PATH (the analyst runs your local `claude`; log in once with `claude` if the analyst errors)
  ✓  Login with X             not set up (optional) — X posts need your own X app: free Native App + `dexterm x set-client-id` + `dexterm x login`; see docs › Login with X
  ✓  Helius RPC               key configured (~/.dexterm/helius.key) — holders & safety enriched
  !  Network                  DEXTERM_OFFLINE is set; skipped the live source probes (use --fixtures / --replay for offline data)
  !  Chart window             native window not built — C opens the chart in your browser instead
                              → Run `npm run build:shell` in packages/popup (about a minute the first time).
  ✓  Data directory           ~/.local/share/dexterm is writable (cache, watchlist, credit meter)
  ✓  KB + skills              KB 17 bundled · 0 user (0 overridden, 0 new) · skills 4 bundled · 0 user (0 overridden, 0 new) (yours: ~/.dexterm/kb/entries, ~/.dexterm/skills; `dexterm kb|skill list`)
  ✓  Voice out (say)          macOS `say` ready · 177 voices · the default — press the voice key, then cycle the voice
  ✓  Default voice            Eddy (English (UK)) — deep British male (dexterm default) · , changes it
  !  Neural voice (Piper)     a higher-quality neural British voice is available but not set up; `say` is speaking for now
                              → Run `dexterm voice setup` to install it (asks first; a private Python runtime + a ~61 MB checksum-verified model; runs offline after, `dexterm voice uninstall` removes it).
  ✓  Voice in (Apple Speech)  on-device Apple Speech via swiftc (no key, streaming) — the first run asks for Microphone + Speech permission at the Mac

Ready to run (4 warnings above are optional).

The checks, in order: Node · Terminal · Terminal colour · Coin images · Claude CLI · Login with X · Helius RPC · RPC · Network · Data sources · Chart window · Data directory. The data-source line probes DexScreener, Jupiter, GeckoTerminal, RugCheck, GoPlus, Solana RPC, PumpPortal; PumpPortal is a soft dependency (new pairs only).

Updating#

dexterm update asks npm and GitHub for the latest release and prints the exact command for how this copy was installed (npm, Homebrew, the release tarball or a git checkout). It never upgrades anything by itself.

A live, interactive run also checks once a day in the background and shows one quiet toast when a newer version exists. The check is two anonymous GET requests with the same fixed headers for everyone (no version, no OS, no ids). Turn it off with dexterm update --off (and back on with --on), or set DEXTERM_NO_UPDATE_CHECK=1 or NO_UPDATE_NOTIFIER=1. It never runs with --fixtures, --replay, CI or DEXTERM_OFFLINE. The trust page lists the hosts.

First run#

The first launch shows the full glitch boot and then a one-screen welcome card: what dexterm is, the keys that get you around, and the safety stance (non-custodial, your keys never enter dexterm, trading is PAPER by default, not financial advice). Press any key to enter the live screener. Later launches boot in about a second.

• ? on any screen shows every key for that screen.
• q quits. The terminal is always restored, even after a crash or a signal.
• 1–4 switch screens, j/k move, ⏎ opens a token, esc goes back.
• a asks the analyst about what you are looking at. This is the one explicit, paid run; opening a token with ⏎ never starts one.

The screener paints within a second on a cold start: a cached snapshot of the last rows (marked how old it is), or skeleton rows while the first DexScreener list lands. Jupiter fields fill in behind it.

Next#

• Complete beginner guide for a slower, no-jargon first run and recovery from common mistakes.
• Screens tour for what each screen shows.
• Keyboard reference, generated from the app's keymap.
• Configuration for the free RPC key and the files on disk.
• dexterm help <topic> for the app's own how-to on any key or command, offline. The analyst reads the same help.
• Bring your own agent to connect Claude Code, Codex or a custom bot, and the spectator view to watch it work live ("watch the agent cook").
• Troubleshooting when a line in doctor is not green.