{"id":"f799b3bd-4743-46e3-9f0d-f72e744c052c","slug":"timelinexray","kind":"mcp","name":"timelinexray","summary":"Unofficial evidence-first CLI + read-only MCP server for X's open-source algorithm (xai-org/x-algorithm): commit-pinned SHA-256 spans, code index, findings that go STALE.","owner":"solisolsoli","repoUrl":"https://github.com/solisolsoli/timelinexray","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-10-02T18:01:32.000Z","addedAt":"2026-10-21T05:16:08.214Z","logoUrl":"https://avatars.githubusercontent.com/u/316363284?u=373d81254d5771dafa5b54d2beb1585689d9fa84&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","cloud-infra","databases"],"tags":["ai-agents","claude-code","cli","code-search","git","provenance","python","recommendation-system"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T06:57:21.049Z","sample":false,"url":"https://conduits.dev/tools/timelinexray","language":"Python","transports":["stdio"],"install":{"pypi":"timelinexray"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"\n\n# TimelineXray\n\n**Read X's open-source recommendation algorithm with receipts.**\n\nCommit-pinned evidence, exact source spans and a findings memory that notices when the code changes,\nfor people and AI agents studying [`xai-org/x-algorithm`](https://github.com/xai-org/x-algorithm).\n\n[](https://github.com/solisolsoli/timelinexray/actions/workflows/ci.yml)\n[](LICENSE)\n[](pyproject.toml)\n[](pyproject.toml)\n[](docs/mcp.md)\n\n[Quickstart](#quickstart) · [Why](#why) · [Features](#features) · [MCP for agents](#use-it-from-an-ai-agent-mcp) · [Docs](#documentation) · [Limits](docs/limits.md)\n\n
\n\nIndependent community analysis of publicly available source code. Not affiliated with or endorsed by X or xAI.\n\n```console\n$ txray param-history ClickWeight # excerpt\nparam! ClickWeight home-mixer/params/param.rs\n 2026-09-26T03:39:02Z 4c5cfe8f07f1 present at the start of the line, public default 0.4\n 2026-09-29T03:06:30Z a707cc27ba36 value changed: public default 0.4 -> 0.3 (old L322 sha256:b01734cae3e1124e at 4c5cfe8f07f1; new L329 sha256:4b5c535dbf7b2b6a)\n current: public default 0.3 at 77d431aabf40 (3 pinned commit(s) with a value)\n...\nnote values are public defaults at the cited commits, not production values; computed from pinned commits only (nothing fetched)\n```\n\n## Why\n\nWhen the recommendation code behind a large social network is published, most of what gets\nwritten about it is screenshots, paraphrase and threads that go stale with the next commit.\nThe upstream repository changes often, its commit messages say almost nothing (most read\n\"Open-source X Recommendation Algorithm\"), and the numbers in it are defaults that a\nconfiguration system can override.\n\nTimelineXray makes every statement about that code checkable:\n\n- **Pinned, not moving.** Every answer names a commit. Nothing depends on a branch.\n- **Exact bytes.** A citation is a line span read from a git blob, with its SHA-256 and an\n anchor check, so anyone can reproduce it.\n- **Findings that expire.** Claims live in a hash-chained ledger; when a newer commit changes\n the cited code, the claim is marked `STALE` instead of quietly staying \"true\".\n- **Honest numbers.** Every value is labelled a *public default at a commit*, never a\n production value or a reach prediction.\n\n## Features\n\n| | |\n| --- | --- |\n| **One-command setup** | `install.sh` checks Python, SQLite FTS5 and git, then installs `txray`; `txray setup` pins and indexes the tested upstream commit and prints your next commands and the agent connection line. |\n| **Snapshots and manifests** | Pin upstream commits into a local bare mirror; classify **every** path (parsed, text, excluded with a reason) with blob ids, sizes, hashes and a license inventory. |\n| **Exact spans** | `txray show` reads line ranges from blobs (never a working tree), keeps CRLF and missing final newlines, and reports span and blob SHA-256 plus whether an anchor occurs. |\n| **Native code index** | Lexical search, symbols and unresolved call candidates for Rust, Scala, Python and Java on SQLite FTS5: 2,147 files and 50,387 symbols at `77d431a`. |\n| **Parameter tools** | `txray param` and `txray param-history` find declarations and their public defaults and trace value changes across pinned commits, both sides cited. |\n| **Findings memory** | A hash-chained ledger of claims whose every citation is a byte span; re-anchoring marks changed evidence `STALE`; only a different reviewer can confirm a claim. |\n| **Change digests** | `txray diff`, `digest` and `update` classify what changed between two commits from the diff itself (never from commit messages) and list the findings it touches: a short main digest (summary, parameter defaults, registrations, scoring changes, with citations), an appendix with every other item, and the complete JSON. |\n| **Read-only MCP server** | Thirteen tools over stdio (`search_code`, `read_span`, `find_symbols`, `get_param`, `param_history`, `verify_claim`, `stale_worklist`, ...) so agents cite instead of guess. |\n| **Offline creator metrics** | `txray metrics` computes descriptive metrics from *your own* analytics export in a network-disabled process. Never a reach prediction. |\n| **Context Layer export** | Optional: write current findings as Markdown notes with permalinks and `[[wikilinks]]` for a [Context Layer](https://github.com/solisolsoli/context-layer) or Obsidian vault. |\n\nPure standard library at runtime. The only network access is `git fetch` from an allowlisted\nupstream URL. No X API, no scraping, no posting, no telemetry.\n\n## Quickstart\n\nTwo commands take you from nothing to a cited answer. You need Linux or macOS, Python 3.11+\nwith SQLite FTS5 (trigram tokenizer) and git 2.38+; the installer checks all three first.\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/solisolsoli/timelinexray/main/install.sh | sh\ntxray setup\n```\n\nThe installer prints what it found and what it runs (excerpt; it uses `uv` or `pipx` when\npresent, else a private virtual environment, and never edits your shell files):\n\n```console\n$ curl -fsSL https://raw.githubusercontent.com/solisolsoli/timelinexray/main/install.sh | sh\nos: Darwin\npython: /usr/bin/python3 (3.12.4, SQLite 3.45.3 with FTS5 and the trigram tokenizer)\ngit: /usr/bin/git (2.54)\nmethod: venv\npackage: git+https://github.com/solisolsoli/timelinexray@main\n...\n+ ~/.local/share/timelinexray/venv/bin/python -m pip install --disable-pip-version-check git+https://github.com/solisolsoli/timelinexray@main\n+ ln -sf ~/.local/share/timelinexray/venv/bin/txray ~/.local/bin/txray\n+ ~/.local/bin/txray --version\ntxray 0.11.0\n\nTimelineXray is installed. Next step:\n txray setup\n```\n\n`txray setup` pins the tested upstream commit (`77d431a`) and builds its code index, once\n(excerpt; paths shortened, timings from one laptop):\n\n```console\n$ txray setup\ncommit 77d431aabf409ca1c1eed9bec7e2183f7c914e23\nstore ~/.cache/timelinexray\npin pinned (fetched from the upstream)\nindex indexed: 2147 paths, 2140 files with indexed lines, 50387 symbols\nelapsed 8.16 s\n\ntry next\n txray search 77d431a ClickWeight\n txray param ClickWeight --commit 77d431a\n txray show 77d431a README.md --lines 1-20\n\nconnect an agent (prints only; no client configuration is edited)\n claude mcp add --transport stdio timelinexray -- /path/to/bin/txray mcp serve --store /path/to/store\n txray setup --print-mcp-config json (an mcpServers snippet)\n\nNumbers in the code are public defaults at the pinned commit, not production values.\n```\n\nA second `txray setup` fetches and indexes nothing (0.17 s on the same laptop). Then ask\nfor a cited answer:\n\n```sh\ntxray show 77d431a home-mixer/params/param.rs --lines 327-331 --anchor ClickWeight\n```\n\n```console\ncommit 77d431aabf409ca1c1eed9bec7e2183f7c914e23\npath home-mixer/params/param.rs\nlines 327-331 of 980 (bytes 7900-8053, 153 bytes)\nblob d2bad9d35b39ee11e20dcae58ef496ff860e3fed sha256 47ad9a0b916049681e2a1561c8e418f2fa6f17f0ad00ea017d3cfa3e5de6ce1b\nspan sha256 b923bbcbd2ff34ec1c61bfb2f24354d247ef9f77c914c53b092e4a33885fa8e9\nendings lf=5 crlf=0 unterminated=0\nclass parsed-candidate (rust)\nanchor FOUND at line 329 (byte 7919)\nnote numbers in the output above are public defaults at commit 77d431aabf409ca1c1eed9bec7e2183f7c914e23, not production values\n----\n 0.07\n);\nparam!(ClickWeight, f64, \"rust_home_mixer_click_weight\", 0.3);\nparam!(OpenLinkWeight, f64, \"rust_home_mixer_open_link_weight\", 0.2);\nparam!(\n```\n\nOther ways to install (all give the same `txray`; details, options, uninstall and\ntroubleshooting in [docs/install.md](docs/install.md)):\n\n```sh\nuv tool install git+https://github.com/solisolsoli/timelinexray\npipx install git+https://github.com/solisolsoli/timelinexray\n\n# read the script before running it\ncurl -fsSLO https://raw.githubusercontent.com/solisolsoli/timelinexray/main/install.sh\nsh install.sh --dry-run # prints every command, changes nothing\nsh install.sh\n```\n\n## How it works\n\n```mermaid\nflowchart LR\n U[(xai-org/x-algorithm)] -- \"git fetch
allowlisted URL only\" --> M[Bare mirror
pinned commits]\n M --> F[Manifest
every path, hashed]\n M --> S[Exact spans
blob bytes + SHA-256]\n M --> I[Code index
SQLite FTS5, symbols]\n I --> P[Parameters
public defaults + history]\n S --> L[Findings ledger
hash chain]\n L -- \"re-anchor on a newer commit\" --> R{CURRENT / STALE /
UNVERIFIABLE}\n M --> D[Diffs and digests
local files]\n S & I & P & L --> X[Read-only MCP server
stdio]\n```\n\nUpstream code is only ever read as data from git objects: never checked out into an agent's\nproject, never executed, never redistributed. Details: [docs/architecture.md](docs/architecture.md).\n\n## Use it from an AI agent (MCP)\n\n```sh\ntxray setup --print-mcp-config # prints the exact `claude mcp add ...` line, absolute paths\n```\n\nRun the printed line once; it looks like\n`claude mcp add --transport stdio timelinexray -- /path/to/bin/txray mcp serve --store /path/to/store`.\n`--print-mcp-config json` prints an `mcpServers` snippet for other stdio clients; neither form\nedits any client configuration. See [docs/agents/](docs/agents/) for configuration files and a\nshort evidence snippet for your `AGENTS.md` / `CLAUDE.md`. The server is read-only, never\nfetches, and refuses a store that contains an analytics dataset. Tested so far: Claude Code\n2.1.286 (print mode, code tools); every other client is listed as untested in the\n[client matrix](docs/mcp.md#client-matrix).\n\n## What it is not, and when not to use it\n\n- **Not a reach predictor or an \"algorithm score\".** Nothing it computes predicts reach or\n reconstructs a ranking score. The upstream README (at `77d431a`) says many tunable values\n come from a configuration system and experiments run on a share of traffic, so numbers in\n the code are shown as public defaults at a named commit.\n- **Not an X API client, scraper, posting bot or engagement automation.** No telemetry.\n- **Not a runner of upstream code.** Upstream files are parsed and read as data only.\n- **Not a redistribution of upstream source.** The upstream repository is fetched at runtime\n into a local store; this repository contains none of it.\n\nReach for something else if you want growth tips, a posting schedule or a single score for\na post: TimelineXray answers \"what does the public code say, at which commit, in which\nbytes\", and stops there. Windows is not supported yet, and the parser is lexical (no type\nresolution); see [docs/limits.md](docs/limits.md).\n\n## Status\n\nVersion `0.11.0`, alpha: all six milestones are implemented (evidence foundation, native code\nindex, findings memory, read-only MCP server, change digests and offline metrics, release\nhardening), plus the fixes of an end-to-end audit. Interfaces may change before 1.0.\n\nQuality is measured, not asserted. `make ci` runs 863 tests against the real upstream, and the CI\nworkflow runs it on Linux and macOS for Python 3.11, 3.12 and 3.13. The semantic release gate (40 reviewed questions answered by\nan agent through the MCP tools, scored by rule) **passed for the first time on 2026-10-07**\n(set revision 2, agent contract r2, haiku): precision 30/30, coverage 30/31, abstention 9/9,\nfalse abstentions 1/31, 48/48 intact citations, no errors. It is one run of one model, and earlier\nruns of the same set varied (abstention 9/9, then 7/9), so it shows the gate can be met, not that\nevery run meets it; the three earlier runs did not pass and stay recorded as measured. The numbers, the analysis and the\nnext steps are in [docs/release-checklist.md](docs/release-checklist.md#3a-semantic-release-gate-audit-section-6-item-5-p7-sections-71-73).\nEvery known limit is listed in [docs/limits.md](docs/limits.md).\n\n## Command reference\n\n```sh\n# One command after installing: pin + index the tested commit, print next steps\ntxray setup # --latest pins upstream main instead; --no-index pins only\ntxray setup --print-mcp-config # prints the `claude mcp add` line (or `json`); changes nothing\n\n# Pin a commit (fetches from the allowlisted upstream only if the commit is not yet local)\ntxray pin 77d431aabf409ca1c1eed9bec7e2183f7c914e23\n\n# Every path with its classification; --summary for counts and license files\ntxray manifest 77d431a --summary\n\n# Exact lines 57-60 of a file, with blob and span hashes and an anchor check\ntxray show 77d431a xai-value-model/scoring.rs --lines 57-60 --anchor \"fn apply\"\n\n# Only the span bytes, byte for byte\ntxray show 77d431a xai-value-model/scoring.rs --lines 57-60 --raw\n\n# Native code index for a pinned commit, then search and list symbols\ntxray index 77d431a --coverage\ntxray search 77d431a \"PhoenixScorer\" --path \"home-mixer/*\" --limit 5\ntxray symbols 77d431a --name compute_weighted_score\n\n# Parameter declarations with their public default at a commit, and over the pinned commits\ntxray param ClickWeight --commit 77d431a\ntxray param-history ClickWeight # 0.4 -> 0.3 at a707cc2, both sides cited; no fetch\n\n# Read-only MCP server for agents (stdio; see docs/mcp.md and docs/agents/)\ntxray mcp serve --store ~/.cache/timelinexray --ledger ~/.cache/timelinexray/findings\ntxray mcp tools --json\n\n# Findings ledger (kept outside any git working tree: --ledger, $TXRAY_FINDINGS or /findings)\ntxray findings add --actor author-1 --title \"...\" --claim \"...\" --evidence-class CODE \\\n --status SUPPORTED --cite 77d431a xai-value-model/scoring.rs 65-119 compute_weighted_score\ntxray findings verify F-... # span integrity only (INTACT / CHANGED / MISSING)\ntxray findings reanchor # freshness only: CURRENT / STALE / UNVERIFIABLE\ntxray findings stale # what to re-review first: old and aligned spans, exact commands\ntxray findings verify --pin-cited # pin the commits imported citations name, re-verify, re-anchor\ntxray findings review F-... --actor reviewer-1 --role reviewer --status SUPPORTED --rationale \"...\"\ntxray findings verify-log # hash chain and HEAD\n\n# Classified changes and a reviewed digest between two pinned commits (nothing is posted)\ntxray diff 4c5cfe8 a707cc2 --class parameter-default\ntxray digest 4c5cfe8 a707cc2 --out ~/txray-digests # main digest + appendix; --ledger DIR for affected findings\ntxray update --out ~/txray-digests # guarded fetch + pin + digest; schedule it yourself\ntxray update --out ~/txray-digests --reanchor --export ~/vault/txray\n # also re-anchors the ledger on the new head and refreshes the notes\n # (docs/updates.md, \"Keeping the ledger fresh\")\n\n# Offline creator metrics from your own export (network disabled in this process)\ntxray metrics import export.csv --schema x-post-v1 --lang en --dump-header # header mapping only: no data row read, nothing written\ntxray metrics import export.csv --schema x-post-v1 --lang en --out ~/private/txray-metrics \\\n --captured-at 2026-09-30T18:00:00+09:00 --counts cumulative --scope combined\ntxray metrics rwe ~/private/txray-metrics\ntxray metrics reach ~/private/txray-metrics --horizon 24h\n```\n\n`txray digest --out` and `txray export --out` refuse a symbolic link, a missing parent, the\nworking tree, the snapshot store, the ledger and an analytics dataset as destination.\n\nAnalytics datasets are private: keep them outside the snapshot store and version control;\nthey are never served over MCP. Every metrics output starts with the notice \"This is not a\nreach prediction.\"\n\nEvery command accepts `--json` for a machine-readable envelope and `--store DIR` to choose\nthe snapshot store, except that `txray mcp serve` takes `--store`, `--ledger` (default `$TXRAY_FINDINGS`, else\n`/findings`) and `--time-budget` but no `--json`, and `txray mcp tools` takes `--json` only.\n\n| Setting | Meaning |\n| --- | --- |\n| `--store DIR`, `TXRAY_STORE` | Snapshot store location. Default: `$XDG_CACHE_HOME/timelinexray` or `~/.cache/timelinexray`. Keep it outside any agent's project directory. |\n| `--upstream URL` | Repository to pin from. Default and only network URL: `https://github.com/xai-org/x-algorithm.git`. |\n| `TXRAY_ALLOW_FILE_URLS` | Whitespace-separated `file://` repository URLs that may also be used (local mirrors, tests). Any other scheme here is rejected. |\n\nExit codes: `0` success; `1` the operation failed (not found, refused, integrity mismatch,\nline range past end of file, git failure); `2` invalid arguments; `3` network access refused\nby the allowlist.\n\n## Documentation\n\n| Topic | Document |\n| --- | --- |\n| Installing, options, uninstall, troubleshooting | [docs/install.md](docs/install.md) |\n| Design and data flow | [docs/architecture.md](docs/architecture.md) |\n| Code index | [docs/code-index.md](docs/code-index.md) |\n| MCP server, tools and client matrix | [docs/mcp.md](docs/mcp.md), [docs/agents/](docs/agents/) |\n| Findings ledger, re-anchoring, review | [docs/findings-memory.md](docs/findings-memory.md) |\n| Diffs, digests and `txray update` | [docs/updates.md](docs/updates.md) |\n| Reviewed upstream changes, 2026-10-15 | [docs/research/upstream-2026-10-15.md](docs/research/upstream-2026-10-15.md) |\n| Offline metrics from your own export | [docs/analytics.md](docs/analytics.md) |\n| Optional Context Layer export | [docs/context-layer.md](docs/context-layer.md) |\n| Known limits | [docs/limits.md](docs/limits.md) |\n| Release checks and the semantic gate | [docs/release-checklist.md](docs/release-checklist.md) |\n\n## Contributing\n\n```sh\nmake test # unittest suite; no test uses the network\nmake lint # byte-compile src, tests and scripts; check the CI workflow\nmake ci # exactly what CI runs: lint, hygiene, strict tests, build + clean-venv install\n```\n\nTests that need the real upstream use a local clone through a `file://` URL: set\n`TXRAY_TEST_UPSTREAM` to a clone containing `92f0918` and its full history, including the\nhistorical `77d431a` pin (`python scripts/fetch_test_upstream.py DIR` makes one), or place\none at `../x-algorithm-upstream`. Without it those tests are\nskipped; with it, `make ci` fails if any test is skipped. The build step of `make ci`\ndownloads `setuptools>=77` from PyPI into an isolated virtual environment; the tool itself\nnever uses the network except its guarded fetch.\n\nStart with [CONTRIBUTING.md](CONTRIBUTING.md). Contributor and agent rules, including the\nevidence contract, are in [AGENTS.md](AGENTS.md) (identical to `CLAUDE.md`). Security\nreporting and the threat model are in [SECURITY.md](SECURITY.md).\n\n## Citing\n\nIf you use TimelineXray in research or reporting, cite the pinned upstream commit together\nwith the tool version. GitHub's \"Cite this repository\" button reads [CITATION.cff](CITATION.cff).\n\n## License\n\nApache License 2.0 for this project's original code; see [LICENSE](LICENSE) and\n[NOTICE](NOTICE). Upstream source is fetched at runtime and remains under its own terms;\nthe manifest's license inventory records the license and notice files it contains.\n"}