dotiphant

Docs

Install Dotiphant

On macOS or Linux, paste curl -fsSL https://dotiphant.com/install.sh | sh into a terminal. It installs the latest Dotiphant release and opens the setup in your browser, which takes about five minutes. Windows support is experimental.

Quick start

curl -fsSL https://dotiphant.com/install.sh | sh

The script is about 150 lines; read it first. It installs uv if needed (uv brings its own Python), installs the latest Dotiphant release from GitHub with uv, and runs dotiphant open. Before installing, it checks the download against the release's SHA-256 checksums and stops on a mismatch. To update, run the same command again.

You can also check signed build provenance with gh attestation verify; see Verify a download.

Other ways to install

Dotiphant ships as GitHub releases, not on PyPI. If you already have uv:

GoalCommand
Install a releaseuv tool install <URL of the .whl file on the release page>, then dotiphant open
From a local cloneuv tool install .

To install by hand and check the file yourself: download the .whl file and SHA256SUMS from the release page into one folder, check it, then install the file:

shasum -a 256 -c --ignore-missing SHA256SUMS  # Linux: sha256sumuv tool install ./dotiphant-X.Y.Z-py3-none-any.whl

The command is dotiphant; phant is a short alias. If the command is not found after installing, run uv tool update-shell and open a new shell.

Setup

dotiphant open walks you through setup in your browser. It takes about 5 minutes. Prefer the terminal? dotiphant setup asks the same questions there. Both are safe to run again.

  1. Create your own Telegram API id and hash at my.telegram.org (free, about a minute). Telegram requires every app to have one. Click "API development tools", fill in the form (app title and short name can be anything, platform Desktop) and copy "App api_id" and "App api_hash" into the setup page.
  2. Log in by scanning a QR code with the Telegram app (Settings > Devices > Link Desktop Device). Phone login works too. If your account has a two-step verification password, the page asks for it.
  3. Choose what to archive: people and groups by default, the last 365 days or everything.
  4. Run the first sync. It takes from a minute to an hour for large accounts, and you can continue while it runs.
  5. Connect the AI apps it finds on your computer, and turn on background refresh.

Afterwards:

dotiphant open  # browse and search in your browserdotiphant connect claude-desktop  # or claude-code, codex, cursor

Fully quit and restart the AI app after connecting it. Run dotiphant status to check the login, archive size and last sync, and dotiphant doctor if anything looks wrong.

Try it without Telegram

dotiphant demo

This opens the viewer on a made-up archive, stored separately from your real data. No login needed. It uses port 8764, so it can run next to dotiphant open.

Install with an AI assistant

Not comfortable with a terminal? An AI assistant that can run commands on your computer (Claude Code, Codex, Cursor, or Claude Desktop with a terminal tool) can install Dotiphant with you. Copy this prompt into it:

Please install Dotiphant for me, following the instructions at
https://github.com/Zierold-Ventures/dotiphant/blob/main/docs/install-with-ai.md
Explain each step in plain words before you run it, and tell me exactly
what to do whenever you need something from me.

You will need your phone with Telegram on it. You type your API id, hash and any codes into the setup page in your browser yourself, never into the AI chat.

Commands

CommandWhat it does
dotiphant openOpen the viewer at http://127.0.0.1:8765, with setup on first run. dotiphant serve does the same
dotiphant setupThe same guided setup in the terminal. Safe to re-run; finished steps are skipped
dotiphant sync [CHAT ...]Fetch new messages now, for all chats or the ones named
dotiphant statusLogin, archive size, last sync, background refresh
dotiphant doctorCheck the installation and print fixes
dotiphant connect [APP]Connect an AI app to your archive, or list the apps it can connect
dotiphant chatsList archived chats
dotiphant search QUERYFull-text search, with --chat, --since, --json
dotiphant export CHATPrint a chat as Markdown, --since 7d, --out FILE
dotiphant recentWhat happened in the last 24 hours
dotiphant media CHATDownload photos, files and voice notes of a chat
dotiphant schedule installRefresh in the background every N minutes
dotiphant mcpThe MCP server (AI apps start this themselves)
dotiphant mcp --http --public-url URLRemote access for ChatGPT, claude.ai and other remote MCP apps
dotiphant import PATHAdd a Telegram Desktop JSON export (result.json), or a chat from WhatsApp's own "Export chat" (.zip or .txt), to the archive. Experimental. Nothing connects to WhatsApp
dotiphant forget CHATDelete a chat and its media from the archive, and stop syncing it
dotiphant demoTry the viewer with made-up chats
dotiphant login / dotiphant logoutLog in again, or end the session

CHAT can be a chat id, an @username or part of the title. Run dotiphant COMMAND --help for all options. Remote access is explained in Remote access.

dotiphant export "Acme" --since 7d | claude -p "What are the open action items?"

Update and uninstall

To update, run the install command again. To remove Dotiphant and everything it stored, follow Wiping everything: stop the background refresh, log out with --forget-credentials, delete the data folder, and run uv tool uninstall dotiphant.

Install Dotiphant

Free and open source (MIT). macOS and Linux; Windows experimental. The command installs the latest GitHub release and opens the setup in your browser. It takes about five minutes.

The script is about 150 lines. Read it first, or see other ways to install. The installer verifies the download against the release checksums (SHA256SUMS) before installing. You can check signed build provenance with gh attestation verify; see Verify a download.

curl -fsSL https://dotiphant.com/install.sh | shdotiphant open  # setup opens in your browser

Updated . Something wrong or unclear? Open an issue.