<p align="center">
<img src="assets/logo.png" alt="TimeGlyph" width="180" />
</p>
# TimeGlyph
[](https://crates.io/crates/timeglyph)
[](https://docs.rs/timeglyph)
[](LICENSE)
[](https://github.com/SecurityRonin/timeglyph/actions/workflows/ci.yml)
[](https://github.com/SecurityRonin/timeglyph/releases)
[](https://github.com/sponsors/h4x0r)
**Decode any timestamp. Identify the unknown ones. See time itself.**
<p align="center">
<img src="assets/lens-demo.gif" alt="TimeGlyph Lens decoding a timestamp live as the cursor hovers a value on screen" width="760" />
<br />
<em>TimeGlyph Lens — hover any number on screen and read its time live, ranked and cited.</em>
</p>
Every examination throws raw timestamps at you — a `133801920000000000` buried in
an artifact — that you need in human-readable time. `timeglyph` reads that value
every way a system might have written it and reports the results **ranked, scored,
and cited** — honest about the ambiguity instead of guessing one answer.
Mostly you never type them at all: **hover the number and read its time live.** When
you need more, the same engine converts a whole CSV in one pass, or lays a month out as
a **timezone/DST/leap-aware reference calendar** — DST fold/gap days, leap seconds, GPS
week, format epochs, and the moon's phase, all flagged. One static Rust binary and a
live overlay, from a single install command.
**[Try it in your browser →](https://securityronin.github.io/timeglyph/playground.html)** · **[Full documentation →](https://securityronin.github.io/timeglyph/)**
The playground runs the real engine as WebAssembly, entirely client-side — paste a value, see every ranked, cited reading; nothing leaves the page.
```console
$ timeglyph 1577836800
# readings consistent with 1577836800 (ranked; a raw value is usually underdetermined — not a single verdict):
[1.00] unix 2020-01-01T00:00:00Z (Unix time (seconds))
[0.94] postgres 2000-01-01T00:26:17.8368Z (PostgreSQL timestamp (µs since 2000))
[0.67] cocoa 2051-01-01T00:00:00Z (Cocoa / CFAbsoluteTime (s since 2001))
[0.67] hfsplus 1953-12-31T00:00:00Z (Apple HFS+ (s since 1904))
...
```
---
## Install
One command per platform — each installs **both** the `timeglyph` CLI and the
[**Lens**](#timeglyph-lens--hover-anything-decode-time-data) overlay app.
**macOS**
```bash
brew install --cask securityronin/tap/timeglyph-lens
```
**Windows**
```powershell
winget install SecurityRonin.timeglyph
```
**Debian / Ubuntu**
```bash
```
You get the CLI on your `PATH` plus a real launcher for the overlay — a
Launchpad/Spotlight app on macOS (Developer-ID-signed and notarized), a Start Menu
shortcut on Windows, a desktop entry on Debian/Ubuntu (amd64 and arm64).
<details>
<summary>CLI only (Cargo, or the portable Linux archive)</summary>
```bash
cargo install timeglyph
```
`cargo install` and the static musl archive ship the CLI alone — no overlay.
On macOS you can also take the CLI by itself with
`brew install securityronin/tap/timeglyph`.
</details>
---
## What you do with it
### TimeGlyph Lens — hover anything, decode time data
The way most people use it: **never type a timestamp again.** Hover any number on
screen and read its time live. An always-on-top overlay follows your cursor and shows
timeglyph's ranked readings for the number in the UI element under the pointer — so you
never copy a value into a converter. Each row carries its confidence, the weekday, and
the public holiday for that date in the chosen zone. Pick any display timezone from the
footer.
It comes with the [one-command install](#install) above, and reads the element under
the cursor through the platform accessibility layer — the Accessibility API on macOS,
UI Automation on Windows, and AT-SPI on Linux (X11, with assistive technologies
enabled).
**Can't hover it? Copy it.** Some values aren't in the accessibility tree at all — a
VM guest window is one opaque framebuffer to the host, and so is a canvas, a rendered
image, or a remote-desktop session. Copy the value and press the header **🗐** button:
same ranked readings, from the clipboard. It reads once per press — nothing polls your
pasteboard — and the clipboard's contents are never drawn as the source caption.
[Overlay guide →](docs/lens.md)
### Identify an unknown value
```bash
timeglyph 1577836800 # ranked, scored readings across every format
timeglyph identify --json 1577836800 # same, machine-readable
timeglyph --as hex 0060947C58B2D501 # raw bytes only: little/big-endian + packed on-disk
timeglyph --as string 20200101000000Z # string forms only: ISO / RFC 2822 / ASN.1
```
Exit codes are pipeline-safe: `0` clear top reading, `2` ambiguous or a sentinel
(review needed), `1` error. Render in any timezone with `--tz` (`UTC`, a fixed
offset, or a DST-correct IANA name); nudge readings toward a source family with
`--artifact "<hint>"`.
### Decode or encode a known format
```bash
timeglyph decode filetime 132223104000000000
timeglyph decode fat 1545691136 # FAT/DOS packed date+time (LOCAL) — one of 45 formats
timeglyph encode unix 2020-01-01T00:00:00Z
timeglyph explain filetime # a spec card: epoch, tick, tz/leap, range, sentinels, citation
timeglyph list # the format registry, with spec citations
```
### Mine artifacts at scale
```bash
timeglyph scan < app.log # find & decode every timestamp in a file (or stdin)
timeglyph carve aabbcc… --from 2015 --to 2026 --json # carve timestamps at every byte offset
timeglyph csv events.csv # enrich a CSV with human-readable timestamp columns
```
Convert in bulk: enrich a whole CSV of timestamps in one pass instead of pasting
them into a converter one at a time. `carve` sweeps a raw blob (a config, a
record, a hex selection) for timestamps at every offset — window- and
score-thresholded — and exports JSONL, ImHex bookmarks, or Timesketch events.
[CSV enrichment →](docs/csv.md)
### See time in context — the reference calendar
```bash
timeglyph cal # this month, with DST/leap/epoch markers
timeglyph cal 2026-11 --tz America/New_York # DST fold/gap days flagged
timeglyph cal 2026-09-18 # one day in full: week/epoch systems + a moon disc
timeglyph cal 2026 --json # a whole year, faithful per-day records
```
`cal` is a calendar built for temporal analysis: per-day UTC offset and DST
fold/gap days, leap-second days and GPS week, ISO week / Julian Day / Unix,
timestamp-format epoch and rollover markers, seven alternative calendars (Chinese
lunisolar with the 干支 four pillars, plus ROC, Japanese, Buddhist, Hebrew, Islamic,
and Persian), and the moon's phase — every value computed and oracle-validated
(`date`, `zdump`, USNO, IERS, JPL).
[The reference calendar →](docs/cal.md)
### Use it from an LLM / agent
```bash
timeglyph mcp # a Model Context Protocol stdio server
```
`mcp` exposes `identify` / `decode` / `explain` as MCP tools, so an LLM-driven
DFIR workflow gets a cited, reproducible reading instead of a hallucinated epoch
conversion.
**Every reading is scored and checked against an independent oracle** — each names
the spec it assumes, and correctness is validated against primary-spec worked examples
and the MIT [`time_decode`](https://github.com/digitalsleuth/time_decode) tool, with
calendar/astronomy values cross-checked against `date`, `zdump`, USNO, IERS, and JPL.
So a reading on *your* weird timestamp is evidence you can cite, not a guess. See
[validation](docs/validation.md).
---
## 45 formats, every reading cited
`timeglyph` decodes and auto-identifies **45 registered formats** plus the
self-describing string forms:
- **Epoch integers & floats** — Unix (s/ms/µs/ns and `double`), FILETIME (incl.
Active Directory / LDAP), WebKit/Chrome, Cocoa / CFAbsoluteTime (integer, signed
double, iOS-11 ns), Apple HFS+/HFS, .NET ticks, OLE automation, Excel-1904,
PostgreSQL, Mozilla PRTime, SQLite Julian day, DHCPv6, Modified Julian Day
- **Embedded IDs** — KSUID, ULID, UUIDv1 / v6 / v7, MongoDB ObjectId, GMail message
IDs, and Snowflake-class IDs (Twitter/X, Discord, Mastodon, LinkedIn, TikTok, Sonyflake)
- **Packed & mobile/broadcast** — FAT/DOS and exFAT date-time words, 128-bit
SYSTEMTIME structs, Microsoft DTTM, BCD, GSM 7-byte semi-octet, Nokia, DVR,
Motorola, Symantec, and SQL Server DATETIME
- **Strings** — ISO 8601 / RFC 3339, RFC 2822 email dates, EXIF, ASN.1
GeneralizedTime & UTCTime
- **Leap-aware scales** (`--features leap`) — GPS, TAI64, NTP, kept separate from
the POSIX spine
Each reading is scored on window membership, granularity, magnitude, byte-width,
endianness, artifact context, and neighbour monotonicity — so the ranking reflects
the evidence, not format popularity. (Validated against an independent oracle — see
the trust note above and [validation](docs/validation.md).)
---
## Why another converter?
Good ones exist ([`time_decode`](https://github.com/digitalsleuth/time_decode),
MIT; DCode, proprietary). `timeglyph` is a single static Rust binary built on a
**rigorous, cited model** where a reading is *evidence, not a verdict*: a
POSIX-correct internal spine (never mislabelled UTC), the leap-second family kept
separate, and **ambiguity as first-class, scored output**. Calendar and timezone
math is reused (`jiff`), never reinvented. See
[the design decisions](docs/decisions/).
---
**Point it at the timestamp you're stuck on.** → `cargo install timeglyph`, or
[try it in your browser](https://securityronin.github.io/timeglyph/playground.html) —
no install, nothing leaves the page.
---
[Privacy Policy](https://securityronin.github.io/timeglyph/privacy/) · [Terms of Service](https://securityronin.github.io/timeglyph/terms/) · © 2026 Security Ronin Ltd