Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(cli): an occasional repowise.dev hint at the moments it helps (#3005)

Swati Ahujad34fae85998f
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.md
index 37ac7bc8a..ece8b2eb9 100644
--- a/docs/reference/CLI_REFERENCE.md
+++ b/docs/reference/CLI_REFERENCE.md
@@ -2173,6 +2173,21 @@ repowise telemetry disable
---
+### `repowise config hints on|off`
+
+Now and then, at a moment where it would help (a finished `init`, a slow
+`update`), the CLI prints one dim line on stderr about
+what repowise.dev adds, with a link. At most one per run, each at most once a
+week. Never under `--format json`, in CI, when stderr is not a terminal, when
+you are signed in, or from `mcp`, `serve`, `watch` and hooks.
+
+```bash
+repowise config hints off # also: REPOWISE_NO_HINTS=1 or DO_NOT_TRACK=1
+repowise config hints on
+```
+
+---
+
### `repowise login`
Sign in to your hosted repowise.dev account. This is unrelated to LLM provider
diff --git a/packages/cli/src/repowise/cli/commands/config_cmd.py b/packages/cli/src/repowise/cli/commands/config_cmd.py
new file mode 100644
index 000000000..c3a4d3b23
--- /dev/null
+++ b/packages/cli/src/repowise/cli/commands/config_cmd.py
@@ -0,0 +1,28 @@
+"""``repowise config``: local CLI preferences kept in ``~/.repowise``."""
+
+from __future__ import annotations
+
+import click
+
+from repowise.cli.helpers import console
+
+
[email protected](name="config")
+def config_group() -> None:
+ """Change local CLI preferences."""
+
+
+@config_group.command(name="hints")
[email protected]("state", type=click.Choice(["on", "off"]))
+def config_hints(state: str) -> None:
+ """Turn the occasional repowise.dev tip on or off."""
+ from repowise.cli import hints
+
+ hints.set_enabled(state == "on")
+ if state == "on":
+ console.print("[green]✓[/green] repowise.dev tips are on (at most one a week each).")
+ else:
+ console.print("[green]✓[/green] repowise.dev tips are off.")
+
+
+config_command = config_group
diff --git a/packages/cli/src/repowise/cli/commands/doctor_cmd/repo_checks.py b/packages/cli/src/repowise/cli/commands/doctor_cmd/repo_checks.py
index a8e795d62..f45bef3f2 100644
--- a/packages/cli/src/repowise/cli/commands/doctor_cmd/repo_checks.py
+++ b/packages/cli/src/repowise/cli/commands/doctor_cmd/repo_checks.py
@@ -357,7 +357,12 @@ def _run_repo_checks(
creds = credentials.load()
if creds is None:
checks.append(
- _check("Hosted account", True, "Not signed in (optional: repowise login)")
+ _check(
+ "Hosted account",
+ True,
+ "Not signed in (optional: repowise login). "
+ "Publish this repo free: repowise publish",
+ )
)
elif creds.get("stale"):
checks.append(
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/command.py b/packages/cli/src/repowise/cli/commands/init_cmd/command.py
index 8ea0f6820..cb23baf4e 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/command.py
@@ -1431,6 +1431,9 @@ def init_command(
)
)
except ProviderError as exc:
+ from repowise.cli.hints import maybe_hint
+
+ maybe_hint("provider_fail")
raise reasoned_error(
f"Provider validation failed: {exc}",
reason="provider_validation_failed",
@@ -1562,6 +1565,9 @@ def init_command(
f"\n{mini(EYES_SLEEPY)} [{WARN}]Interrupted.[/] Indexed work so far has been "
"saved — run [bold]repowise init --resume[/] to continue where it stopped."
)
+ from repowise.cli.hints import maybe_hint
+
+ maybe_hint("interrupt")
return
# What the run degraded on, in a place an agent can read after the
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/reporting.py b/packages/cli/src/repowise/cli/commands/init_cmd/reporting.py
index fd0fbb693..fb000d57b 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/reporting.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/reporting.py
@@ -118,6 +118,16 @@ def _render_defect_accuracy(result: Any) -> None:
console.print()
+#: From this many files, the hosted pitch is staying fresh without a long local
+#: run. Lower than the fast-mode offer on purpose: a hint costs nothing to skip.
+_LARGE_REPO_FILES = 1000
+
+
+def completion_hint(run_mode: str, file_count: int) -> str:
+ """Which hint a finished init earns: big repos hear about freshness."""
+ return "large_repo" if run_mode == "fast" or file_count >= _LARGE_REPO_FILES else "init_success"
+
+
def show_completion(
*,
repo_path: Any,
@@ -344,6 +354,12 @@ def show_completion(
console.print(_line)
console.print()
+ # One quiet stderr line about repowise.dev (see hints.py for when it is
+ # shown); a big repo hears about staying fresh instead.
+ from repowise.cli.hints import maybe_hint
+
+ maybe_hint(completion_hint(run_mode, result.file_count))
+
print_files_written(console, Path(repo_path), files_written or [])
_show_generation_checks(result)
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/reporting.py b/packages/cli/src/repowise/cli/commands/update_cmd/reporting.py
index 1c7f380c1..5ced26ca4 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/reporting.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/reporting.py
@@ -316,6 +316,7 @@ def show_full_completion(
build_completion_panel("repowise update complete", metrics, next_steps=next_steps)
)
console.print()
+ _slow_update_hint(elapsed)
def show_index_only_completion(
@@ -371,6 +372,7 @@ def show_index_only_completion(
)
)
console.print()
+ _slow_update_hint(elapsed)
def show_workspace_completion(
@@ -407,6 +409,18 @@ def show_workspace_completion(
build_completion_panel("repowise workspace update complete", metrics, next_steps=next_steps)
)
console.print()
+ _slow_update_hint(elapsed)
+
+
+#: An update slower than this is one a hosted index would have saved.
+_SLOW_UPDATE_SECONDS = 60
+
+
+def _slow_update_hint(elapsed: float) -> None:
+ if elapsed > _SLOW_UPDATE_SECONDS:
+ from repowise.cli.hints import maybe_hint
+
+ maybe_hint("slow_update")
# ---------------------------------------------------------------------------
diff --git a/packages/cli/src/repowise/cli/hints.py b/packages/cli/src/repowise/cli/hints.py
new file mode 100644
index 000000000..ee228fe56
--- /dev/null
+++ b/packages/cli/src/repowise/cli/hints.py
@@ -0,0 +1,186 @@
+"""One quiet line about repowise.dev, at the moments it would help.
+
+Rules that keep it from being a nag:
+
+* stderr only, one dim line plus its link, never in ``--format json`` runs;
+* at most one hint per command run, and each hint at most once every 7 days;
+* never from ``mcp``, ``serve``, ``watch``, hooks, or anything an agent reads;
+* off in CI and tests, when stderr is not a terminal, for signed-in users,
+ with ``REPOWISE_NO_HINTS=1``, ``repowise config hints off`` or ``DO_NOT_TRACK``.
+
+Deciding never touches the network: everything is read from local files and
+the environment, so a hint can never slow a command down. Every local feature
+works without signing in; a hint only says what the hosted side adds.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+
+_SHOWN_KEY = "hints_shown"
+_ENABLED_KEY = "hints_enabled"
+_EVERY = timedelta(days=7)
+
+#: Commands whose output belongs to an agent, a daemon or a hook.
+_QUIET_COMMANDS = frozenset({"mcp", "serve", "watch", "hook", "augment"})
+
+#: Set once a hint is shown, so a run never shows two.
+_shown_this_run = False
+
+
+@dataclass(frozen=True)
+class Hint:
+ text: str
+ #: Where the link was shown, for the site's attribution.
+ src: str
+ #: The section of the repowise.dev/hosted story the link opens.
+ moment: str
+ #: The free next step the line ends with.
+ action: str = "Publish it free: repowise publish"
+
+
+#: Publishing a public repo is free (no card, up to 2 repos); anything about
+#: private repos or more repos says "free for 10 days, card required".
+HINTS: dict[str, Hint] = {
+ "init_success": Hint(
+ "Use this repo from Claude.ai or ChatGPT, or share it with your team.",
+ src="cli_init_success",
+ moment="mcp",
+ ),
+ "provider_fail": Hint(
+ "Don't want to set up a key? repowise.dev writes the docs for you.",
+ src="cli_provider_fail",
+ moment="keys",
+ action="Start free: repowise publish",
+ ),
+ "interrupt": Hint(
+ "Big repo? repowise.dev indexes it in the cloud and keeps it fresh on every push.",
+ src="cli_interrupt",
+ moment="sync",
+ action="Start free: repowise publish",
+ ),
+ "large_repo": Hint(
+ "repowise.dev keeps big repos fresh automatically on every push "
+ "(Pro: free for 10 days, card required).",
+ src="cli_large_repo",
+ moment="sync",
+ ),
+ "slow_update": Hint(
+ "Skip manual updates: repowise.dev re-indexes on every push.",
+ src="cli_slow_update",
+ moment="sync",
+ ),
+}
+
+
+def _env_truthy(name: str) -> bool:
+ return os.environ.get(name, "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def set_enabled(enabled: bool) -> None:
+ """``repowise config hints on|off``."""
+ from repowise.cli.platform import store
+
+ store.update(**{_ENABLED_KEY: bool(enabled)})
+
+
+def is_enabled() -> bool:
+ """The user's switch and the environment, nothing else."""
+ if _env_truthy("REPOWISE_NO_HINTS") or _env_truthy("DO_NOT_TRACK"):
+ return False
+ from repowise.cli.platform import store
+
+ return store.load().get(_ENABLED_KEY) is not False
+
+
+def _quiet_command() -> bool:
+ try:
+ import click
+
+ ctx = click.get_current_context(silent=True)
+ except Exception:
+ return False
+ if ctx is None:
+ return False
+ root = ctx.find_root()
+ names = {root.invoked_subcommand, ctx.info_name}
+ return bool(names & _QUIET_COMMANDS)
+
+
+def _signed_in() -> bool:
+ from repowise.cli.platform import credentials
+
+ creds = credentials.load()
+ return bool(creds) and not creds.get("stale")
+
+
+def _due(hint_id: str, now: datetime) -> bool:
+ from repowise.cli.platform import store
+
+ last = (store.load().get(_SHOWN_KEY) or {}).get(hint_id)
+ if not isinstance(last, str):
+ return True
+ try:
+ return now - datetime.fromisoformat(last) >= _EVERY
+ except ValueError:
+ return True
+
+
+def _mark_shown(hint_id: str, now: datetime) -> None:
+ from repowise.cli.platform import store
+
+ shown = dict(store.load().get(_SHOWN_KEY) or {})
+ shown[hint_id] = now.isoformat()
+ store.update(**{_SHOWN_KEY: shown})
+
+
+def should_show(hint_id: str, *, fmt: str = "text") -> bool:
+ if _shown_this_run or hint_id not in HINTS or fmt == "json":
+ return False
+ from repowise.cli.platform.telemetry.environment import is_ci
+
+ if is_ci() or not is_enabled() or _quiet_command():
+ return False
+ import sys
+
+ if not sys.stderr.isatty():
+ return False
+ return not _signed_in() and _due(hint_id, datetime.now(UTC))
+
+
+def maybe_hint(hint_id: str, *, fmt: str = "text") -> bool:
+ """Show the hint on stderr if every rule above allows it. Never raises.
+
+ Returns whether it was shown.
+ """
+ global _shown_this_run
+ try:
+ if not should_show(hint_id, fmt=fmt):
+ return False
+ hint = HINTS[hint_id]
+ from rich.markup import escape
+
+ from repowise.cli.helpers import err_console
+ from repowise.cli.platform.links import site_link
+
+ url = site_link("hosted", hint.src, fragment=hint.moment)
+ # The URL is the link's own text, so a terminal without hyperlinks
+ # still shows something to copy.
+ err_console.print(
+ f"\n [dim]{escape(hint.text)} {escape(hint.action)}\n"
+ f" See how: [link={url}]{escape(url)}[/link][/dim]",
+ # No syntax colouring inside a dim line, and one link, not one per token.
+ highlight=False,
+ )
+ _shown_this_run = True
+ _mark_shown(hint_id, datetime.now(UTC))
+ with contextlib.suppress(Exception):
+ from repowise.cli.platform import telemetry
+
+ telemetry.add_command_outcome(hint_shown=hint_id)
+ return True
+ except Exception:
+ return False
diff --git a/packages/cli/src/repowise/cli/main.py b/packages/cli/src/repowise/cli/main.py
index b0a520a1e..fc3bcb1a3 100644
--- a/packages/cli/src/repowise/cli/main.py
+++ b/packages/cli/src/repowise/cli/main.py
@@ -98,6 +98,7 @@ _OSS_COMMANDS: tuple[tuple[str, str], ...] = (
("wiki-styles", "restyle_cmd:wiki_styles_command"),
("whats-new", "whats_new_cmd:whats_new_command"),
("telemetry", "telemetry_cmd:telemetry_command"),
+ ("config", "config_cmd:config_command"),
("publish", "publish_cmd:publish_command"),
("login", "login_cmd:login_command"),
("logout", "login_cmd:logout_command"),
diff --git a/tests/unit/cli/test_hints.py b/tests/unit/cli/test_hints.py
new file mode 100644
index 000000000..85552dfb3
--- /dev/null
+++ b/tests/unit/cli/test_hints.py
@@ -0,0 +1,195 @@
+"""The repowise.dev hints: when they show, what they say, where they link.
+
+What protects the user: at most one line per run on stderr, each hint at most
+once a week, never for agents, daemons, CI, JSON output or signed-in users,
+and every way to turn them off works.
+"""
+
+from __future__ import annotations
+
+import io
+import time
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from unittest import mock
+from urllib.parse import parse_qs, urlparse
+
+import click
+import pytest
+from click.testing import CliRunner
+from rich.console import Console
+
+from repowise.cli import hints
+from repowise.cli.platform import credentials, store
+from repowise.cli.platform.telemetry import environment
+
+
+def stderr(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> io.StringIO:
+ """A terminal-like stderr outside CI, signed out, with a fresh store."""
+ monkeypatch.setattr(credentials, "_path", lambda: tmp_path / "credentials.json")
+ monkeypatch.setattr(store, "_path", lambda: tmp_path / "platform.json")
+ store.update(anon_id="abc123def456")
+ for var in ("REPOWISE_NO_HINTS", "DO_NOT_TRACK", "REPOWISE_TELEMETRY_DISABLED"):
+ monkeypatch.delenv(var, raising=False)
+ monkeypatch.setattr(environment, "is_ci", lambda: False)
+ monkeypatch.setattr("sys.stderr.isatty", lambda: True, raising=False)
+ buf = io.StringIO()
+ import repowise.cli.helpers as helpers
+
+ monkeypatch.setattr(helpers, "err_console", Console(file=buf, width=300, highlight=False))
+ monkeypatch.setattr(hints, "_shown_this_run", False)
+ return buf
+
+
+def _url(text: str) -> str:
+ return next(w for w in text.split() if w.startswith("https://repowise.dev/hosted"))
+
+
+class TestShowing:
+ def test_shows_the_line_its_action_and_its_link(self, stderr, monkeypatch):
+ from repowise.cli.platform import telemetry
+
+ recorded: dict = {}
+ monkeypatch.setattr(telemetry, "add_command_outcome", lambda **f: recorded.update(f))
+
+ assert hints.maybe_hint("init_success") is True
+
+ out = stderr.getvalue()
+ assert "Use this repo from Claude.ai or ChatGPT, or share it with your team." in out
+ assert "Publish it free: repowise publish" in out
+ url = urlparse(_url(out))
+ assert url.path == "/hosted" and url.fragment == "mcp"
+ assert parse_qs(url.query) == {"src": ["cli_init_success"]}
+ assert recorded == {"hint_shown": "init_success"}
+
+ def test_link_has_no_install_id_with_telemetry_off(self, stderr, monkeypatch):
+ monkeypatch.setenv("REPOWISE_TELEMETRY_DISABLED", "1")
+ hints.maybe_hint("slow_update")
+ assert parse_qs(urlparse(_url(stderr.getvalue())).query) == {"src": ["cli_slow_update"]}
+
+ def test_one_hint_per_run(self, stderr):
+ assert hints.maybe_hint("init_success")
+ assert not hints.maybe_hint("slow_update")
+ assert "Skip manual updates" not in stderr.getvalue()
+
+ def test_once_a_week_per_hint(self, stderr, monkeypatch):
+ assert hints.maybe_hint("slow_update")
+ monkeypatch.setattr(hints, "_shown_this_run", False)
+ assert not hints.maybe_hint("slow_update")
+
+ week_ago = (datetime.now(UTC) - timedelta(days=7, minutes=1)).isoformat()
+ store.update(hints_shown={"slow_update": week_ago})
+ assert hints.maybe_hint("slow_update")
+
+ def test_another_hint_is_not_blocked_by_the_week(self, stderr, monkeypatch):
+ assert hints.maybe_hint("slow_update")
+ monkeypatch.setattr(hints, "_shown_this_run", False)
+ assert hints.maybe_hint("init_success")
+
+
+class TestNeverShown:
+ @pytest.mark.parametrize("var", ["REPOWISE_NO_HINTS", "DO_NOT_TRACK"])
+ def test_env_switches(self, stderr, monkeypatch, var):
+ monkeypatch.setenv(var, "1")
+ assert not hints.maybe_hint("init_success")
+ assert stderr.getvalue() == ""
+
+ def test_config_switch(self, stderr):
+ result = CliRunner().invoke(_cli(), ["config", "hints", "off"])
+ assert result.exit_code == 0, result.output
+ assert not hints.maybe_hint("init_success")
+ CliRunner().invoke(_cli(), ["config", "hints", "on"])
+ assert hints.maybe_hint("init_success")
+
+ def test_ci(self, stderr, monkeypatch):
+ monkeypatch.setattr(environment, "is_ci", lambda: True)
+ assert not hints.maybe_hint("init_success")
+
+ def test_not_a_terminal(self, stderr, monkeypatch):
+ monkeypatch.setattr("sys.stderr.isatty", lambda: False, raising=False)
+ assert not hints.maybe_hint("init_success")
+
+ def test_json_output(self, stderr):
+ assert not hints.maybe_hint("init_success", fmt="json")
+
+ def test_signed_in(self, stderr):
+ credentials.save(
+ {"token_kind": "api_key", "access_token": "rw_live_x", "expires": time.time()}
+ )
+ assert not hints.maybe_hint("init_success")
+
+ @pytest.mark.parametrize("command", ["mcp", "serve", "watch", "hook", "augment"])
+ def test_agent_daemon_and_hook_commands(self, stderr, command):
+ @click.group()
+ def root() -> None:
+ pass
+
+ shown: list[bool] = []
+
+ @root.command(name=command)
+ def sub() -> None:
+ # CliRunner swaps stderr for a pipe; make it a terminal again so
+ # only the command name can stop the hint.
+ with mock.patch("sys.stderr.isatty", return_value=True):
+ shown.append(hints.maybe_hint("slow_update"))
+
+ @root.command(name="update")
+ def other() -> None:
+ with mock.patch("sys.stderr.isatty", return_value=True):
+ shown.append(hints.maybe_hint("slow_update"))
+
+ CliRunner().invoke(root, [command])
+ assert shown == [False]
+ CliRunner().invoke(root, ["update"])
+ assert shown == [False, True]
+
+ def test_unknown_hint(self, stderr):
+ assert not hints.maybe_hint("nope")
+
+
+class TestWording:
+ def test_every_hint_ends_with_a_free_publish_step(self):
+ for hint in hints.HINTS.values():
+ assert hint.action.endswith("repowise publish")
+ assert hint.action.split(":")[0] in {"Publish it free", "Start free"}
+
+ def test_one_next_step_per_line(self):
+ # publish signs the person in, so a second command would only compete.
+ for hint in hints.HINTS.values():
+ assert f"{hint.text} {hint.action}".count("repowise ") == 1
+
+ def test_trial_claims_name_the_card(self):
+ for hint in hints.HINTS.values():
+ text = f"{hint.text} {hint.action}".lower()
+ if "trial" in text or "10 days" in text or "private" in text:
+ assert "free for 10 days, card required" in text
+
+ def test_moments_exist_on_the_story_page(self):
+ moments = {"sync", "mcp", "bot", "security", "link", "team", "keys"}
+ assert {h.moment for h in hints.HINTS.values()} <= moments
+ assert all(h.src.startswith("cli_") for h in hints.HINTS.values())
+
+
+class TestPlacement:
+ def test_init_picks_the_large_repo_hint_for_big_or_fast_runs(self):
+ from repowise.cli.commands.init_cmd.reporting import completion_hint
+
+ assert completion_hint("standard", 999) == "init_success"
+ assert completion_hint("standard", 1000) == "large_repo"
+ assert completion_hint("fast", 10) == "large_repo"
+
+ @pytest.mark.parametrize(("elapsed", "expected"), [(59.0, []), (61.0, ["slow_update"])])
+ def test_update_hints_only_when_slow(self, monkeypatch, elapsed, expected):
+ from repowise.cli.commands.update_cmd import reporting
+
+ asked: list[str] = []
+ monkeypatch.setattr(hints, "maybe_hint", lambda hint_id, **kw: asked.append(hint_id))
+ reporting._slow_update_hint(elapsed)
+ assert asked == expected
+
+
+def _cli():
+ from repowise.cli.main import cli
+
+ return cli
diff --git a/tests/unit/cli/test_lazy_commands.py b/tests/unit/cli/test_lazy_commands.py
index a93152262..15fe3d1cf 100644
--- a/tests/unit/cli/test_lazy_commands.py
+++ b/tests/unit/cli/test_lazy_commands.py
@@ -33,7 +33,7 @@ from repowise.core.registry import CLIRegistry, LazyCommand
#: command is meant to require editing it.
_EXPECTED_NAMES = frozenset(
{
- "agents", "ask", "augment", "context", "corrections", "costs", "coverage",
+ "agents", "ask", "augment", "config", "context", "corrections", "costs", "coverage",
"dead-code", "decision", "delete", "distill", "doc-drift", "doctor",
"expand",
"export", "generate", "generate-claude-md", "health", "hook",