murmur is a local-first TypeScript/Node CLI for analyzing public X/Twitter profiles from user-supplied exports.

The MVP imports Apify-style JSON/CSV exports or collects public timelines through the X API, cleans tweets, computes deterministic style and engagement features, and writes JSON/Markdown reports. LLM analysis is provider-based; Kimi and X API credentials are configured through the setup wizard.

git clone <repo-url> murmur
cd murmur
corepack enable
pnpm install
pnpm build

For day-to-day local use, run the CLI through the package script:

pnpm murmur --help

Optional global install from this checkout:

pnpm link --global
murmur --help

Run:

pnpm murmur setup

The wizard asks for the data directory, official X API Bearer Token, optional twitterapi.io API key, and optional Kimi settings. It writes ~/.config/murmur/config.json with private 0600 permissions. Environment variables still override config for CI and scripts.

To get the X Bearer Token, create an app in the X Developer Console, open Keys and Tokens, and copy the app-only Bearer Token. murmur only uses this for read-only public profile data.

Paste this into an AI coding assistant that has terminal access to your machine:

Set up the local murmur repo for me. Work from the repository root. Install dependencies with pnpm, build the TypeScript project, run the tests, then run `pnpm murmur setup` and walk me through each prompt. Explain that the X API credential needed is the app-only Bearer Token from console.x.com > app > Keys and Tokens, and that murmur only reads public profile data. After setup, verify with `pnpm murmur --help` and show me example commands for `--source x` and Apify imports. Do not ask me to paste secrets into chat; let the setup wizard collect them in the terminal.

An Agent Skills-compatible murmur skill is bundled at skills/codex/murmur. It has standard SKILL.md frontmatter and works as a global skill for Claude Code, Codex, and other Agent Skills clients that load skill folders.

Interactive install:

pnpm murmur skills install

Noninteractive install for both Claude and Codex:

pnpm murmur skills install --agents claude,codex --yes --force

This installs copies to:

~/.claude/skills/murmur
~/.codex/skills/murmur

Manual install is also fine:

mkdir -p ~/.codex/skills
ln -s "$(pwd)/skills/codex/murmur" ~/.codex/skills/murmur

For Claude Code, the equivalent manual path is ~/.claude/skills/murmur. The skill is intentionally a thin wrapper around the CLI. Agents should call pnpm murmur ... instead of reimplementing analysis logic.

pnpm murmur collect @handle --source apify --input path/to/export.json --limit 1000
pnpm murmur collect @handle --source x --limit 100
pnpm murmur collect @handle --source twitterapi --limit 100
pnpm murmur setup
pnpm murmur skills install --agents claude,codex --yes
pnpm murmur prepare @handle
pnpm murmur analyze @handle --model kimi-k2.6-turbo
pnpm murmur run @handle --source apify --input path/to/export.json --limit 1000
pnpm murmur run @handle --source x --limit 100
pnpm murmur run @handle --source twitterapi --limit 100
pnpm murmur compare @handle1 @handle2 @handle3
pnpm murmur report @handle --format markdown
pnpm murmur export @handle --format json

--source x uses app-only Bearer authentication for read-only public profile data. Run pnpm murmur setup and paste the Bearer Token from console.x.com; no cookies, private/protected-profile access, or user-context OAuth flow is used.

--source twitterapi uses the third-party twitterapi.io API with an X-API-Key header. The adapter accepts both the documented tweets response shape and the live data.tweets response shape.

data/
  raw/<handle>/tweets.jsonl
  clean/<handle>/tweets.jsonl
  clean/<handle>/tweets.parquet
  reports/<handle>/features.json
  reports/<handle>/analysis.json
  reports/<handle>/report.md

Use pnpm murmur setup to change the default data directory. Set MURMUR_DATA_DIR only when you need a one-off override.

pnpm test