Twitter Personality: An Open-Source X Profile Analyser Built on Next.js 15 and Vercel AI Gateway

What Twitter Personality Does and Its History

Twitter Personality takes an X (formerly Twitter) username, fetches the user's profile and roughly 15 recent posts via the official X API v2, sends that data to an LLM with a fixed prompt, and streams a structured analysis back to the browser. The output includes a roast, an assessment of strengths, a love life reading, a spirit animal, and pickup lines.

The README states that the original version of this application went viral in 2024. The repository is a relaunched version: it replaced the original Wordware-hosted prompt infrastructure with the Vercel AI SDK and Vercel AI Gateway, updated the frontend to Next.js 15, and rebranded to Sauna. All previously generated analyses are cached in the Neon Postgres database and continue to render.

The prompts themselves, which live in src/lib/prompts.ts, are described as the original viral prompts ported from the Wordware platform.

Architecture: X API, AI Gateway, and Neon Postgres

The data flow has three stages. First, the application fetches the target user's profile and recent posts. The primary source is the official X API v2, accessed with a bearer token obtained from the X developer console. A SocialData API key provides a fallback scraper if the X API is unavailable.

Second, the fetched data is passed to an LLM via the Vercel AI Gateway. The default model is xai/grok-4.20-non-reasoning, configured via the AI_MODEL environment variable. The README states that swapping models is a matter of changing that one variable to any string the Vercel AI Gateway supports: it lists xai/grok-4.20-non-reasoning, zai/glm-5.2, and openai/gpt-5.2 as examples, and points to vercel.com/ai-gateway/models for the full list. The application is not tied to a specific provider.

Third, the generated analysis is stored in Neon Postgres. The users and pairs tables carry status flags that deduplicate concurrent generation requests and prevent the same analysis from being run twice within a staleness window. The schema uses JSONB columns to store the analysis output, and the README notes that the column keys should not be changed casually because they match the cached data key-for-key.

Setting Up the Application Locally

The setup requires Node.js, a Neon Postgres database, a Vercel AI Gateway key, and an X API bearer token. The README walks through the process:

npm install
npm run dev

Environment variables go in a .env.local file based on the .env.example template. The minimum set for a working local instance is:

- DATABASE_URL: the Neon Postgres connection string - AI_GATEWAY_API_KEY: a Vercel AI Gateway key (automatic on Vercel deployments via OIDC) - X_API_BEARER_TOKEN: the official X API v2 bearer token - NEXT_PUBLIC_BASE_URL: the base URL used to generate share links

The X API bearer token is described as pay-per-use in the README. The official X developer console at developer.x.com is where credits are purchased. The SocialData fallback requires its own API key but is listed as optional.

PostHog analytics keys and Stripe paywall configuration are also present in the .env.example, but both are optional: the README notes that the paywall is off by default via a toggle in src/lib/config.tsx.

Prompt Engineering and Streaming Output

The prompts that generate the personality profile live in src/lib/prompts.ts. The README explains a deliberate design choice: structured-output mode (constrained decoding) is avoided because it flattens the voice of the output. Instead, the prompts enumerate the expected output keys in free-form instructions, and the LLM produces JSON text that is streamed and parsed incrementally.

The client-side JSON parser at src/lib/parse-partial-json.ts renders the analysis as it arrives, section by section, before the full response is complete. That is what produces the streaming effect on the page.

The shapes of the output fields are documented in src/lib/schemas.ts. These schemas mirror the JSONB column structure in the database, which is why changing a key in the schema would invalidate cached analyses.

Limitations and What the Repository Does Not Cover

The X API v2 bearer token is the primary data source, and the README describes it as pay-per-use. Running the application at any volume incurs X API costs that are separate from Vercel and Neon charges. The free tier of the X API has strict rate limits, and the application does not expose rate limit handling in the README.

The repository carries no licence file. The README notes the project is private (package.json has "private": true), and there is no LICENCE or LICENSE file in the top-level entry list. Without an explicit open-source licence, the default copyright applies, which means forking and redistributing the code requires permission from the maintainers.

The compatibility check mode (two usernames) has the same architecture as the single-user analysis, with a separate API endpoint at /api/analysis/pair, but the README does not describe any differences in the prompt or output structure for that mode beyond noting it exists.

Comparison with Direct Vercel AI SDK Usage

An engineer who wants to build a similar X personality tool from scratch using the Vercel AI SDK would face two main tasks not covered by the SDK itself: crafting the prompts that produce the specific personality dimensions (roast, strengths, love life, spirit animal), and building the partial JSON streaming parser.

Twitter Personality provides both. The src/lib/prompts.ts file is the accumulated result of the original viral version's prompt iteration. An engineer using the SDK directly would start from scratch on both. The trade-off is that the existing prompts are tuned for a specific type of output (creative and often irreverent) rather than neutral personality assessment.

Maintenance Status

The last push to the repository was on 2026-08-02. The project is not archived and has no GitHub releases. The README describes it as deployed on Vercel, and the live site is at twitter.wordware.ai.

Editorial conclusion

Twitter Personality suits engineers who want a reference implementation of streaming structured LLM output with a swappable model backend and a Neon Postgres caching layer. The prompts are the direct descendants of the original viral Wordware version and produce creative, opinionated output rather than sober analysis. It is not suited for production use without reviewing X API costs (the official bearer token is pay-per-use), confirming the paywall toggle in src/lib/config.tsx, and reading the licence terms: the repository carries no licence file, which means the default copyright applies and redistribution is restricted until the maintainers publish explicit terms.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. wordware-ai/twitter on GitHub