v0.3.7

v0.3.7

Fixed: no more SQLITE_BUSY crash on concurrent launches

If you launched dsx while another dsx process was already running (typically
a live TUI doing its background index refresh, or two launches racing), the
new process could die instantly with:

SQLiteError: database is locked (SQLITE_BUSY)

Two changes fix this:

• dsx now waits (up to 5s) for the other process's write to finish instead of
  failing immediately.
• Launching dsx no longer writes to the index at all when the schema is
  already current, so plain concurrent launches can't contend at startup.

Your index data was never at risk — SQLITE_BUSY was pure lock contention,
and any interrupted operation rolls back cleanly under WAL.

Verification

• Reproduced the two-process contention both with and without the fix
  (fails in 1ms before, succeeds after a short wait now).
• Full test suite (62 tests), typecheck, and compiled-binary smoke test green
  locally; all four release artifacts built by CI.

No new commands, flags, or behavior changes otherwise — upgrade in place.

v0.3.6

dsx v0.3.6 — AGENTS.md guidance, one sync command

dsx now installs a small guidance block into your AGENTS.md alongside the companion skill, teaching droids two habits that only work when they're ambient: logging papercuts (dsx papercut add) when workflow friction costs time, and searching past sessions (dsx search) after two failed attempts at the same problem, before a third.

New: dsx sync (replaces dsx skill sync)

One command manages both companion assets:

dsx sync            # questionnaire: skill dirs + AGENTS.md files (choices remembered)
dsx sync --apply    # non-interactive: reapply saved choices, ask only new questions
dsx sync --force    # overwrite an AGENTS.md block you hand-edited

The installer runs dsx sync --apply on every install/update, so both assets refresh automatically. Without a terminal (agent/CI installs) it never prompts: defaults are ~/.agents/skills/dsx and ~/.agents/AGENTS.md, and it prints what it did. Deselecting an asset in the questionnaire removes it cleanly.

How the AGENTS.md block behaves

The guidance lives between <!-- dsx:begin <hash> --> and <!-- dsx:end --> markers:

• Move it anywhere. Updates replace the block in place; position in your file is yours.
• Hand-edits are safe. The marker hash detects edits inside the block; sync then skips that file and tells you (--force overwrites). Everything outside the block is never touched.
• Missing paths are created, including the file itself if you have no AGENTS.md yet.
• Removing the block by hand and re-running dsx sync re-adds it; deselect it in the questionnaire instead.

Migration notes

• dsx skill sync is gone (including --to); use dsx sync. Your saved skill choice carries over: skill-prefs.json is read once and migrated to sync-prefs.json.
• Existing installs get the new AGENTS.md question defaulted on the next non-interactive update, or asked on the next interactive dsx sync.

Verification

62 tests (block create/append/in-place update/idempotence/edit-skip/force/removal, prefs migration), typecheck, compiled-binary smoke tests of the non-tty flow, legacy prefs migration, and idempotence against a real, reorganized AGENTS.md.

v0.3.5

v0.3.5 — the companion skill installs itself

The dsx companion skill (the one that teaches droids to mine their own
session history) now ships inside the binary. Installing or updating dsx via
install.sh offers to install it; previously the only way to get the skill
was cloning the repo and symlinking .agents/skills/dsx by hand.

New: dsx skill sync

dsx skill sync                         # (re)answer the questionnaire
dsx skill sync --to ~/.agents/skills   # pick target dir(s) directly
dsx skill sync --apply                 # reapply your saved choice (what install.sh runs)

• The questionnaire offers ~/.agents/skills/dsx (default yes) and
  ~/.factory/skills/dsx (default no). Your answers are cached at
  $XDG_DATA_HOME/dsx/skill-prefs.json, so installer re-runs refresh the
  skill silently instead of re-asking. Bare dsx skill sync always re-asks,
  with your cached answers as the defaults.
• Declining is remembered too, and removes any previously installed copies;
  so does deselecting one directory.
• Without a terminal (agent-driven installs, CI), nothing prompts, hangs, or
  fails: dsx applies your saved choice, or on first run installs the default
  (~/.agents/skills/dsx) and prints a line saying so.

Behavior changes

• install.sh now runs dsx skill sync --apply after installing the binary.
  Existing users see the questionnaire once on their next update, then never
  again unless they run dsx skill sync themselves.
• If you previously symlinked the skill from a clone, accepting that
  directory replaces the symlink with a real copy (version-locked to the
  binary); the clone itself is untouched.
• The skill is embedded at build time from .agents/skills/dsx/, the same
  source as the dsx ask / dsx insights --deep sub-droid cheatsheet, so
  installed skill and binary can never drift apart.

Verification

• 48 tests (8 new covering skill write/overwrite, symlink replacement,
  deselection cleanup, prefs round-trip), typecheck, SEA smoke tests on
  linux-x64: interactive questionnaire over /dev/tty, silent --apply
  re-runs, no-tty defaulting, decline-removes-copy.

Caveat: a harness that allocates a pty for shell commands is
indistinguishable from a human terminal, so a first-time install there still
shows the questionnaire.

v0.3.4

dsx v0.3.4

The TUI is now live: it keeps itself indexed while open, stays responsive while doing so, and the dashboard renders about twice as fast. No CLI changes; --json shapes are unchanged.

Live TUI

The background refresh introduced in v0.3.3 now repeats every 30 seconds while the TUI is open. Dashboard KPIs, the daily sparkline, and the session list track your running droid sessions without relaunching or pressing anything. Idle cycles (nothing new on disk) cost a file scan and trigger no re-render.

Ingest no longer competes with your keystrokes

Indexing transactions are bounded at 2,000 lines or 2MB per burst, with a real event-loop turn between bursts. View switching during a heavy backlog ingest now responds at normal latency (verified against a 100MB backlog: switches complete in ~1s, same as idle).

Faster dashboard

A covering index on per-session daily activity cuts the dashboard's heaviest query (byDay pro-ration, also behind dsx stats --by day) from ~560ms to ~220ms on a 950k-message index. The index is created automatically the first time v0.3.4 opens your existing index (a one-time ~0.4s), no rebuild.

Verification

bun test, tsc --noEmit, compiled linux-x64 SEA. Scripted TUI runs: first frame ~560ms including the one-time index build, live cycle observed updating KPIs from sessions appending in real time, view switching timed during a simulated 100MB backlog ingest, clean quit.

Install

curl -fsSL https://raw.githubusercontent.com/ain3sh/droid-session-explorer/main/install.sh | bash

v0.3.3

dsx v0.3.3

Fixes the multi-second blank terminal between hitting Enter on dsx and seeing the dashboard.

TUI: first paint no longer waits for indexing

Previously the TUI ran a full index refresh before starting the renderer. Ingest costs roughly 130ms per 2MB of new transcript, so after a stretch of active droid work the accumulated appends (not new sessions, appends to sessions you were still running) routinely meant 5+ seconds of nothing after Enter.

Now the dashboard renders immediately from the existing index (~0.4s even with 100MB of pending appends, measured), the refresh runs in the background with indexing N/M changed files... in the footer, and the dashboard, sessions, stats, and insights views re-query automatically when it finishes. Quitting no longer waits for an in-flight refresh; interrupted ingest resumes from its byte offset on the next run.

No CLI changes: commands still refresh before answering (use --no-refresh to skip), and --json shapes are unchanged.

Verification

bun test, tsc --noEmit, compiled linux-x64 SEA. Scripted TUI runs against a copy of a real 1.3GB index rewound by 100MB: first frame at 0.39s with the indexing status visible, status clears on completion, views update, clean quit. Steady-state warm launch measured at ~0.5s end to end in a real terminal pane.

Install

curl -fsSL https://raw.githubusercontent.com/ain3sh/droid-session-explorer/main/install.sh | bash

v0.3.2

dsx v0.3.2

Under-the-hood release: faster runtime, faster queries, no command or flag changes. Existing --json output shapes are unchanged.

Bun 1.4 runtime

Release binaries are now built on Bun 1.4 (the CI runner tracks latest and crossed over on 2026-08-20; this is the first release verified against it end to end). Bun 1.4 halves cold-start time on Linux and cuts base memory roughly in half, which dsx feels directly as a short-lived CLI: dsx --version runs in ~65ms and dsx --no-refresh list in ~90ms on the compiled binary.

Query-layer performance

• dsx list (and the TUI session views) now page with LIMIT/OFFSET inside SQLite instead of materializing every session summary per call. Fuzzy title filtering (-q) still scans all candidates, as it must.
• dsx insights builds session summaries once and finds cost outliers with a binary search over the sorted credit distribution, replacing a quadratic scan. On a ~5,400-session index the report stays interactive in the TUI.
• dsx search --regex streams ripgrep's output and kills it as soon as the hit limit is reached instead of buffering everything; a limited search over a multi-GB session tree returns in ~130ms.

Internal cleanup (no behavior change)

• One shared WHERE builder now backs list, stats, and insights filtering; previously three hand-rolled copies were drifting apart.
• dsx index migrate-path skips dangling symlinks in the session root instead of crashing mid-scan.
• Timestamps at epoch 0 no longer parse as missing.

Verification

bun test (40 tests), tsc --noEmit, and the compiled linux-x64 SEA were verified on Bun 1.4.0: CLI smoke across list/search/insights/stats (human, --json, fuzzy, and regex paths), plus scripted TUI checks (dashboard render, view switching, live fuzzy filter, search-to-transcript open, clean quit with screen restore).

Install

curl -fsSL https://raw.githubusercontent.com/ain3sh/droid-session-explorer/main/install.sh | bash

v0.3.1

Fixes a crash on startup, and the index is now ~40% smaller

If dsx was crashing for you with TypeError: undefined is not an object (evaluating 'record.message.role'), this release fixes it. Just upgrade — no
flags, no config, nothing to migrate.

The crash

Some transcripts store messages in a flat shape (role and text directly on
the record, with an epoch-millisecond timestamp) instead of the usual nested
message object. A few also contain permission audit entries that are labeled
as messages but carry no message content at all. Indexing assumed the nested
shape and died on the first record that didn't match, taking the whole run with
it — including dsx with no arguments, since that refreshes the index before
opening the TUI.

All three shapes are now handled. Sessions that previously killed the indexer
show up normally in list, search, show, and export, and their timestamps
resolve correctly.

Smaller index

The full-text index used to keep its own verbatim copy of every message, on top
of the transcripts already on disk. That copy was about two thirds of the
index file. It's gone: search now reads matching lines back from the source
transcript when it builds result snippets.

On a real ~6 GB session store:

	before	after
~/.cache/dsx/index.db	1,521 MB	949 MB
indexed blocks	670k	1,261k
bytes per block	2,270	752

The "before" number is from a partial index (it had crashed partway). Like for
like, the index holds nearly twice the content in about 60% of the space.

Search output is unchanged — same results, same highlighting. Queries returning
50 hits take 260-400 ms on that store.

What happens when you upgrade

First run rebuilds the index from scratch, because the storage format changed.
Expect a few minutes on a large session store (about 7 minutes for 6,000+
files); after that, refreshes are incremental as usual. The rebuild reclaims the
old file's disk space rather than leaving it allocated.

One small caveat: search matches on word stems, so a result that matched only
via a stem variant (searching running, text says runs) shows its snippet
without highlighting rather than highlighting the wrong word.

Verification

Full reindex of a 6,262-file / 877,439-line store, plus CLI search, show, and
export against the previously-crashing sessions, TUI launch, unit tests, and
typecheck.

v0.3.0

Capture workflow friction as it happens

dsx papercut add "what happened and the likely fix" appends a durable local record. Use dsx papercut list to filter by project, session, or source.

Review a transcript for missed papercuts

dsx papercut review <session> uses gpt-5.6-luna to extract concrete friction. Reviews are preview-only by default; pass --save to append candidates. Transcript input is treated as untrusted data and reviewer sessions cannot use tools.

Recover from repeated operational failures

The companion dsx skill now tells droids to search prior sessions after two failed attempts at the same tooling, environment, deployment, or operational problem, before inventing a third workaround.

Storage and configuration

Papercuts live at ~/.local/share/dsx/papercuts.jsonl. Override with DSX_PAPERCUTS_PATH; override the review model with DSX_PAPERCUT_MODEL.

v0.2.5

dsx v0.2.5

This release standardizes the bundled dsx Droid skill location for this repository.

What's changed

• Moved the companion skill from skills/dsx to .agents/skills/dsx.
• Updated the embedded dsx ask / dsx insights --deep cheatsheet imports to read from .agents/skills/dsx/references/*.md.
• Updated repository agent guidance to point maintainers at the new skill path.
• Bumped the CLI version to 0.2.5 because v0.2.4 is already published.

User impact

There are no CLI command or JSON contract changes. Existing commands keep working, and the local ~/.agents/skills/dsx symlink should now target the standardized .agents/skills/dsx repo path.

Verification

• bun test
• bunx tsc --noEmit
• bun run build
• bun run compile
• ./dist/dsx-linux-x64 --no-refresh list -n 2
• GitHub release workflow completed and published linux/darwin x64/arm64 assets.

v0.2.4

dsx v0.2.4: Stats TUI top-bar readability patch

This patch fixes the Stats TUI state display so shortcut-driven changes are visible as text, not only as terminal color styling.

What changed

• The selected Stats dimension now renders with explicit brackets, for example [model], [project], [day], and [day-model].
• Project and model filters now render as text chips when not editing, instead of staying inside a narrow input viewport.
• Long filter values are easier to read after submitting, which makes p and m state changes clear.

Why this matters

The v0.2.3 analytics release added several powerful Stats TUI controls (w, v, a, p, m, tab), but the selected dimension depended on color-only highlighting. That made the top bar feel static in some terminals and made tctl snapshots weaker as verification evidence.

Verified with tctl

The patch was verified with a recorded tctl run against the compiled binary, asserting all of these state transitions:

• w: all → 7d → 30d → 90d → all
• v: credits → totalTokens → inputTokens
• a: main → all → main
• tab: [model] → [project] → [day] → [day-model]
• p: project filter shows droid-session-explorer
• m: model filter shows gpt

Also validated locally with:

bun test
bunx tsc --noEmit
bun run build
bun run compile
./dist/dsx-linux-x64 --version
./dist/dsx-linux-x64 --no-refresh list -n 1