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 versionPreviously 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:
| Platform | Download |
|---|---|
| macOS · Apple Silicon | darwin-arm64 |
| macOS · Intel | darwin-amd64 |
| Linux · x86-64 | linux-amd64 |
| Linux · ARM64 | linux-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 versionAdd 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_hashThese 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 --qrOn 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 fxReplace @example_channel with a public channel or group you want to read:
indexit -q telegram fetch messages \
--dialog @example_channel --limit 200 | fxYou 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 | fxListing 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-codeUse --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:
| Step | By hand | Ask your agent |
|---|---|---|
| Install | brew install --formula octolab/tap/indexit | “Set up indexit.” With the setup instruction above, it installs indexit for your system and checks indexit version. |
| Credentials | Write 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 in | indexit 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 messages | indexit -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 chat | indexit -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?
- Describe a channel and find its discussion group.
- Read a date range or specific messages.
- Save photos from a forum topic.
- Filter the stream with jq.
- Use a proxy when a direct connection is unavailable.
- Teach your coding agent indexit with the skill that ships with it.