crowsnest 0.0.2__tar.gz

crowsnest-0.0.2/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+# wads CI — calls the reusable workflow hosted in i2mint/wads.
+#
+# All configuration comes from this repo's pyproject.toml [tool.wads.ci.*].
+# To customize the workflow itself (rare), replace this file with the
+# full inline template `wads/data/github_ci_uv.yml` from i2mint/wads.
+#
+# Permissions: the reusable workflow needs `contents: write` (version-bump
+# push-back, gh-pages branch push) and `pages: write` (Pages REST config).
+# Both default to read-only on personal-account callers, so they are granted
+# explicitly here.
+name: Continuous Integration
+on: [push, pull_request]
+jobs:
+  ci:
+    uses: i2mint/wads/.github/workflows/uv-ci.yml@master
+    permissions:
+      contents: write
+      pages: write
+    # Explicit pass-through (not `secrets: inherit`, which does not reliably
+    # propagate caller-repo secrets to a reusable workflow owned by a different
+    # account). crowsnest reads local files and never reaches the network, so
+    # PYPI_PASSWORD is the only secret it needs.
+    secrets:
+      PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}

crowsnest-0.0.2/.gitignore

@@ -0,0 +1,129 @@
+docs/_build/
+wads_configs.json
+data/wads_configs.json
+wads/data/wads_configs.json
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+.DS_Store
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm
+.idea
+
+# Ruff
+.ruff_cache/
+
+# VS Code
+.vscode/
+
+# Temporary test outputs
+batch_results.json
+*.tmp
+tmp/
+temp/
+# Local session handoffs (not for commit)
+.claude/handoffs/

crowsnest-0.0.2/LICENSE

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

crowsnest-0.0.2/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.5
+Name: crowsnest
+Version: 0.0.2
+Summary: One session that watches your other Claude Code sessions: who is busy, who is waiting on you, what each one just said, and how to ask one directly
+Project-URL: Homepage, https://github.com/thorwhalen/crowsnest
+Project-URL: Repository, https://github.com/thorwhalen/crowsnest
+Project-URL: Issues, https://github.com/thorwhalen/crowsnest/issues
+Author: Thor Whalen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,claude-code,monitor,sessions,transcripts
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: cw<0.2,>=0.1.1
+Requires-Dist: openloops>=0.1.8
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# crowsnest
+
+**One session that watches your other Claude Code sessions.**
+
+A machine running many Claude Code sessions has a question nobody answers: *what are they all doing, and which of them needs me?* Each session knows only itself, the terminal tabs are silent until you click them, and the answer lives in forty scrollbacks.
+
+`crowsnest` reads what Claude Code already writes, the registry it keeps for every running session and the transcript each one appends to, and answers in three tiers, cheapest first. It never sends, spawns, kills or writes into another session.
+
+## Start here
+
+```bash
+pip install crowsnest          # Python 3.10+. Puts a `crowsnest` command on your PATH.
+crowsnest install-skills       # link the skill and the scout subagent into ~/.claude
+```
+
+Then open a session, name it, and ask in whatever words you would have used anyway:
+
+```bash
+claude -n lookout
+```
+
+> **what are my sessions doing, and is anything waiting on me?**
+
+```
+## Waiting on you
+- xa_needed_or_not (xa, 25m) — input needed
+
+## Just finished
+- monitor (proj, 10m) — "The sweep landed. It's the repo-side view, and it's complementary…"
+
+## Working
+- openloops: one session, mid-turn on the one-command test.
+
+## Headline
+1 waiting on you, 1 just finished, 1 working, 29 idle.
+```
+
+That answer is a synthesis. Every row behind it is one the `crowsnest` command printed, and the skill tells the session how to go deeper when a row is not enough: read a session's earlier turns, ask the session itself, or arm the event stream and be told.
+
+## The three tiers
+
+| Tier | What | Costs the watched session |
+|---|---|---|
+| 1. read | `crowsnest`, `crowsnest show X`, `crowsnest turns X` — the registry and the transcript tail | nothing |
+| 2. ask | message a running session (Claude Code's `SendMessage`) and get an answer from its own context | one turn of its context |
+| 3. be told | `crowsnest watch`, one line per change, fed to the watching session's `Monitor` tool | nothing |
+
+The skill's rule is to never spend a costlier tier when a cheaper one answers, and never to ask a session that is `busy` or `waiting`.
+
+## The command
+
+```
+crowsnest                          who is alive: waiting on you first, then busy, then idle
+crowsnest show <session>           one session: last asked, last said, running now, pending question
+crowsnest turns <session> -n 5     the last five turns, oldest first; --before N pages back
+crowsnest watch                    one line per change, forever (started, exited, idle, busy, waiting, error)
+crowsnest install-skills           link the skill and the scout subagent into ~/.claude
+```
+
+`<session>` is the name you gave the session with `claude -n <name>`, a unique prefix of one, a session-id prefix, or a pid.
+
+```
+waiting  25m  xa_needed_or_not      xa           input needed · Let me split that into smaller steps.
+busy     14m  session_monitor       openloops    → Bash: Run the one-command test
+idle     10m  monitor               proj         "The sweep landed. It's the repo-side view…"
+-- 32 live: 1 waiting, 1 busy, 30 idle
+```
+
+## What it reads
+
+- `~/.claude/sessions/<pid>.json`: written while a session runs. Name, session id, working directory, `busy` / `idle` / `waiting`, and when waiting, what for. Checked against a live process before it is reported, because a crash leaves the file behind.
+- `~/.claude/projects/<slug>/<session-id>.jsonl`: the transcript. Read from the end, widening until one human prompt is in view; `turns` reads the whole file on request.
+
+What a transcript's content *means* is [openloops](https://github.com/thorwhalen/openloops)' business, and crowsnest calls it rather than re-implementing it. openloops deliberately never looks at whether a process is running; crowsnest is that other half.
+
+## From Python
+
+```python
+from crowsnest import roster, show, turns, events, live_sessions
+
+roster()["counts"]  # {'waiting': 1, 'busy': 1, 'idle': 30, 'other': 0}
+show("monitor")["activity"]["last_assistant_text"]
+for event in events(interval=5):  # forever
+    ...
+```
+
+Every function takes `home=` (the Claude Code config directory; a synced copy of another machine's works the same way) and the readers take `is_alive=` (how a registry pid is confirmed running).
+
+## Not in crowsnest
+
+Starting a session, in some directory, from a phone, is [xa](https://github.com/thorwhalen/xa)'s job (`xa spawn`). Asking a session a question is Claude Code's own `SendMessage`; the skill says when.

crowsnest-0.0.2/README.md

@@ -0,0 +1,91 @@
+# crowsnest
+
+**One session that watches your other Claude Code sessions.**
+
+A machine running many Claude Code sessions has a question nobody answers: *what are they all doing, and which of them needs me?* Each session knows only itself, the terminal tabs are silent until you click them, and the answer lives in forty scrollbacks.
+
+`crowsnest` reads what Claude Code already writes, the registry it keeps for every running session and the transcript each one appends to, and answers in three tiers, cheapest first. It never sends, spawns, kills or writes into another session.
+
+## Start here
+
+```bash
+pip install crowsnest          # Python 3.10+. Puts a `crowsnest` command on your PATH.
+crowsnest install-skills       # link the skill and the scout subagent into ~/.claude
+```
+
+Then open a session, name it, and ask in whatever words you would have used anyway:
+
+```bash
+claude -n lookout
+```
+
+> **what are my sessions doing, and is anything waiting on me?**
+
+```
+## Waiting on you
+- xa_needed_or_not (xa, 25m) — input needed
+
+## Just finished
+- monitor (proj, 10m) — "The sweep landed. It's the repo-side view, and it's complementary…"
+
+## Working
+- openloops: one session, mid-turn on the one-command test.
+
+## Headline
+1 waiting on you, 1 just finished, 1 working, 29 idle.
+```
+
+That answer is a synthesis. Every row behind it is one the `crowsnest` command printed, and the skill tells the session how to go deeper when a row is not enough: read a session's earlier turns, ask the session itself, or arm the event stream and be told.
+
+## The three tiers
+
+| Tier | What | Costs the watched session |
+|---|---|---|
+| 1. read | `crowsnest`, `crowsnest show X`, `crowsnest turns X` — the registry and the transcript tail | nothing |
+| 2. ask | message a running session (Claude Code's `SendMessage`) and get an answer from its own context | one turn of its context |
+| 3. be told | `crowsnest watch`, one line per change, fed to the watching session's `Monitor` tool | nothing |
+
+The skill's rule is to never spend a costlier tier when a cheaper one answers, and never to ask a session that is `busy` or `waiting`.
+
+## The command
+
+```
+crowsnest                          who is alive: waiting on you first, then busy, then idle
+crowsnest show <session>           one session: last asked, last said, running now, pending question
+crowsnest turns <session> -n 5     the last five turns, oldest first; --before N pages back
+crowsnest watch                    one line per change, forever (started, exited, idle, busy, waiting, error)
+crowsnest install-skills           link the skill and the scout subagent into ~/.claude
+```
+
+`<session>` is the name you gave the session with `claude -n <name>`, a unique prefix of one, a session-id prefix, or a pid.
+
+```
+waiting  25m  xa_needed_or_not      xa           input needed · Let me split that into smaller steps.
+busy     14m  session_monitor       openloops    → Bash: Run the one-command test
+idle     10m  monitor               proj         "The sweep landed. It's the repo-side view…"
+-- 32 live: 1 waiting, 1 busy, 30 idle
+```
+
+## What it reads
+
+- `~/.claude/sessions/<pid>.json`: written while a session runs. Name, session id, working directory, `busy` / `idle` / `waiting`, and when waiting, what for. Checked against a live process before it is reported, because a crash leaves the file behind.
+- `~/.claude/projects/<slug>/<session-id>.jsonl`: the transcript. Read from the end, widening until one human prompt is in view; `turns` reads the whole file on request.
+
+What a transcript's content *means* is [openloops](https://github.com/thorwhalen/openloops)' business, and crowsnest calls it rather than re-implementing it. openloops deliberately never looks at whether a process is running; crowsnest is that other half.
+
+## From Python
+
+```python
+from crowsnest import roster, show, turns, events, live_sessions
+
+roster()["counts"]  # {'waiting': 1, 'busy': 1, 'idle': 30, 'other': 0}
+show("monitor")["activity"]["last_assistant_text"]
+for event in events(interval=5):  # forever
+    ...
+```
+
+Every function takes `home=` (the Claude Code config directory; a synced copy of another machine's works the same way) and the readers take `is_alive=` (how a registry pid is confirmed running).
+
+## Not in crowsnest
+
+Starting a session, in some directory, from a phone, is [xa](https://github.com/thorwhalen/xa)'s job (`xa spawn`). Asking a session a question is Claude Code's own `SendMessage`; the skill says when.

crowsnest-0.0.2/crowsnest/__init__.py

@@ -0,0 +1,52 @@
+"""One session that watches the others.
+
+A machine running many Claude Code sessions has a question nobody answers: *what are they
+all doing, and which of them needs me?* Each session knows only itself, the terminal tabs
+are silent until you click them, and the answer lives in forty scrollbacks.
+
+``crowsnest`` reads what Claude Code already writes -- the registry it keeps for every
+running session, and the transcript each session appends to -- and answers in three
+tiers, cheapest first:
+
+1. **The roster** (:func:`crowsnest.tools.roster`): who is alive, busy, idle or waiting,
+   where, since when. Instant; no transcript is read.
+2. **The activity** (:func:`crowsnest.tools.show`, :func:`crowsnest.tools.turns`): what a
+   session was last asked, what it last said, the tool it is running now, the question
+   it is waiting on -- read from the tail of its transcript, which costs the watched
+   session nothing and never interrupts it. ``turns`` pages further back when the tail is
+   not enough.
+3. **The ask**: a running session can be *messaged* and will answer from its own
+   context. That is a Claude Code feature, not a Python one, so it lives in the shipped
+   skill (``crowsnest/data/skills/crowsnest/SKILL.md``) rather than here -- with the rule
+   that says when it is worth a turn of someone else's context and when it is not.
+
+And one stream: :func:`crowsnest.watch.events` yields a line every time a session starts,
+exits, finishes a turn, or starts waiting on its human, so a monitor is told rather than
+made to poll.
+
+Everything here is read-only. Nothing sends, spawns, kills, or writes into another
+session; the one write in the package is the skill installer, and it writes symlinks.
+
+>>> from crowsnest import live_sessions, roster
+>>> live_sessions(home='/nonexistent-dir-for-doctest')
+[]
+"""
+
+from crowsnest.activity import Activity, Turn, read_activity, read_turns
+from crowsnest.registry import LiveSession, live_sessions
+from crowsnest.tools import resolve, roster, show, turns
+from crowsnest.watch import events
+
+__all__ = [
+    "Activity",
+    "LiveSession",
+    "Turn",
+    "events",
+    "live_sessions",
+    "read_activity",
+    "read_turns",
+    "resolve",
+    "roster",
+    "show",
+    "turns",
+]

crowsnest-0.0.2/crowsnest/__main__.py

@@ -0,0 +1,234 @@
+"""The ``crowsnest`` command: the one surface v0 builds.
+
+Every verb is a thin renderer over a function in :mod:`crowsnest.tools`, the single list
+all surfaces dispatch from. The core prints nothing and exits nothing; the formatting is
+here so that a later MCP or HTTP adapter needs no change to the core.
+
+Bare ``crowsnest`` prints the roster, because the fewest keystrokes have to produce the
+useful thing.
+"""
+
+# PYTHON_ARGCOMPLETE_OK
+
+from __future__ import annotations
+
+import json as _json
+import sys
+from datetime import datetime, timezone
+
+from crowsnest import skills as _skills
+from crowsnest import tools
+from crowsnest import watch as _watch
+
+__all__ = ["main"]
+
+DEFAULT_COMMAND = "roster"
+
+
+def _age(epoch: float | None) -> str:
+    if not epoch:
+        return "?"
+    seconds = max(0.0, datetime.now(timezone.utc).timestamp() - epoch)
+    for size, unit in ((86400, "d"), (3600, "h"), (60, "m")):
+        if seconds >= size:
+            return f"{seconds / size:.0f}{unit}"
+    return f"{seconds:.0f}s"
+
+
+def _one_line(text: str, limit: int) -> str:
+    text = " ".join((text or "").split())
+    return text if len(text) <= limit else text[: limit - 1].rstrip() + "…"
+
+
+def _local(stamp: str) -> str:
+    """An ISO timestamp as local ``HH:MM``, or the raw value when unparseable."""
+    try:
+        return (
+            datetime.fromisoformat(stamp.replace("Z", "+00:00"))
+            .astimezone()
+            .strftime("%H:%M")
+        )
+    except ValueError:
+        return stamp
+
+
+def _row_detail(row: dict, limit: int) -> str:
+    act = row.get("activity") or {}
+    status = row["status"]
+    if status == "waiting":
+        cause = act.get("pending_question") or "; ".join(act.get("in_flight") or ())
+        parts = [
+            row.get("waiting_for") or "waiting",
+            cause or act.get("last_assistant_text", ""),
+        ]
+        return _one_line(" · ".join(p for p in parts if p), limit)
+    if status == "busy":
+        running = "; ".join(act.get("in_flight") or ())
+        if running:
+            return _one_line("→ " + running, limit)
+        return _one_line("asked: " + act.get("last_user_prompt", ""), limit)
+    said = act.get("last_assistant_text", "")
+    mark = "⚠ " if act.get("errored") else ""
+    return _one_line(f'{mark}"{said}"' if said else "", limit)
+
+
+def roster(*, home: str | None = None, brief: bool = False, width: int = 110):
+    """Who is alive, most urgent first: waiting on you, then busy, then idle.
+
+    `--brief` answers from the registry alone, without reading any transcript.
+    """
+    result = tools.roster(home=home, activity=not brief)
+    lines = []
+    for row in result["sessions"]:
+        head = f"{row['status']:<8}{_age(row['status_since']):>4}  {row['label'][:26]:<27}{row['project'][:16]:<17}"
+        detail = "" if brief else _row_detail(row, max(20, width - len(head)))
+        lines.append((head + detail).rstrip())
+    counts = result["counts"]
+    summary = ", ".join(f"{n} {k}" for k, n in counts.items() if n)
+    lines.append(f"-- {len(result['sessions'])} live: {summary or 'none'}")
+    return "\n".join(lines)
+
+
+def show(session: str, *, home: str | None = None, recent: int = 8, json: bool = False):
+    """One session in full: what it was asked, what it said, what it is running now.
+
+    `session` is a registry name, a unique prefix of one, a session-id prefix, or a pid.
+    """
+    result = tools.show(session, home=home, recent=recent)
+    if json:
+        return _json.dumps(result, indent=2)
+    s, act = result["session"], result["activity"]
+    since = _age(s["status_since"])
+    out = [
+        f"# {s['label']}  ({s['status']} for {since}"
+        + (f", {s['waiting_for']}" if s["waiting_for"] else "")
+        + ")"
+    ]
+    out.append(
+        f"pid {s['pid']} · session {s['session_id'][:8]} · {s['cwd']}"
+        + (f" · branch {act['git_branch']}" if act["git_branch"] else "")
+        + (" · remote control on" if s["remote_control"] else "")
+    )
+    if act["pending_question"]:
+        out += ["", "## Waiting on you", act["pending_question"]]
+    if act["in_flight"]:
+        out += ["", "## In flight", *[f"- {t}" for t in act["in_flight"]]]
+    out += [
+        "",
+        f"## Last asked ({_local(act['last_prompt_at'])})",
+        act["last_user_prompt"] or "(none in the tail)",
+    ]
+    out += [
+        "",
+        f"## Last said ({_local(act['last_text_at'])})",
+        act["last_assistant_text"] or "(none in the tail)",
+    ]
+    if act["recent_tools"]:
+        out += ["", "## Recent tools", *[f"- {t}" for t in act["recent_tools"]]]
+    flags = [k for k in ("turn_open", "errored") if act[k]]
+    if flags or not act["tail_complete"]:
+        out += [
+            "",
+            "flags: "
+            + ", ".join(flags + ([] if act["tail_complete"] else ["tail only"])),
+        ]
+    return "\n".join(out)
+
+
+def turns(
+    session: str,
+    *,
+    last: int = 5,
+    before: int | None = None,
+    home: str | None = None,
+    json: bool = False,
+):
+    """The last few turns of a session, oldest first. `--before N` pages back from turn N."""
+    result = tools.turns(session, last=last, before=before, home=home)
+    if json:
+        return _json.dumps(result, indent=2)
+    out = [f"# {result['session']['label']} — turns"]
+    for t in result["turns"]:
+        out += [
+            "",
+            f"## turn {t['index']}  ({_local(t['prompt_at'])})",
+            f"> {t['prompt']}",
+        ]
+        if t["tools"]:
+            out.append(
+                f"tools ({len(t['tools'])}): "
+                + "; ".join(t["tools"][:8])
+                + (" …" if len(t["tools"]) > 8 else "")
+            )
+        out.append(t["reply"] or "(no final text)")
+    if not result["turns"]:
+        out.append("(no turns)")
+    return "\n".join(out)
+
+
+def watch(
+    *, interval: float = _watch.DFLT_INTERVAL, home: str | None = None, json: bool = False
+):
+    """Print one line per change, forever: started, exited, idle, busy, waiting, error.
+
+    Built for Claude Code's `Monitor` tool: each line becomes a notification in the
+    watching session. Stop with Ctrl-C.
+    """
+    try:
+        for event in _watch.events(interval=interval, home=home):
+            if json:
+                line = _json.dumps(event)
+            else:
+                when = _local(event["at"])
+                line = f"{when}  {event['kind']:<8} {event['name']} ({event['project']})"
+                if event["detail"]:
+                    line += f" — {event['detail']}"
+            print(line, flush=True)
+    except KeyboardInterrupt:
+        pass
+
+
+def install_skills(
+    *,
+    target: str | None = None,
+    only: str | None = None,
+    force: bool = False,
+    dry_run: bool = False,
+):
+    """Link the bundled skill and subagent into ~/.claude (or `--target`). Idempotent."""
+    names = [n for n in (only or "").split(",") if n.strip()] or None
+    plan = _skills.install_skills(target=target, only=names, force=force, dry_run=dry_run)
+    lines = [f"{'would install' if dry_run else 'installed'} into {plan['target']}"]
+    for row in plan["actions"]:
+        how = f" ({row['method']})" if row["method"] else ""
+        lines.append(
+            f"{row['action']:<9}{row['kind']:<7}{row['name']:<18}{row['reason']}{how}"
+        )
+    return "\n".join(lines)
+
+
+_commands = [roster, show, turns, watch, install_skills]
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Dispatch the ``crowsnest`` command. Bare ``crowsnest`` runs :func:`roster`."""
+    import cw
+
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv or argv[0].startswith("-") and argv[0] not in ("-h", "--help"):
+        argv = [DEFAULT_COMMAND, *argv]
+    parser = cw.mk_parser(
+        _commands, prog="crowsnest", description=__doc__.splitlines()[0]
+    )
+    try:
+        code = cw.run(parser, argv)
+    except (ValueError, KeyError) as exc:
+        message = exc.args[0] if exc.args else str(exc)
+        print(f"crowsnest: {message}", file=sys.stderr)
+        sys.exit(2)
+    if code:
+        raise SystemExit(code)
+
+
+if __name__ == "__main__":
+    main()