thinkspace

Context-Aware Scratchpad

• Why: Context switching to Notion/Obsidian/Todoist kills focus.
• What: thinkspace note "todo: fix env var issue" — later: thinkspace search "env"

✨ Features

• 🏷️ Auto-tags every note with your project (Git repo or folder) and time buckets (YYYY, YYYY‑MM, YYYY‑MM‑DD).
• 🔎 Search by text, tags, project, or time window. Uses SQLite with FTS5 full-text indexes when available, otherwise runs compatible LIKE queries.
• 📦 Zero-config local store in your user data dir (e.g. ~/.local/share/thinkspace/notes.db).
• 🎨 Rich CLI output: readable tables, panels, and helpful highlighting.
• 🗑️ Safe deletes with per-note confirmation or an interactive picker.
• 🧰 Portable single dependency stack (Typer + Rich + Platformdirs).

🚀 Quickstart

pip install thinkspace
# or from source
pip install .

Add a note:

thinkspace note "todo: fix env var issue"

Search later:

thinkspace search "env"

List recent notes:

thinkspace list --limit 10

Filter by project:

thinkspace search "todo" --project my-repo

Show top tags:

thinkspace tags

Export to Markdown:

thinkspace export --out notes.md

Delete a note:

thinkspace delete 42

Clean up interactively:

thinkspace delete --interactive --limit 50

🧩 Commands

• note [TEXT] – Capture a note. Use --tag multiple times to add manual tags.
• search [QUERY] – Full‑text search with optional filters: --project, --since, --until, --limit.
• list – Show most recent notes.
• tags – Show top tags (auto & manual).
• db-path – Print the notes DB path.
• export – Export all notes (optionally filtered) to Markdown.
• delete [ID ...] – Remove one or more notes (prompts for confirmation unless --yes is provided, or open with --interactive to choose from a checklist).

🏗️ How it works

• On first run, Thinkspace creates a tiny SQLite DB at your user data directory.
• Notes are stored with fields: id, text, project, tags, created_at, path.
• If SQLite FTS5 (the built-in full-text search extension) is available, Thinkspace builds an FTS5 virtual table so queries tokenize text and return ranked matches instantly.
• On systems without FTS5 compiled in, Thinkspace falls back to standard SQL LIKE clauses—simple substring matching that works everywhere, though with slower lookups on large notebooks.

🧪 Testing

pip install -r requirements-dev.txt  # installs pytest & mypy
mypy src
pytest -q

🧹 Linting

pip install -r requirements-dev.txt  # installs ruff
ruff check .
ruff format .

📦 Publishing to PyPI

1. Update version in pyproject.toml.
2. Build:

   python -m build
   

3. Upload:

   python -m twine upload dist/*
   

⚡ uv workflow

Prefer using uv for speed and reproducibility.

# 1) Create and sync a local env (writes uv.lock)
uv sync

# 2) Run the CLI from the project env
uv run thinkspace note "hello from uv"

# 3) Format & lint
uv run ruff check --select I --fix
uv run ruff format

# 4) Type checking
uv run mypy src

# 5) Tests
uv run pytest -q

# 6) Build & publish
uv build --no-sources
uv publish  # set UV_PUBLISH_TOKEN with a PyPI token

Dev dependencies live in [dependency-groups] and are synced by default.