explaingit

dcbuild3r/x-circle

★ 6TypeScriptAudience · generalComplexity · 2/5ActiveSetup · moderate

TLDR

Local browser tool that turns your X (Twitter) archive into a private network graph and a Top 200 circle PNG export, with optional avatar fetching and AI tag enrichment.

Mindmap

mindmap
  root((x-circle))
    Inputs
      X archive zip
      tweets js
      direct-messages js
      following js
    Outputs
      Network graph JSON
      Top 200 PNG
      Interactions JSONL
    Use Cases
      Personal circle screenshot
      DM network analysis
      Influence ranking
    Tech Stack
      TypeScript
      Bun
      Vite
      React

Things people build with this

USE CASE 1

Generate a Top 200 X circle PNG from your own archive

USE CASE 2

Rank your closest X contacts by a weighted DM, reply, mention, and retweet score

USE CASE 3

Explore an interactive force graph of your X interactions locally

USE CASE 4

Tag top handles with role labels inferred from public bios

Tech stack

TypeScriptBunViteReact

Getting it running

Difficulty · moderate Time to first run · 30min

App runs in a minute on sample data, but a real graph requires requesting your X archive which can take days to be ready.

In plain English

X Circle is a small local tool that turns your personal X (formerly Twitter) data export into a private network graph of the people you interact with most. The output includes an interactive graph of small avatar nodes and a Top 200 circle screenshot with your profile in the centre, which you can save as a PNG or copy to the clipboard. The project is a standalone extraction of an existing X network feature from a larger Obsidian Portal project. Everything runs in the browser after you generate a single JSON file from your archive. The README walks through the X archive process: open Settings on x.com, go to Your account, choose Download an archive, confirm your password, request the archive, and wait for X to email you when it is ready. After downloading the zip you move it into a stable folder and extract it. Inside you get files like tweets.js, follower.js, following.js, and direct-messages.js. To build the graph you run an import script against the archive's data directory. It writes the JSON file the app reads, plus normalised JSONL tables for interactions, followers, and following, and a readable markdown summary of the top 200 contacts. Each row in the interaction table records counts for direct messages sent and received, mentions, replies, and retweets, along with a combined interaction score. The score weights direct messages most heavily, then replies, then mentions and retweets. The archive does not include profile pictures for everyone, so there is an optional script that fetches public X profile images for the top handles. Environment variables let you cap the number of handles, target specific handles, or set how many concurrent fetches to run. There is also a workflow for using an AI assistant to tag handles with role labels based on their public bios. The README is clear about privacy: imported archive data stays on your machine, and the generated folders should not be committed to Git.

Copy-paste prompts

Prompt 1
Give me a 5-minute install guide for x-circle using bun install and bun run dev
Prompt 2
Walk me through downloading my X archive and running bun run import:archive against the data folder
Prompt 3
Show me how x-circle computes the interaction_score from DMs, replies, mentions, and retweets
Prompt 4
How do I fetch profile avatars for the top 200 handles with X_AVATAR_LIMIT and X_AVATAR_CONCURRENCY env vars
Prompt 5
Explain the XNetwork data model in src/types.ts and how nodes and edges are derived from the interaction table
Open on GitHub → Explain another repo

Generated 2026-05-22 · Model: sonnet-4-6 · Verify against the repo before relying on details.