Skip to Content
Quick start

Your first useful result

Let your coding agent set up indexit and help you explore a Telegram conversation. You’ll need an existing Telegram account and your own API credentials.

Start with your agent

Copy this instruction into an agent that can read the web and run commands on your computer:

GIVE THIS TO YOUR AGENT

Read https://indexit.octolab.org/quick-start.md and help me set up indexit, connect my Telegram account, and explore a conversation I choose. Guide me through any steps I need to do myself.

Your agent handles installation, checks the setup, and offers to add the indexit skill, so you can keep working through it. You create your Telegram API credentials, enter them locally, and confirm the login on your phone.

Prefer to run the commands yourself? Follow the steps below.

1. Install indexit

On macOS, install the stable release with Homebrew :

brew install --formula octolab/tap/indexit indexit version

Previously installed the Cask? Follow the one-time Formula migration first.

For Linux or a manual installation, use a ready-to-run archive below. Go is not required.

Linux & manual installation

Download the v0.4.1 archive for your machine:

PlatformDownload
macOS · Apple Silicondarwin-arm64 
macOS · Inteldarwin-amd64 
Linux · x86-64linux-amd64 
Linux · ARM64linux-arm64 

In the directory containing your download, extract the archive and install the binary. This example uses Linux x86-64; substitute your archive’s filename:

tar -xzf indexit_0.4.1_linux-amd64.tar.gz mkdir -p "$HOME/.local/bin" install -m 755 indexit "$HOME/.local/bin/indexit" export PATH="$HOME/.local/bin:$PATH" indexit version

Add the export PATH line to your shell configuration to keep indexit available in new terminals. All archives and checksums are on the v0.4.1 release page .

install is a standard macOS/Linux command that copies a file and sets its permissions. Here, -m 755 makes the copied binary executable; it is not a package manager. The destination is your own ~/.local/bin, so this step does not need sudo.

2. Add your Telegram credentials

Create an application at my.telegram.org/apps  and copy its api_id and api_hash. See Telegram’s application setup  if you need a hand.

Create a .env in the directory where you run indexit:

TELEGRAM_API_ID=123456 TELEGRAM_API_HASH=replace_with_your_api_hash

These are placeholders. Use your own values and keep the file private. No GitHub token is needed for Telegram.

3. Sign in with a QR code

indexit telegram auth login --qr

On your phone, open Telegram → Settings → Devices → Link Desktop Device and scan the terminal QR. If your account has a 2FA password, enter it when prompted. The session is saved for future runs.

4. Open your messages in fx

Install fx , an interactive JSON viewer. On macOS:

brew install fx

Replace @example_channel with a public channel or group you want to read:

indexit -q telegram fetch messages \ --dialog @example_channel --limit 200 | fx

You get an interactive view of the latest 200 messages. Expand a record with the arrow keys. Press / to search its contents, or @ to find a JSON path. Nothing needs to be saved first.

A public link works too: --dialog https://t.me/example_channel. For a private conversation, list your dialogs first and use the returned uid:

indexit -q telegram fetch dialogs | fx

Listing dialogs fills the local peer cache. The -q flag keeps progress logs out of the interactive view; errors are still shown.

Work through your agent

indexit is built to be driven by a coding agent as well as by hand. Every binary carries a skill: instructions that teach Claude Code, Codex, and other agents its commands and pitfalls, written for that release. The setup instruction above offers to install it; to do it yourself:

indexit skill install --agent claude-code

Use --agent codex for Codex. Start a new agent session, then ask for /indexit in Claude Code or $indexit in Codex, or just say what you want. Here is the quick start again, side by side:

StepBy handAsk your agent
Installbrew install --formula octolab/tap/indexit“Set up indexit.” With the setup instruction above, it installs indexit for your system and checks indexit version.
CredentialsWrite TELEGRAM_API_ID and TELEGRAM_API_HASH into .env“Help me add my Telegram API credentials.” It tells you where to get them; you type them into .env yourself.
Sign inindexit telegram auth login --qr“Connect my Telegram account.” It gives you the login command to run in your terminal, then confirms with auth status.
Read messagesindexit -q telegram fetch messages --dialog @example_channel --limit 200 | fx“What has @example_channel posted lately?” It fetches a small batch and answers from the records.
Find a private chatindexit -q telegram fetch dialogs | fx, then the chat’s uid“Find my chat with the climbing club.” It lists your dialogs, matches the titles, and asks which one you meant.

The agent reads the same JSONL that you open in fx, but it doesn’t launch fx or fzf: they need your terminal. It filters records with jq, keeps first runs small, and checks skipped messages and failed downloads before it reports success. Your credentials, session, and sign-in stay with you.

The same goes for everything after the first steps: “Export these three message links”, “Save the photos from this forum topic”, “What is this invite link, and does it have a discussion group?” See what the skill covers →

Try the two workflows

Explore the interactive examples to see both in action:

  • Explore with fx: browse message fields and search their contents.
  • Find with fzf: type part of a conversation’s name and select it.

Search operates on the records fetched for that run. --limit 200 keeps the first look small; increase it when you want a wider window.

Where next?