breadcrumbst 0.4.6__tar.gz

breadcrumbst-0.4.6/.gitignore

@@ -0,0 +1,17 @@
+.venv/
+.install-test/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+*.db
+*.db-shm
+*.db-wal
+graphify-out/
+build/
+dist/
+*.egg-info/
+.build-check/
+.test-tmp-*/
+/videos/
+/scripts/capture_video.py
+/scripts/capture_feature_tour.py

breadcrumbst-0.4.6/CHANGELOG.md

@@ -0,0 +1,193 @@
+# Changelog
+
+## 0.4.6 — PyPI distribution identity · 2026-10-25
+
+- Publish under `breadcrumbst` because PyPI rejects the original package name.
+  The product, Python imports, settings and main `breadcrumbs` command retain
+  their existing names. `breadcrumbst` is an additional command for direct uvx use.
+- Detect the new distribution's installed version before legacy metadata.
+- Configure the PyPI trusted-publisher target for the accepted project name.
+
+
+## 0.4.5 — Keep Latest pinned after layout changes · 2026-10-25
+
+- Keep the newest branch entry at the bottom after the terminal resizes or
+  wrapped rows change height. Older selected entries retain their selection.
+- Await screen mounting in the compact timeline regression check, so slow
+  Windows runners verify a mounted view instead of racing its construction.
+- Verify follow behavior through width changes as well as new observations.
+
+
+## 0.4.4 — Bread mark, clearer install, product demos · 2026-10-25
+
+- Add the supplied logo to the README, terminal header and welcome tour.
+  Terminal rendering uses bundled colour data and adds no runtime dependency.
+- Put the core timer/intention/trail pitch, demo GIF and isolated install first.
+  Explain native capture platform limits before users install.
+- Prepare authenticated PyPI publishing and concrete contributor issues.
+  Direct released-wheel installation remains available without Git.
+- Add a short README GIF using real intention, timer and branch captures.
+
+
+## 0.4.3 — Persistent sidebar and safer Windows updates · 2026-10-25
+
+- Keep activity details visible beside the branch list. Arrow keys or a click
+  immediately update the sidebar. Enter stays inline; Escape closes branches.
+  Remove the Ctrl+Enter activity popup.
+- Wait for running Windows launchers to close before pip changes packages. If
+  they remain open, stop safely with an actionable status and leave the app intact.
+- Back up the importable Breadcrumbs package and its metadata before updating,
+  restoring them if pip fails after uninstalling. Avoid forcibly reinstalling
+  every dependency on an application update.
+- Update the README and real UI captures to match the persistent sidebar.
+- Add regression coverage for a busy launcher and recovery after pip failure.
+
+
+## 0.4.2 — Current browser build, cleaner branch details · 2026-10-25
+
+- Fix the legacy unpacked-extension path left behind by the runtime rename:
+  installers, future updater helpers, and installed app startup refresh known
+  old extension folders. Pairing storage and Chrome preferences stay untouched.
+  A Chrome/Edge extension reload is still required to activate new files.
+- Add `breadcrumbs browser repair`, loaded extension version reporting,
+  app/extension version display, and an old-build notice in Config.
+- Preserve capture diagnostic messages in activity records so new Unknown
+  visits can explain missing reports or an old extension instead of only
+  saying that the window was captured.
+- Remove artwork attribution strings from activity details. Attribution remains
+  in the bundled notices and documentation.
+- Open clicked/Enter-selected activity in a sidebar, with a smaller bounded
+  branch card. Escape collapses details; Ctrl+Enter keeps the full-screen option.
+  Compact details remain readable at 80×24.
+
+## 0.4.1 — Keep the session, follow the trail · 2026-10-25
+
+### Fixed
+
+- Branches opens at the latest activity and keeps following new visits and
+  duration updates without rebuilding the list. Inspecting an older visit
+  preserves selection; End or Latest returns to the newest activity.
+- A session keeps its name across work blocks, breaks, and app restarts.
+  Ctrl+N or an explicitly edited name starts a different session. Block
+  checkpoints, reflections, and elapsed times remain separate.
+- The timer bridge starts for untracked running blocks too, so the paired
+  extension can detect/control the current block without enabling capture.
+  Port conflicts retry after another app instance closes.
+- Browser title matching handles alternate dash glyphs and browser/profile
+  suffixes, while ambiguous profiles still remain unverified.
+
+### Added
+
+- Click/Enter opens a full, scrollable activity detail screen with logo,
+  timestamps, title/domain, capture precision, and annotation keys at all sizes.
+- Short/long breaks appear in the session's branch timeline as timer spans.
+  Paused/offline gaps are excluded; app/browser capture stays off during breaks.
+- Explicit terminal-title program hints and bundled logos for Claude Code,
+  Codex, Python, Node.js, Git, and Neovim. Hints affect presentation only;
+  process-verified agent attribution and scope classification stay separate.
+- The extension shows its actual last reported tab/domain. Disabled title
+  sharing immediately redacts its preview; stopped, stale, private/internal,
+  or unfocused context clears the preview. Awake heartbeats run every two seconds.
+- Clearer browser verification notices, contributor guidance, updated project
+  positioning, and practical launch-channel suggestions in `docs/SHARING.md`.
+
+### Data and updating
+
+- Existing blocks/history are retained. New blocks store a persistent session
+  root and export its readable session name. Older unrelated blocks are not
+  retroactively joined into a guessed session.
+- Reload the unpacked extension after updating so Chrome/Edge loads v0.4.1.
+  Re-pair if its saved address/token no longer matches Config → Browser connection.
+
+## 0.4.0 — Breadcrumbs · 2026-10-25
+
+### Renamed
+
+- Tlock is now Breadcrumbs. The app, Python package, primary command, browser
+  extension, installer, updater, and repository use the new name.
+- `breadcrumbs` is the primary command. `tlock` remains a compatibility entry.
+- Existing Tlock data, saved sessions, preferences, and environment overrides
+  remain supported. No history is moved or deleted.
+
+### Added
+
+- A 12-page first-launch feature tour with Back/Next, keyboard navigation,
+  scrolling, Skip, and replay using `?` from the ready or paused timer.
+  Tour dismissal is remembered. Saved-session recovery takes priority;
+  the tour never starts capture or a timer and blocks underlying app shortcuts.
+- A hands-on onboarding guide and a README organized around practical tasks,
+  with feature explanations, examples, settings, and a keyboard reference.
+- Opt-in app/browser/terminal-agent scope before starting a block, with reuse
+  and untracked options. Scope can also change within an existing session.
+- Durable running spans and a Git-style activity trail with colored app nodes,
+  departures, returns, source precision, and user annotations.
+- A small animated, nameless trail beside intentions and a live context bar.
+- Bundled Chrome/Edge extension with local pairing, exact URL selection,
+  current-session pickup, theme matching, and Start/Pause/Resume/Finish controls.
+- Browser connection setup in Config, separate from scope selection.
+- Verified CLI agent markers for supported terminals; background processes do
+  not count as foreground agent activity.
+- Explicit activity export, including per-span scope snapshots.
+- Local-date work totals and clear long-break round progress, alongside named
+  recovery, intentions, task carryover, reflections, and configurable reading.
+
+### Fixed
+
+- Missing tab/agent verification reports Unknown rather than a false deviation.
+- Scope survives recovery, including edits made while paused. Offline time is
+  not joined into activity spans; late results from old spans are discarded.
+- Long-break progress counts only full Focus completions and resets after a
+  full long break. The UI states the remaining focus blocks directly.
+- Extension status is independent of tab capture and stale browser requests.
+  A stalled response body is bounded, older replies cannot replace newer state,
+  and stale/double-clicked timer commands cannot target a changed session.
+- Unverified browser fallback discards window titles, including potential
+  private-browser titles. IPv6 domain literals are validated and normalized.
+- Empty trail selections clear the previous visit's logo and details.
+- Historical visit explanations use that running span's scope snapshot,
+  rather than the session's most recently edited scope.
+
+### Browser reliability and privacy
+
+- Authenticated loopback bridge with bounded extension origins and payloads.
+- Exact-page hashes retain query identity without transmitting raw URL paths
+  or queries. Titles are separately configurable; private/internal tabs are
+  excluded by the extension. Hashes are not anonymous identifiers.
+- Stopping sharing does not disable timer status or controls. Reopening the
+  popup discovers an already-running TUI session without waiting for tab reads.
+- Timer commands bind to session identity/revision. Duplicate Finish commands,
+  stale popups, pre-restart revisions, and changed-session replies cannot
+  silently retarget a block. Busy dialogs temporarily disable remote controls.
+- Slow response bodies time out, older results cannot replace newer status,
+  and failed tab reads do not discard a healthy countdown.
+
+### Validation
+
+- Windows Python regression suite, dependency-free extension tests, and a
+  real isolated Chromium/extension/TUI/SQLite integration scenario.
+- Installer/reinstall, paths with spaces, legacy-data recovery, installed-wheel
+  commands/resources, and package metadata checks.
+- CI covers Windows/Ubuntu on Python 3.11/3.14, browser integration, extension
+  tests, and package installation. See `docs/QA-v0.4.0.md` for audit scope.
+
+### Upgrade notes
+
+- Close Tlock before upgrading. Use `breadcrumbs` afterward; old command aliases
+  remain available for transition.
+- Load the extension from the new path printed by `breadcrumbs browser path`
+  and pair it through Config. The old unpacked extension points to the old folder.
+- Windows and Linux/X11 app capture are supported. Wayland/macOS native app
+  capture and general editor-integrated terminal attribution remain limitations.
+
+## 0.3.0 — Tlock
+
+- Recoverable named sessions, scope-change decisions, rotating reading cards,
+  sound previews, saved intentions, and session reflections.
+
+## 0.2.0 — Tlock
+
+- A cleaner timer workflow, simplified companion, task carryover, and local export.
+
+## 0.1.0 — Tlock
+
+- Initial public release.

breadcrumbst-0.4.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Breadcrumbs contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

breadcrumbst-0.4.6/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.5
+Name: breadcrumbst
+Version: 0.4.6
+Summary: A terminal-first productivity timer that keeps your goals in view and helps you understand where you trail off.
+Project-URL: Homepage, https://github.com/SaroashDS/Breadcrumbs
+Project-URL: Repository, https://github.com/SaroashDS/Breadcrumbs
+Project-URL: Issues, https://github.com/SaroashDS/Breadcrumbs/issues
+Project-URL: Changelog, https://github.com/SaroashDS/Breadcrumbs/releases
+License: MIT License
+        
+        Copyright (c) 2026 Breadcrumbs contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: pomodoro,productivity,terminal,timer,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Office/Business :: Scheduling
+Requires-Python: >=3.11
+Requires-Dist: textual<2.0,>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/SaroashDS/Breadcrumbs/main/docs/assets/breadcrumbs-mark-transparent.png" width="220" alt="Breadcrumbs bread-and-trail mark" />
+</p>
+
+<h1 align="center">Breadcrumbs</h1>
+
+<p align="center">
+  <strong>A terminal-first productivity timer that helps you understand where you trail off.</strong><br />
+  Set an intention, stay with your goal, and leave yourself a trail back.
+</p>
+
+```sh
+pipx install https://github.com/SaroashDS/Breadcrumbs/releases/download/v0.4.6/breadcrumbst-0.4.6-py3-none-any.whl
+```
+
+Then run `breadcrumbs`. **Python 3.11+** and [pipx](https://pipx.pypa.io/stable/installation/) are required.
+This installs the released wheel in an isolated environment; no shell script or Git clone.
+The wheel installs directly from the GitHub release. [Other install options](docs/INSTALL.md)
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/SaroashDS/Breadcrumbs/main/docs/assets/breadcrumbs-demo.gif" width="900" alt="Set an intention, start, and see the branch trail" />
+</p>
+
+**Platform support:** timer + paired Chrome/Edge work on Windows, Linux and macOS.
+Native foreground-app capture supports **Windows and Linux/X11 only**.
+macOS and Wayland native capture are not implemented. [Details](docs/ACTIVITY.md)
+
+[Installation options](docs/INSTALL.md) · [First session](docs/ONBOARDING.md) ·
+[Full guide + keys](docs/USAGE.md) · [Browser extension](docs/BROWSER_EXTENSION.md) ·
+[Latest release](https://github.com/SaroashDS/Breadcrumbs/releases/latest)
+
+## Try one block
+
+1. Press `E` and write one small intention. `Ctrl+B` adds a task; `F2` checks it off.
+2. Press `Escape`, choose a duration, then `Space` to start.
+3. Choose your working scope, reuse it, or continue without tracking.
+4. Switch between your work and other apps. Press `B` to inspect the trail.
+5. Finish the block, save a reflection, and review it with `H`.
+
+The feature tour opens on first launch. Replay it with `?` while ready or paused.
+It never enables capture or starts the timer. [Hands-on onboarding](docs/ONBOARDING.md)
+
+## What it does
+
+| Need | Breadcrumbs feature |
+| --- | --- |
+| Keep the next step in view | Intentions and a persistent Markdown checklist |
+| Work to your own rhythm | Focus/short/long presets, custom timers, pause and resume |
+| Understand a detour | App/browser scope, Git-style branches, useful-detour annotations |
+| Inspect what happened | Activity details stay beside the trail and follow selection |
+| Stop and return later | Named sessions, checkpoints and paused recovery |
+| Learn from a block | Reflections, optional focus rating, history and JSON export |
+| Stay in the browser | Optional extension countdown, Start/Pause/Resume and confirmed Finish |
+
+Sessions keep their name across work blocks, breaks and restarts. `Ctrl+N`
+explicitly starts a new session. Breaks appear in the same trail without capture.
+`End` or **Latest** follows the newest activity; selecting an older visit preserves it.
+
+**In scope** matches your choices. **Supporting** marks a useful detour.
+**Deviation** is outside scope and can still be useful work. **Unknown** means
+the context was not verified. `A`, `S`, and `V` annotate a selected visit.
+
+Optional preferences include three themes, sound previews, a companion and
+reading cards. They stay out of the core timer workflow. [Every setting](docs/USAGE.md#settings)
+
+## Browser and terminal context
+
+Open **Config (`C`) → Browser connection** for the extension folder and local
+pairing token. Load the unpacked extension in Chrome/Edge, pair, then select
+apps, domains or exact pages in scope. Page matching includes query parameters.
+Sharing tab context and controlling the timer are separate controls.
+
+Selected Claude Code/Codex CLI activity uses a verified foreground terminal
+marker. A running background process alone does not count as focus. Pinned
+titles, multiplexers and editor panes may prevent verification; unsupported
+context stays Unknown. [Setup and limitations](docs/ACTIVITY.md)
+
+## Install, update and recover
+
+Prefer a one-off run with [uv](https://docs.astral.sh/uv/getting-started/installation/)?
+
+```sh
+uvx --from https://github.com/SaroashDS/Breadcrumbs/releases/download/v0.4.5/breadcrumbs-0.4.5-py3-none-any.whl breadcrumbs
+```
+
+[All installation options](docs/INSTALL.md) cover pipx, uvx, ordinary virtual
+environments, the optional Windows installer and source development.
+Use the latest released wheel URL when updating a wheel-based installation.
+
+```sh
+breadcrumbs sessions
+breadcrumbs --resume my-session
+breadcrumbs export --output sessions.json
+breadcrumbs export --activity --output activity.json
+```
+
+Recovery opens paused. Time while the app was closed is excluded. `Q` saves and
+quits; `F` offers Keep working, Finish early or End session.
+[Full keyboard reference](docs/USAGE.md#keyboard-reference)
+
+## Why build this?
+
+Too many productivity tools turn a simple need into another subscription, an
+unnecessary AI agent, or a system that takes more work to manage than it saves.
+
+Sometimes you just want a timer, goals you can keep in view, and an understanding
+of where your attention trails off. Breadcrumbs is for developers moving between
+editors, terminals and documentation, and anyone who wants a simpler way to work.
+
+Write what you intend to do. Notice useful detours. Find your way back.
+
+## Your data
+
+Sessions and preferences stay locally in `~/.breadcrumbs`. `BREADCRUMBS_HOME`
+chooses another folder. Existing Tlock data and its compatibility command remain usable in place.
+
+Tracking is optional and runs only during running focus/custom blocks. Pauses,
+breaks and quitting stop it. Normal export omits activity; `--activity` adds it.
+The extension sends domains and URL hashes, not raw paths or queries. Titles
+are optional. Hashes identify pages and are not anonymous. Private/internal
+tabs are excluded by the extension; app-only capture cannot reliably identify
+private windows. [Privacy and capture details](docs/ACTIVITY.md)
+
+## Contributors welcome
+
+Help make everyday work easier: small features, integrations, useful workflows,
+bug fixes and clearer docs are welcome. Keep the timer useful on its own and
+integrations optional.
+
+Start with a concrete [good first issue](https://github.com/SaroashDS/Breadcrumbs/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22)
+or a [help wanted task](https://github.com/SaroashDS/Breadcrumbs/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22help%20wanted%22).
+The [roadmap tickets](docs/CONTRIBUTOR_TASKS.md) cover weekly review, CSV export,
+editor context and broader desktop support. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+```sh
+python -m pip install -e ".[dev]"
+python -m pytest -q
+```
+
+[Changelog](CHANGELOG.md) · [QA](docs/TESTING.md) ·
+[Architecture](docs/FOCUS_BRANCHES.md) · [Brand credits](docs/BRANDS.md) ·
+[Publishing setup](docs/PUBLISHING.md)
+
+MIT licensed. Brand marks belong to their respective owners.

breadcrumbst-0.4.6/README.md

@@ -0,0 +1,144 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/SaroashDS/Breadcrumbs/main/docs/assets/breadcrumbs-mark-transparent.png" width="220" alt="Breadcrumbs bread-and-trail mark" />
+</p>
+
+<h1 align="center">Breadcrumbs</h1>
+
+<p align="center">
+  <strong>A terminal-first productivity timer that helps you understand where you trail off.</strong><br />
+  Set an intention, stay with your goal, and leave yourself a trail back.
+</p>
+
+```sh
+pipx install https://github.com/SaroashDS/Breadcrumbs/releases/download/v0.4.6/breadcrumbst-0.4.6-py3-none-any.whl
+```
+
+Then run `breadcrumbs`. **Python 3.11+** and [pipx](https://pipx.pypa.io/stable/installation/) are required.
+This installs the released wheel in an isolated environment; no shell script or Git clone.
+The wheel installs directly from the GitHub release. [Other install options](docs/INSTALL.md)
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/SaroashDS/Breadcrumbs/main/docs/assets/breadcrumbs-demo.gif" width="900" alt="Set an intention, start, and see the branch trail" />
+</p>
+
+**Platform support:** timer + paired Chrome/Edge work on Windows, Linux and macOS.
+Native foreground-app capture supports **Windows and Linux/X11 only**.
+macOS and Wayland native capture are not implemented. [Details](docs/ACTIVITY.md)
+
+[Installation options](docs/INSTALL.md) · [First session](docs/ONBOARDING.md) ·
+[Full guide + keys](docs/USAGE.md) · [Browser extension](docs/BROWSER_EXTENSION.md) ·
+[Latest release](https://github.com/SaroashDS/Breadcrumbs/releases/latest)
+
+## Try one block
+
+1. Press `E` and write one small intention. `Ctrl+B` adds a task; `F2` checks it off.
+2. Press `Escape`, choose a duration, then `Space` to start.
+3. Choose your working scope, reuse it, or continue without tracking.
+4. Switch between your work and other apps. Press `B` to inspect the trail.
+5. Finish the block, save a reflection, and review it with `H`.
+
+The feature tour opens on first launch. Replay it with `?` while ready or paused.
+It never enables capture or starts the timer. [Hands-on onboarding](docs/ONBOARDING.md)
+
+## What it does
+
+| Need | Breadcrumbs feature |
+| --- | --- |
+| Keep the next step in view | Intentions and a persistent Markdown checklist |
+| Work to your own rhythm | Focus/short/long presets, custom timers, pause and resume |
+| Understand a detour | App/browser scope, Git-style branches, useful-detour annotations |
+| Inspect what happened | Activity details stay beside the trail and follow selection |
+| Stop and return later | Named sessions, checkpoints and paused recovery |
+| Learn from a block | Reflections, optional focus rating, history and JSON export |
+| Stay in the browser | Optional extension countdown, Start/Pause/Resume and confirmed Finish |
+
+Sessions keep their name across work blocks, breaks and restarts. `Ctrl+N`
+explicitly starts a new session. Breaks appear in the same trail without capture.
+`End` or **Latest** follows the newest activity; selecting an older visit preserves it.
+
+**In scope** matches your choices. **Supporting** marks a useful detour.
+**Deviation** is outside scope and can still be useful work. **Unknown** means
+the context was not verified. `A`, `S`, and `V` annotate a selected visit.
+
+Optional preferences include three themes, sound previews, a companion and
+reading cards. They stay out of the core timer workflow. [Every setting](docs/USAGE.md#settings)
+
+## Browser and terminal context
+
+Open **Config (`C`) → Browser connection** for the extension folder and local
+pairing token. Load the unpacked extension in Chrome/Edge, pair, then select
+apps, domains or exact pages in scope. Page matching includes query parameters.
+Sharing tab context and controlling the timer are separate controls.
+
+Selected Claude Code/Codex CLI activity uses a verified foreground terminal
+marker. A running background process alone does not count as focus. Pinned
+titles, multiplexers and editor panes may prevent verification; unsupported
+context stays Unknown. [Setup and limitations](docs/ACTIVITY.md)
+
+## Install, update and recover
+
+Prefer a one-off run with [uv](https://docs.astral.sh/uv/getting-started/installation/)?
+
+```sh
+uvx --from https://github.com/SaroashDS/Breadcrumbs/releases/download/v0.4.5/breadcrumbs-0.4.5-py3-none-any.whl breadcrumbs
+```
+
+[All installation options](docs/INSTALL.md) cover pipx, uvx, ordinary virtual
+environments, the optional Windows installer and source development.
+Use the latest released wheel URL when updating a wheel-based installation.
+
+```sh
+breadcrumbs sessions
+breadcrumbs --resume my-session
+breadcrumbs export --output sessions.json
+breadcrumbs export --activity --output activity.json
+```
+
+Recovery opens paused. Time while the app was closed is excluded. `Q` saves and
+quits; `F` offers Keep working, Finish early or End session.
+[Full keyboard reference](docs/USAGE.md#keyboard-reference)
+
+## Why build this?
+
+Too many productivity tools turn a simple need into another subscription, an
+unnecessary AI agent, or a system that takes more work to manage than it saves.
+
+Sometimes you just want a timer, goals you can keep in view, and an understanding
+of where your attention trails off. Breadcrumbs is for developers moving between
+editors, terminals and documentation, and anyone who wants a simpler way to work.
+
+Write what you intend to do. Notice useful detours. Find your way back.
+
+## Your data
+
+Sessions and preferences stay locally in `~/.breadcrumbs`. `BREADCRUMBS_HOME`
+chooses another folder. Existing Tlock data and its compatibility command remain usable in place.
+
+Tracking is optional and runs only during running focus/custom blocks. Pauses,
+breaks and quitting stop it. Normal export omits activity; `--activity` adds it.
+The extension sends domains and URL hashes, not raw paths or queries. Titles
+are optional. Hashes identify pages and are not anonymous. Private/internal
+tabs are excluded by the extension; app-only capture cannot reliably identify
+private windows. [Privacy and capture details](docs/ACTIVITY.md)
+
+## Contributors welcome
+
+Help make everyday work easier: small features, integrations, useful workflows,
+bug fixes and clearer docs are welcome. Keep the timer useful on its own and
+integrations optional.
+
+Start with a concrete [good first issue](https://github.com/SaroashDS/Breadcrumbs/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22)
+or a [help wanted task](https://github.com/SaroashDS/Breadcrumbs/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22help%20wanted%22).
+The [roadmap tickets](docs/CONTRIBUTOR_TASKS.md) cover weekly review, CSV export,
+editor context and broader desktop support. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+```sh
+python -m pip install -e ".[dev]"
+python -m pytest -q
+```
+
+[Changelog](CHANGELOG.md) · [QA](docs/TESTING.md) ·
+[Architecture](docs/FOCUS_BRANCHES.md) · [Brand credits](docs/BRANDS.md) ·
+[Publishing setup](docs/PUBLISHING.md)
+
+MIT licensed. Brand marks belong to their respective owners.

breadcrumbst-0.4.6/breadcrumbs/__init__.py

@@ -0,0 +1,3 @@
+"""Breadcrumbs terminal focus companion."""
+
+__version__ = "0.4.6"