howzo 0.1.0__tar.gz

howzo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sohail
+
+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.

howzo-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: howzo
+Version: 0.1.0
+Summary: Knows your machine: ask 'how do I X' in English, get the installed tool + a runnable command.
+Author: Sohail
+License: MIT
+Project-URL: Homepage, https://github.com/sohailchd/howzo
+Project-URL: Repository, https://github.com/sohailchd/howzo
+Keywords: cli,shell,commands,developer-tools,discovery,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# howzo
+
+**Knows your machine.** Ask "how do I X" in English → get the tool that is actually installed on *this* machine, plus a runnable command.
+
+howzo is a free, local, **zero-model** command router. It indexes the tools that are actually installed on your box — brew, npm, pipx, uv, system binaries, your own scripts — and answers plain-English questions by matching against that inventory. No accounts, no API keys, no telemetry, and no network access when answering.
+
+## Why
+
+Generic command helpers (ShellGPT, mang.sh, Atuin) index a static corpus of popular commands. howzo indexes *your machine* instead — the exact tools, versions, and help text you actually have. If it's installed, howzo knows it; if it isn't, howzo doesn't waste your time suggesting it.
+
+## Install
+
+Requires Python 3.9+. Runtime dependencies: **none** (stdlib only).
+
+### macOS / Linux
+
+```sh
+pipx install howzo        # or: uv tool install howzo
+```
+
+macOS also has a Homebrew formula (tap required):
+
+```sh
+brew tap sohailchd/howzo && brew install howzo
+```
+
+### Windows
+
+```powershell
+py -m pipx install howzo  # or: uv tool install howzo
+```
+
+### From source
+
+```sh
+git clone https://github.com/sohailchd/howzo.git
+pipx install --editable howzo    # or: uv tool install --editable howzo
+```
+
+### First run
+
+```sh
+howzo scan     # one-time: build your machine's inventory (~2-3 min)
+```
+
+Rescans are safe: captured help text, `when_to_use` notes, custom entries, and mined npx packages are preserved.
+
+## Usage
+
+```console
+$ howzo "how do I rotate a pdf"
+pdfq  (pipx, 1.0)
+  rotate and convert pdf files
+
+$ howzo whatis crwl
+crwl  (pipx, 0.3.1)
+  (binary of pipx crawl4ai)
+
+$ howzo kill a process on port 8080
+lsof  (brew, 9.9)
+  list open files and network connections
+```
+
+### Commands
+
+| Command | What it does |
+|---|---|
+| `howzo <query>` | Ask in plain English (implicit `ask`) |
+| `howzo scan [--deep]` | Rebuild inventory; `--deep` also captures `--help` text for every tool |
+| `howzo ask "query"` | Same as `<query>` |
+| `howzo whatis <tool>` | Reverse lookup: what is this tool for? |
+| `howzo deep <tool>` | Capture `--help`/man for one tool on demand |
+| `howzo add <name> "desc"` | Register a tool the scanner can't see (internal CLIs, aliases) |
+| `howzo list [--source S]` | Browse the inventory |
+| `howzo mcp` | Run as a stdio MCP server |
+| `howzo db` | Show the database path |
+
+## What it indexes
+
+| Source | What's indexed |
+|---|---|
+| brew | formulae + versions + descriptions (`brew info`) |
+| npm | global packages + their installed binaries |
+| pipx | packages + the binaries they provide (e.g. `crwl` → crawl4ai) |
+| uv | `uv tool` installs |
+| scripts | executables in `~/bin` and `~/.local/bin` (one-liner from the script header) |
+| system (Unix) | `/usr/bin` + `/usr/sbin` + `/usr/local/bin` binaries, described via man pages |
+| path (Windows) | executables found on `PATH` (System32, Program Files, …) |
+| npx | `npx`/`bunx`/`pnpm dlx` packages mined from your shell history (zsh, bash, PowerShell) |
+| custom | anything you add with `howzo add` |
+
+A typical machine indexes ~1,200 tools.
+
+## How it works
+
+- **SQLite + FTS5** at `~/.local/share/howzo/howzo.db` (Windows: `%LOCALAPPDATA%\howzo`), one row per tool: name, source, version, oneliner, when-to-use, help excerpt.
+- **Match = BM25 + word-boundary token-coverage re-rank** in Python. No models, no embeddings — `kill` never matches `skill`, `port` never matches `report`.
+- **~20–30 MB RAM**, and answering is fully offline. The network is only touched while scanning, to fetch package descriptions from npm/PyPI.
+- Set `HOWZO_DB=/some/dir` to relocate the database (also how the test suite isolates itself).
+
+## MCP
+
+howzo runs as a stdio MCP server exposing `howzo_ask`, `howzo_whatis`, and `howzo_list`:
+
+```json
+{
+  "mcpServers": {
+    "howzo": { "command": "howzo", "args": ["mcp"] }
+  }
+}
+```
+
+## Development
+
+```sh
+git clone https://github.com/sohailchd/howzo.git && cd howzo
+uv venv .venv
+VIRTUAL_ENV=$PWD/.venv uv pip install -e ".[dev]"   # or: pip install -e ".[dev]"
+pytest
+```
+
+Layout:
+
+```
+src/howzo/
+├── cli.py        # entry point + dispatch
+├── commands.py   # scan / ask / whatis / deep / add / list
+├── config.py     # platform constants, DB path (HOWZO_DB override)
+├── proc.py       # subprocess helpers (cross-platform)
+├── db.py         # SQLite + FTS5 schema, upsert
+├── match.py      # tokenization, FTS query, BM25 + coverage re-rank
+├── render.py     # output formatting
+├── helptext.py   # man pages, --help capture
+├── mcp.py        # MCP stdio server
+└── scan/         # one module per source: brew, npm, pipx, uv, scripts, system, path, npx
+tests/            # pytest suite (runs against temp DBs, no network)
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

howzo-0.1.0/README.md

@@ -0,0 +1,141 @@
+# howzo
+
+**Knows your machine.** Ask "how do I X" in English → get the tool that is actually installed on *this* machine, plus a runnable command.
+
+howzo is a free, local, **zero-model** command router. It indexes the tools that are actually installed on your box — brew, npm, pipx, uv, system binaries, your own scripts — and answers plain-English questions by matching against that inventory. No accounts, no API keys, no telemetry, and no network access when answering.
+
+## Why
+
+Generic command helpers (ShellGPT, mang.sh, Atuin) index a static corpus of popular commands. howzo indexes *your machine* instead — the exact tools, versions, and help text you actually have. If it's installed, howzo knows it; if it isn't, howzo doesn't waste your time suggesting it.
+
+## Install
+
+Requires Python 3.9+. Runtime dependencies: **none** (stdlib only).
+
+### macOS / Linux
+
+```sh
+pipx install howzo        # or: uv tool install howzo
+```
+
+macOS also has a Homebrew formula (tap required):
+
+```sh
+brew tap sohailchd/howzo && brew install howzo
+```
+
+### Windows
+
+```powershell
+py -m pipx install howzo  # or: uv tool install howzo
+```
+
+### From source
+
+```sh
+git clone https://github.com/sohailchd/howzo.git
+pipx install --editable howzo    # or: uv tool install --editable howzo
+```
+
+### First run
+
+```sh
+howzo scan     # one-time: build your machine's inventory (~2-3 min)
+```
+
+Rescans are safe: captured help text, `when_to_use` notes, custom entries, and mined npx packages are preserved.
+
+## Usage
+
+```console
+$ howzo "how do I rotate a pdf"
+pdfq  (pipx, 1.0)
+  rotate and convert pdf files
+
+$ howzo whatis crwl
+crwl  (pipx, 0.3.1)
+  (binary of pipx crawl4ai)
+
+$ howzo kill a process on port 8080
+lsof  (brew, 9.9)
+  list open files and network connections
+```
+
+### Commands
+
+| Command | What it does |
+|---|---|
+| `howzo <query>` | Ask in plain English (implicit `ask`) |
+| `howzo scan [--deep]` | Rebuild inventory; `--deep` also captures `--help` text for every tool |
+| `howzo ask "query"` | Same as `<query>` |
+| `howzo whatis <tool>` | Reverse lookup: what is this tool for? |
+| `howzo deep <tool>` | Capture `--help`/man for one tool on demand |
+| `howzo add <name> "desc"` | Register a tool the scanner can't see (internal CLIs, aliases) |
+| `howzo list [--source S]` | Browse the inventory |
+| `howzo mcp` | Run as a stdio MCP server |
+| `howzo db` | Show the database path |
+
+## What it indexes
+
+| Source | What's indexed |
+|---|---|
+| brew | formulae + versions + descriptions (`brew info`) |
+| npm | global packages + their installed binaries |
+| pipx | packages + the binaries they provide (e.g. `crwl` → crawl4ai) |
+| uv | `uv tool` installs |
+| scripts | executables in `~/bin` and `~/.local/bin` (one-liner from the script header) |
+| system (Unix) | `/usr/bin` + `/usr/sbin` + `/usr/local/bin` binaries, described via man pages |
+| path (Windows) | executables found on `PATH` (System32, Program Files, …) |
+| npx | `npx`/`bunx`/`pnpm dlx` packages mined from your shell history (zsh, bash, PowerShell) |
+| custom | anything you add with `howzo add` |
+
+A typical machine indexes ~1,200 tools.
+
+## How it works
+
+- **SQLite + FTS5** at `~/.local/share/howzo/howzo.db` (Windows: `%LOCALAPPDATA%\howzo`), one row per tool: name, source, version, oneliner, when-to-use, help excerpt.
+- **Match = BM25 + word-boundary token-coverage re-rank** in Python. No models, no embeddings — `kill` never matches `skill`, `port` never matches `report`.
+- **~20–30 MB RAM**, and answering is fully offline. The network is only touched while scanning, to fetch package descriptions from npm/PyPI.
+- Set `HOWZO_DB=/some/dir` to relocate the database (also how the test suite isolates itself).
+
+## MCP
+
+howzo runs as a stdio MCP server exposing `howzo_ask`, `howzo_whatis`, and `howzo_list`:
+
+```json
+{
+  "mcpServers": {
+    "howzo": { "command": "howzo", "args": ["mcp"] }
+  }
+}
+```
+
+## Development
+
+```sh
+git clone https://github.com/sohailchd/howzo.git && cd howzo
+uv venv .venv
+VIRTUAL_ENV=$PWD/.venv uv pip install -e ".[dev]"   # or: pip install -e ".[dev]"
+pytest
+```
+
+Layout:
+
+```
+src/howzo/
+├── cli.py        # entry point + dispatch
+├── commands.py   # scan / ask / whatis / deep / add / list
+├── config.py     # platform constants, DB path (HOWZO_DB override)
+├── proc.py       # subprocess helpers (cross-platform)
+├── db.py         # SQLite + FTS5 schema, upsert
+├── match.py      # tokenization, FTS query, BM25 + coverage re-rank
+├── render.py     # output formatting
+├── helptext.py   # man pages, --help capture
+├── mcp.py        # MCP stdio server
+└── scan/         # one module per source: brew, npm, pipx, uv, scripts, system, path, npx
+tests/            # pytest suite (runs against temp DBs, no network)
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

howzo-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "howzo"
+version = "0.1.0"
+description = "Knows your machine: ask 'how do I X' in English, get the installed tool + a runnable command."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Sohail" }]
+keywords = ["cli", "shell", "commands", "developer-tools", "discovery", "mcp"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+# Update after the GitHub repo is created
+Homepage = "https://github.com/sohailchd/howzo"
+Repository = "https://github.com/sohailchd/howzo"
+
+[project.scripts]
+howzo = "howzo.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

howzo-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

howzo-0.1.0/src/howzo/__init__.py

@@ -0,0 +1,7 @@
+"""howzo - knows your machine.
+
+Ask "how do I X" in English and get the tool that is actually installed on
+this machine, plus a usage hint. Stdlib only, zero models, fully local.
+"""
+
+__version__ = "0.1.0"

howzo-0.1.0/src/howzo/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m howzo` entry point."""
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main() or 0)

howzo-0.1.0/src/howzo/cli.py

@@ -0,0 +1,48 @@
+"""howzo command-line entry point."""
+import sys
+
+from . import commands
+from .config import db_path
+from .mcp import cmd_mcp
+
+USAGE = """howzo - knows your machine. Ask "how do I X" in English; get the installed tool + command.
+
+Commands:
+  howzo <query>          just type your question (same as ask)
+  howzo scan [--deep]    rebuild inventory (brew/npm/pipx/uv/scripts/system). --deep also captures --help
+  howzo ask "query"
+  howzo whatis <tool>
+  howzo deep <tool>      capture --help for one tool
+  howzo add <name> "desc"  register a tool the scanner can't see (internal CLIs, npx aliases)
+  howzo list [--source S]
+  howzo mcp              run as a stdio MCP server (exposes howzo_ask / howzo_whatis / howzo_list)
+  howzo db               show database path
+
+Stdlib only, zero models, fully local. Works on macOS, Linux, and Windows."""
+
+
+def main(argv=None):
+    args = list(sys.argv[1:] if argv is None else argv)
+    if not args:
+        print(USAGE)
+        return 1
+    cmd, rest = args[0], args[1:]
+    if cmd == "scan":
+        return commands.cmd_scan(rest)
+    if cmd == "ask":
+        return commands.cmd_ask(rest)
+    if cmd == "whatis":
+        return commands.cmd_whatis(rest)
+    if cmd == "deep":
+        return commands.cmd_deep(rest)
+    if cmd == "add":
+        return commands.cmd_add(rest)
+    if cmd == "list" and (not rest or rest[0].startswith("-")):
+        return commands.cmd_list(rest)
+    if cmd == "mcp":
+        return cmd_mcp(rest)
+    if cmd == "db":
+        print(db_path())
+        return 0
+    # implicit ask: howzo <query> == howzo ask <query>
+    return commands.cmd_ask(args)

howzo-0.1.0/src/howzo/commands.py

@@ -0,0 +1,180 @@
+"""CLI command handlers (scan / ask / whatis / deep / add / list)."""
+import os
+import sqlite3
+import time
+
+from . import config
+from .db import db, upsert
+from .helptext import capture_help
+from .match import coverage, fts_query, find_by_name, has_word, query_tokens, rank_rows
+from .render import render_tool
+from .scan import scanners
+
+
+def cmd_scan(args):
+    c = db()
+    try:
+        # preserve on-demand captured help + enrichments across rescans
+        keep = {r["name"]: (r["help_excerpt"], r["help_captured_at"], r["when_to_use"])
+                for r in c.execute("SELECT name, help_excerpt, help_captured_at, when_to_use FROM tools")}
+        custom_rows = {r["name"]: (r["source"], r["version"], r["path"], r["oneliner"],
+                                   r["when_to_use"], r["help_excerpt"], r["help_captured_at"])
+                       for r in c.execute("SELECT * FROM tools WHERE source IN ('custom','npx')")}
+        c.execute("DELETE FROM tools")
+    except sqlite3.DatabaseError:
+        print("  warning: db corrupted, rebuilding")
+        d = config.db_dir()
+        for f in os.listdir(d):
+            if f.startswith("howzo.db"):
+                os.remove(os.path.join(d, f))
+        c = db()
+        keep, custom_rows = {}, {}
+    deep = "--deep" in args
+    t0 = time.time()
+    for fn in scanners():
+        fn(c)
+    # custom tools added via 'howzo add' must survive rescans
+    for name, (src, ver, path, one, w, h, h_at) in custom_rows.items():
+        c.execute("INSERT INTO tools(name, source, version, path, oneliner, when_to_use, help_excerpt, "
+                  "help_captured_at, scanned_at) VALUES(?,?,?,?,?,?,?,?,?) ON CONFLICT(name) DO NOTHING",
+                  (name, src, ver, path, one, w, h, h_at, time.strftime("%Y-%m-%d")))
+    for name, (h, h_at, w) in keep.items():
+        c.execute("UPDATE tools SET help_excerpt=?, help_captured_at=?, when_to_use=? WHERE name=?",
+                  (h, h_at, w, name))
+    c.commit()
+    total = c.execute("SELECT COUNT(*) FROM tools").fetchone()[0]
+    print(f"  inventory: {total} tools in {time.time()-t0:.0f}s")
+    if deep:
+        print("  capturing --help (can take a few minutes)...")
+        rows = c.execute("SELECT id, name, path FROM tools").fetchall()
+        done = 0
+        for tid, name, path in rows:
+            h = capture_help(name, path)
+            if h:
+                c.execute("UPDATE tools SET help_excerpt=?, help_captured_at=? WHERE id=?",
+                          (h, time.strftime("%Y-%m-%d"), tid))
+                done += 1
+        c.commit()
+        print(f"  help captured for {done}/{len(rows)} tools")
+    else:
+        print("  (tip: 'howzo scan --deep' also captures --help for richer answers;")
+        print("   'howzo deep <tool>' captures help for one tool on demand)")
+    return 0
+
+
+def cmd_ask(args):
+    q = " ".join(args).strip()
+    if not q:
+        print('usage: howzo ask "how do I ..."')
+        return 1
+    c = db()
+    row = find_by_name(c, q)
+    if row:
+        print(render_tool(row, q))
+        return 0
+    ftsq = fts_query(q)
+    toks = query_tokens(q)
+    rows = []
+    if ftsq:
+        try:
+            rows = c.execute(
+                "SELECT t.*, bm25(tools_fts) AS score FROM tools_fts f JOIN tools t ON t.id=f.rowid "
+                "WHERE tools_fts MATCH ? ORDER BY score LIMIT 12", (ftsq,)).fetchall()
+        except sqlite3.OperationalError:
+            rows = []
+    if not rows and toks:
+        # fallback: broad LIKE candidates per token, then word-boundary filter
+        cand = {}
+        for t in toks:
+            like = f"%{t}%"
+            for r in c.execute("SELECT * FROM tools WHERE lower(name) LIKE ? OR lower(oneliner) LIKE ? "
+                               "OR lower(when_to_use) LIKE ? OR lower(help_excerpt) LIKE ? LIMIT 60",
+                               (like, like, like, like)):
+                hay = " ".join(filter(None, [r["name"], r["oneliner"], r["when_to_use"], r["help_excerpt"]]))
+                if has_word(hay, t):
+                    cand[r["id"]] = r
+        rows = list(cand.values())
+    rows = rank_rows(rows, toks)
+    if not rows:
+        print(f"no match for: {q}\n  (try 'howzo scan --deep' to index --help text)")
+        return 1
+    for r in rows[:3]:
+        print(render_tool(r, q))
+        print()
+    best_cov = max(coverage(r, toks) for r in rows[:3])
+    if best_cov < len(toks):
+        print("  (partial match - no tool advertises all terms)")
+    return 0
+
+
+def cmd_whatis(args):
+    c = db()
+    for name in args:
+        row = find_by_name(c, name)
+        if not row:
+            print(f"unknown tool: {name}")
+            continue
+        t = {k: row[k] for k in row.keys()}
+        print(render_tool(t, " ".join(args)))
+        if t.get("help_excerpt"):
+            print("  help:")
+            for l in t["help_excerpt"].splitlines()[:12]:
+                print("   ", l)
+        print()
+    return 0
+
+
+def cmd_add(args):
+    if len(args) < 2:
+        print('usage: howzo add <name> "what it does"   (e.g. howzo add my-internal-tool \'syncs staging DB\')')
+        return 1
+    name = args[0]
+    desc = " ".join(args[1:])
+    c = db()
+    upsert(c, name, "custom", "", "", desc)
+    c.commit()
+    print(f"added: {name} (source=custom, survives rescans)")
+    return 0
+
+
+def cmd_deep(args):
+    if not args:
+        print("usage: howzo deep <tool>")
+        return 1
+    name = args[0]
+    c = db()
+    row = c.execute("SELECT * FROM tools WHERE lower(name)=?", (name.lower(),)).fetchone()
+    if not row:
+        print(f"not in inventory: {name} (run 'howzo scan')")
+        return 1
+    t = {k: row[k] for k in row.keys()}
+    print(f"capturing help for {name}...")
+    h = capture_help(name, t.get("path"))
+    if not h:
+        print("  no help captured (binary not found or silent --help)")
+        return 1
+    c.execute("UPDATE tools SET help_excerpt=?, help_captured_at=? WHERE id=?",
+              (h, time.strftime("%Y-%m-%d"), t["id"]))
+    c.commit()
+    print(f"  ok ({len(h)} chars)")
+    return 0
+
+
+def cmd_list(args):
+    c = db()
+    src = None
+    if "--source" in args:
+        src = args[args.index("--source") + 1]
+    q = "SELECT * FROM tools"
+    params = ()
+    if src:
+        q += " WHERE source=?"
+        params = (src,)
+    q += " ORDER BY source, name"
+    rows = c.execute(q, params).fetchall()
+    print(f"{'TOOL':<28} {'SRC':<8} {'VER':<14} WHAT")
+    for r in rows:
+        t = {k: r[k] for k in r.keys()}
+        print(f"{t['name']:<28} {t['source']:<8} {str(t.get('version') or '')[:13]:<14} {t.get('oneliner','')[:70]}")
+    print(f"\n{len(rows)} tools")
+    return 0

howzo-0.1.0/src/howzo/config.py

@@ -0,0 +1,25 @@
+"""Platform constants and paths.
+
+The database location can be overridden with the HOWZO_DB environment
+variable (the test suite uses this to run against temp directories).
+"""
+import os
+
+IS_WINDOWS = os.name == "nt"
+HOME = os.path.expanduser("~")
+
+# Directories scanned for user scripts (see scan/scripts.py)
+SCAN_DIRS = [os.path.join(HOME, "bin"), os.path.join(HOME, ".local", "bin")]
+
+
+def db_dir():
+    override = os.environ.get("HOWZO_DB")
+    if override:
+        return override
+    if IS_WINDOWS:
+        return os.path.join(os.environ.get("LOCALAPPDATA") or HOME, "howzo")
+    return os.path.join(HOME, ".local", "share", "howzo")
+
+
+def db_path():
+    return os.path.join(db_dir(), "howzo.db")