workstream-cli 0.0.1__py3-none-any.whl

workstream/ARCHITECTURE.md

@@ -0,0 +1,89 @@
+# ws Architecture
+
+ws is a workstream manager — it tracks trains of thought spanning projects and time.
+Data lives as markdown files in `_Workstreams/`, each with YAML frontmatter and a markdown body.
+
+## Execution Modes
+
+ws operates in four distinct modes depending on who initiates the call and how results are consumed.
+
+| Mode       | Who drives       | LLM involved | ws lifetime        | Examples                                          |
+|------------|------------------|--------------|--------------------|----------------------------------------------------|
+| **direct** | User via CLI     | No           | Runs and exits     | `ws list`, `ws stale`, `ws next`, `ws report`, `ws show` |
+| **handoff**| User via CLI     | Yes (omp)    | Execs into omp     | `ws review`, `ws sweep --review-plans`, `ws init` bootstrap |
+| **batch**  | User via CLI     | Yes (loop)   | Stays alive        | `ws sweep --discover`, `ws sweep --review-plans --batch`, summary backfill |
+| **tool**   | Agent in omp     | Already running | Runs and exits  | Agent runs `ws stale`, `ws show`, etc. as tool calls |
+
+### Direct
+
+Deterministic CLI commands. Pure Python, no LLM. Read workstream files, compute, print.
+
+### Handoff
+
+ws gathers context, writes a manifest to a temp file, then **replaces itself** via `os.execv` into an omp/claude harness process. The harness receives the manifest as `--append-system-prompt` and a skill directive. After exec, ws is gone — the harness owns the session.
+
+### Batch
+
+ws orchestrates repeated LLM calls in a loop. It stays alive as the driver: sends prompts via `llm.py`, parses structured responses, writes results back to workstream files. Used for bulk operations where interactive review is unnecessary.
+
+### Tool
+
+The user is already inside an omp session. The agent calls ws CLI commands as tools. ws is a passive data source — it reads, computes, prints, and exits. No handoff occurs.
+
+## Recursion Guard
+
+When a handoff command is invoked from **within** an existing omp session (tool mode), ws must not exec into a second harness. Detection: check for `$OMPCODE=1` or `$CLAUDECODE=1` environment variables. When detected, print the context manifest to stdout instead of calling `os.execv`. See `commands/sweep.py` for the handoff path.
+
+## Data Model
+
+All types live in `models.py`. No I/O — pure dataclasses and helpers.
+
+| Type            | Description                                              |
+|-----------------|----------------------------------------------------------|
+| `Workstream`    | Top-level entity: id, title, status, size, tags, repos, timestamps, thread, plans, branches, next_actions, log, thoughts, ideas, decisions, summary |
+| `ThreadEntry`   | Timestamped narrative entry in a workstream's thread     |
+| `ThoughtEntry`  | Captured thought with timestamp and content              |
+| `IdeaEntry`     | Idea with timestamp and content                          |
+| `PlanRef`       | Reference to a plan file: path, id, optional workstream  |
+| `BranchRef`     | Reference to a git branch: name, repo, optional dates    |
+| `LogEntry`      | Timestamped structured log entry (action + detail)       |
+
+Serialization to/from markdown+YAML frontmatter is handled by `markdown.py`.
+
+## Key Modules
+
+| Module              | Responsibility                                                        |
+|---------------------|-----------------------------------------------------------------------|
+| `cli.py`            | Entry point, face `Command` tree, middleware for config loading        |
+| `config.py`         | Config discovery (`$WS_DIR`, walk-up, global pointer), LLM detection  |
+| `models.py`         | Dataclasses for all entities. Pure data + helpers, no I/O             |
+| `markdown.py`       | YAML frontmatter round-trip, section-level read/write                 |
+| `llm.py`            | LLM shell-out abstraction — detect and invoke CLI-based LLM agents    |
+| `git.py`            | Thin subprocess wrappers for branch and commit queries                |
+| `repo_discovery.py` | Scan directories for git repos, build activity index                  |
+| `sweep_state.py`    | Persistent state for sweep deduplication across runs                  |
+| `thoughts.py`       | Thought/snooze computation helpers                                    |
+| `web.py`            | Live web dashboard                                                    |
+
+### Commands (`commands/`)
+
+| Command       | Mode     | What it does                                              |
+|---------------|----------|-----------------------------------------------------------|
+| `init`        | handoff  | First-time setup, install harness skills, optional bootstrap |
+| `list_cmd`    | direct   | Tabular listing of workstreams                            |
+| `show`        | direct   | Display a single workstream by id prefix                  |
+| `stale`       | direct   | Find workstreams that need attention                      |
+| `next_cmd`    | direct   | Prioritized active workstreams by staleness               |
+| `report`      | direct   | Activity report across workstreams                        |
+| `sweep`       | all four | Scan repos, discover/review plans, batch or interactive   |
+| `backfill`    | batch    | Add IDs and infer associations for plan files             |
+| `checkin`     | direct   | Record a check-in on a workstream                         |
+| `new`         | direct   | Create a new workstream                                   |
+| `idea`        | direct   | Idea capture, listing, promotion                          |
+| `snooze`      | direct   | Snooze/wake workstreams                                   |
+| `nest`        | direct   | Workstream hierarchy (nest/unnest)                        |
+| `tree`        | direct   | ASCII tree of workstream hierarchy                        |
+| `index`       | direct   | Generate index.md for the workstreams directory           |
+| `serve`       | direct   | Live web dashboard server                                 |
+| `setup`       | direct   | Validate installation health, optionally fix              |
+| `cron`        | direct   | Set up periodic sweep in user crontab                     |

workstream/__init__.py

@@ -0,0 +1,8 @@
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version('workstream')
+except PackageNotFoundError:
+    __version__ = '0.1.0-dev'
+
+__all__ = ['__version__']

workstream/cli.py

@@ -0,0 +1,136 @@
+"""ws CLI entry point and shared helpers."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from face import Command, CommandLineError, UsageError, face_middleware
+
+from workstream.config import Config, apply_timezone, load_config
+from workstream.markdown import load_workstream
+from workstream.models import Workstream, slugify
+
+
+# Files that live in the workstream directory but aren't workstream files.
+_SKIP_FILES = frozenset(('index.md', 'inbox.md', 'dashboard.html'))
+
+
+def load_all_workstreams(ws_dir: Path) -> list[Workstream]:
+    """Load every workstream from *ws_dir*, skipping non-workstream files."""
+    result: list[Workstream] = []
+    for f in sorted(ws_dir.glob('*.md')):
+        if f.name in _SKIP_FILES:
+            continue
+        try:
+            result.append(load_workstream(f))
+        except Exception:
+            continue
+    return result
+
+
+def resolve_workstream(config: Config, id_prefix: str) -> Workstream:
+    """Find the unique workstream matching *id_prefix*.
+
+    Matches against full ID, hex suffix, any prefix/suffix of the ID,
+    or title slug prefix. Raises ``UsageError`` on zero or multiple matches.
+    """
+    ws_dir = config.workstreams_path
+    matches: list[Workstream] = []
+    for ws in load_all_workstreams(ws_dir):
+        # Match: full ID prefix, full ID suffix, hex-suffix prefix, or slug prefix
+        hex_suffix = ws.id.split('-', 3)[-1]  # e.g. 'a1b2c3d4e5'
+        slug = slugify(ws.title)
+        if (ws.id.startswith(id_prefix)
+                or ws.id.endswith(id_prefix)
+                or hex_suffix.startswith(id_prefix)
+                or slug.startswith(id_prefix)):
+            matches.append(ws)
+
+    if len(matches) == 0:
+        raise UsageError(f'No workstream matching "{id_prefix}"')
+    if len(matches) > 1:
+        names = ', '.join(f'{w.id} ({w.title})' for w in matches)
+        raise UsageError(f'Multiple matches for "{id_prefix}": {names}')
+    return matches[0]
+
+
+# ---------------------------------------------------------------------------
+# Middleware: resolve config via --dir flag / env var / auto-discovery
+# ---------------------------------------------------------------------------
+
+@face_middleware(provides=['config'], optional=True)
+def mw_load_config(next_, dir):
+    """Resolve workstreams dir from --dir flag, $WS_DIR, or auto-discovery."""
+    if dir:
+        ws_dir = Path(dir).expanduser().resolve()
+        # Accept both notes root (parent dir) and direct _Workstreams path
+        candidate = ws_dir / '_Workstreams'
+        if candidate.is_dir():
+            ws_dir = candidate
+        elif not ws_dir.is_dir():
+            # CommandLineError from middleware doesn't get printed by face's
+            # run loop; print explicitly so the user sees the message.
+            print(f'error: --dir: directory does not exist: {ws_dir}', file=sys.stderr)
+            raise SystemExit(1)
+        config = load_config(ws_dir_override=ws_dir)
+    else:
+        config = load_config()
+        # Guard: if we resolved a workstreams dir but it has no config.yaml,
+        # the pointer is stale or WS_DIR is pointing at the wrong directory.
+        if config.workstreams_dir:
+            ws_path = Path(config.workstreams_dir)
+            if ws_path.is_dir() and not (ws_path / 'config.yaml').exists():
+                raise UsageError(
+                    f'Directory {str(ws_path)!r} has no workstream config (config.yaml).\n'
+                    f"Is $WS_DIR set correctly? Run 'ws init' to initialize."
+                )
+    apply_timezone(config)
+    return next_(config=config)
+
+
+def build_command() -> Command:
+    """Construct the top-level ``ws`` command with all subcommands."""
+    cmd = Command(None, name='ws', doc='Workstream manager \u2014 track trains of thought across projects.')
+    cmd.add('--dir', parse_as=str, missing=None,
+            doc='Workstreams directory (or parent); overrides $WS_DIR and auto-discovery')
+    cmd.add(mw_load_config)
+
+    from workstream.commands import init, new, list_cmd, show, report, index, next_cmd, stale, sweep, serve, backfill, cron, nest, tree, snooze, idea, checkin, setup, inspect_cmd, review, block, focus_cmd, resume, update_status
+
+    cmd.add(init.get_command())
+    cmd.add(new.get_command())
+    cmd.add(list_cmd.get_command())
+    cmd.add(show.get_command())
+    cmd.add(report.get_command())
+    cmd.add(index.get_command())
+    cmd.add(next_cmd.get_command())
+    cmd.add(stale.get_command())
+    cmd.add(sweep.get_command())
+    cmd.add(serve.get_command())
+    cmd.add(backfill.get_command())
+    cmd.add(cron.get_command())
+    cmd.add(nest.get_nest_command())
+    cmd.add(nest.get_unnest_command())
+    cmd.add(tree.get_command())
+    cmd.add(snooze.get_command())
+    cmd.add(snooze.get_wake_command())
+    cmd.add(idea.get_idea_command())
+    cmd.add(idea.get_ideas_command())
+    cmd.add(idea.get_promote_command())
+    cmd.add(checkin.get_command())
+    cmd.add(inspect_cmd.get_command())
+    cmd.add(setup.get_command())
+    cmd.add(review.get_command())
+    cmd.add(block.get_command())
+    cmd.add(block.get_unblock_command())
+    cmd.add(focus_cmd.get_command())
+    cmd.add(resume.get_command())
+    cmd.add(update_status.get_command())
+    return cmd
+
+
+def main() -> None:
+    """CLI entry point."""
+    cmd = build_command()
+    cmd.run()

workstream/commands/backfill.py

@@ -0,0 +1,139 @@
+"""ws backfill — add IDs and infer workstream associations for .plans/ files."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from face import Command
+
+from workstream.config import Config
+from workstream.cli import load_all_workstreams
+from workstream.markdown import parse_frontmatter, write_frontmatter
+from workstream.models import ACTIVE_STATUSES, generate_id, slugify
+
+
+def _load_active_workstreams(config):
+    """Load active workstreams from the configured directory."""
+    return [ws for ws in load_all_workstreams(config.workstreams_path)
+            if ws.status in ACTIVE_STATUSES]
+
+
+def _slug_overlap(plan_slug: str, ws_slug: str) -> bool:
+    """Check if plan slug shares meaningful tokens with workstream slug."""
+    plan_parts = set(plan_slug.split('-'))
+    ws_parts = set(ws_slug.split('-'))
+    # Remove trivially short tokens (single chars, empty)
+    plan_parts = {p for p in plan_parts if len(p) > 1}
+    ws_parts = {p for p in ws_parts if len(p) > 1}
+    if not plan_parts or not ws_parts:
+        return False
+    return bool(plan_parts & ws_parts)
+
+
+def _infer_workstream(repo_name: str, plan_slug: str, workstreams):
+    """Try to infer the workstream for a plan.
+
+    Returns the workstream ID if exactly one active workstream matches
+    by repo AND has title/slug overlap. Returns None otherwise.
+    """
+    candidates = []
+    for ws in workstreams:
+        if repo_name not in ws.repos:
+            continue
+        ws_slug = slugify(ws.title)
+        if _slug_overlap(plan_slug, ws_slug):
+            candidates.append(ws)
+    if len(candidates) == 1:
+        return candidates[0].id
+    return None
+
+
+def _backfill_handler(config: Config, dry_run: bool = False) -> None:
+    workstreams = _load_active_workstreams(config)
+
+    total_plans = 0
+    ids_added = 0
+    ws_associated = 0
+
+    for repo_cfg in config.repos:
+        repo_path = Path(repo_cfg.path).expanduser()
+        plans_dir = config.get_plans_dir(repo_cfg.name, repo_path)
+        if not plans_dir.is_dir():
+            continue
+
+        for plan_file in sorted(plans_dir.glob('*.md')):
+            total_plans += 1
+            try:
+                text = plan_file.read_text(encoding='utf-8')
+                meta, body = parse_frontmatter(text)
+            except Exception as exc:
+                print(f'  warning: skipping {repo_cfg.name}/{plan_file.name}: {exc}')
+                continue
+
+            changed = False
+            plan_id = meta.get('id', '')
+            title = meta.get('title', plan_file.stem)
+            plan_slug = slugify(title)
+
+            # Step b/c: ensure plan has an ID and filename matches
+            if not plan_id:
+                plan_id = generate_id()
+                meta['id'] = plan_id
+                changed = True
+                ids_added += 1
+                if dry_run:
+                    print(f'  would add id {plan_id} to {repo_cfg.name}/{plan_file.name}')
+
+            # Determine canonical filename
+            canonical_name = f'{plan_id}-{plan_slug}.md'
+            needs_rename = plan_file.name != canonical_name
+
+            # Step d: infer workstream if empty
+            ws_field = meta.get('workstream', '')
+            if not ws_field:
+                inferred = _infer_workstream(repo_cfg.name, plan_slug, workstreams)
+                if inferred:
+                    meta['workstream'] = inferred
+                    changed = True
+                    ws_associated += 1
+                    if dry_run:
+                        print(f'  would set workstream={inferred} on {repo_cfg.name}/{plan_file.name}')
+
+            if not changed and not needs_rename:
+                continue
+
+            if dry_run:
+                if needs_rename:
+                    print(f'  would rename {repo_cfg.name}/{plan_file.name} -> {canonical_name}')
+                continue
+
+            # Write updated frontmatter
+            new_text = write_frontmatter(meta, body)
+
+            if needs_rename:
+                new_path = plans_dir / canonical_name
+                if new_path.exists() and new_path != plan_file:
+                    print(f'  warning: cannot rename {plan_file.name} -> {canonical_name}: target exists')
+                    # Still write updated metadata to the original file
+                    plan_file.write_text(new_text, encoding='utf-8')
+                else:
+                    plan_file.write_text(new_text, encoding='utf-8')
+                    if new_path != plan_file:
+                        plan_file.rename(new_path)
+                        print(f'  renamed {repo_cfg.name}/{plan_file.name} -> {canonical_name}')
+            else:
+                plan_file.write_text(new_text, encoding='utf-8')
+
+    label = 'Would process' if dry_run else 'Processed'
+    print(f'Backfill {"(dry run) " if dry_run else ""}complete: '
+          f'{total_plans} plans {label.lower()}, '
+          f'{ids_added} IDs added, '
+          f'{ws_associated} workstream associations made.')
+
+
+def get_command() -> Command:
+    cmd = Command(_backfill_handler, name='backfill',
+                  doc='Add IDs and infer workstream associations for .plans/ files.')
+    cmd.add('--dry-run', parse_as=True,
+            doc='Show what would be done without modifying files.')
+    return cmd

workstream/commands/block.py

@@ -0,0 +1,93 @@
+"""ws block / ws unblock — block and unblock workstreams."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from face import Command, CommandLineError
+
+from workstream.cli import resolve_workstream
+from workstream.config import Config
+from workstream.markdown import (
+    load_workstream,
+    parse_frontmatter,
+    write_frontmatter,
+    append_log_entry,
+)
+from workstream.models import LogEntry
+
+
+def _block_handler(posargs_: tuple, config: Config) -> None:
+    if not posargs_:
+        raise CommandLineError('Usage: ws block <id-prefix> [reason...]')
+
+    id_prefix = posargs_[0]
+    reason = ' '.join(posargs_[1:]) if len(posargs_) > 1 else ''
+
+    ws = resolve_workstream(config, id_prefix)
+
+    # Re-load fresh from disk to avoid stale state.
+    ws = load_workstream(ws.source_path)
+    today = datetime.now().strftime('%Y-%m-%d')
+
+    ws.status = 'blocked'
+    ws.blocked_notes = reason
+    ws.updated = today
+
+    # Read raw text, update frontmatter, append log entry, write back.
+    text = ws.source_path.read_text(encoding='utf-8')
+    meta, body = parse_frontmatter(text)
+    meta.update(ws.frontmatter_dict())
+    detail = reason if reason else ''
+    body = append_log_entry(body, LogEntry(date=today, event='blocked', detail=detail))
+    out = write_frontmatter(meta, body)
+    ws.source_path.write_text(out.rstrip('\n') + '\n', encoding='utf-8')
+
+    if reason:
+        print(f"Blocked '{ws.title}': {reason}")
+    else:
+        print(f"Blocked '{ws.title}'")
+
+
+def _unblock_handler(posargs_: tuple, config: Config) -> None:
+    if len(posargs_) != 1:
+        raise CommandLineError('Usage: ws unblock <id-prefix>')
+
+    id_prefix = posargs_[0]
+    ws = resolve_workstream(config, id_prefix)
+
+    # Re-load fresh from disk.
+    ws = load_workstream(ws.source_path)
+    today = datetime.now().strftime('%Y-%m-%d')
+
+    ws.status = 'active'
+    ws.blocked_notes = ''
+    ws.updated = today
+
+    # Read raw text, update frontmatter, append log entry, write back.
+    text = ws.source_path.read_text(encoding='utf-8')
+    meta, body = parse_frontmatter(text)
+    meta.update(ws.frontmatter_dict())
+    # Explicitly remove cleared blocked_notes (frontmatter_dict omits empty values)
+    meta.pop('blocked_notes', None)
+    body = append_log_entry(body, LogEntry(date=today, event='unblocked'))
+    out = write_frontmatter(meta, body)
+    ws.source_path.write_text(out.rstrip('\n') + '\n', encoding='utf-8')
+
+    print(f"Unblocked '{ws.title}' ({ws.id})")
+
+
+def get_command() -> Command:
+    return Command(
+        _block_handler, name='block',
+        doc='Block a workstream (stuck on external dependency).',
+        posargs=True,
+    )
+
+
+def get_unblock_command() -> Command:
+    return Command(
+        _unblock_handler, name='unblock',
+        doc='Unblock a workstream.',
+        posargs=True,
+    )

workstream/commands/checkin.py

@@ -0,0 +1,51 @@
+"""ws checkin — record a check-in on a workstream."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from face import Command, CommandLineError
+
+from workstream.cli import resolve_workstream
+from workstream.config import Config
+from workstream.markdown import (
+    load_workstream, parse_frontmatter, write_frontmatter, append_log_entry,
+)
+from workstream.models import LogEntry
+
+
+def _checkin_handler(posargs_: tuple, config: Config) -> None:
+    if not posargs_:
+        raise CommandLineError('Usage: ws checkin <id-prefix> [note...]')
+
+    id_prefix = posargs_[0]
+    note = ' '.join(posargs_[1:]) if len(posargs_) > 1 else ''
+
+    ws = resolve_workstream(config, id_prefix)
+    # Re-load fresh from disk
+    ws = load_workstream(ws.source_path)
+
+    now_dt = datetime.now().isoformat(timespec='seconds')
+    today_date = datetime.now().strftime('%Y-%m-%d')
+
+    # Read raw text for body manipulation
+    text = ws.source_path.read_text(encoding='utf-8')
+    meta, body = parse_frontmatter(text)
+    meta['updated'] = now_dt
+    meta['last_activity'] = now_dt
+
+    entry = LogEntry(date=today_date, event='checked-in', detail=note)
+    body = append_log_entry(body, entry)
+
+    ws.source_path.write_text(
+        write_frontmatter(meta, body), encoding='utf-8'
+    )
+    if note:
+        print(f"Checked in on '{ws.title}': {note}")
+    else:
+        print(f"Checked in on '{ws.title}'")
+
+
+def get_command() -> Command:
+    return Command(_checkin_handler, name='checkin',
+                   doc='Record a check-in with optional note.', posargs=True)

workstream/commands/cron.py

@@ -0,0 +1,119 @@
+"""ws cron — set up periodic sweep in user crontab."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import os
+from pathlib import Path
+
+from face import Command
+
+
+_CRON_COMMENT = '# workstream: periodic sweep'
+
+
+def _find_ws_path() -> str:
+    """Find the ``ws`` binary on PATH."""
+    path = shutil.which('ws')
+    if path:
+        return path
+    # Fallback: invoke via python module
+    return 'python3 -m workstream.cli'
+
+
+def _sweep_log_path() -> str:
+    """Return XDG-compliant path for the sweep log file."""
+    state_dir = os.environ.get('XDG_STATE_HOME', '')
+    if not state_dir:
+        state_dir = str(Path.home() / '.local' / 'state')
+    return str(Path(state_dir) / 'workstream' / 'sweep.log')
+
+
+def _build_cron_line(interval: str, thoughts: bool) -> str:
+    """Build the crontab line for the given interval."""
+    ws_path = _find_ws_path()
+    thoughts_flag = ' --thoughts' if thoughts else ''
+
+    # Cron schedules
+    schedules = {
+        'hourly': '0 * * * *',
+        'daily': '0 9 * * *',
+        'weekly': '0 9 * * 1',
+    }
+    schedule = schedules.get(interval, schedules['daily'])
+
+    log_path = _sweep_log_path()
+    log_dir = str(Path(log_path).parent)
+    return f'{schedule} mkdir -p {log_dir} && {ws_path} sweep{thoughts_flag} >> {log_path} 2>&1'
+
+
+def _get_current_crontab() -> str:
+    """Read current user crontab, returning '' if empty."""
+    result = subprocess.run(
+        ['crontab', '-l'], capture_output=True, text=True, timeout=10
+    )
+    if result.returncode != 0:
+        return ''
+    return result.stdout
+
+
+def _cron_handler(interval: str = 'daily', thoughts: bool = False,
+                  install: bool = False, remove: bool = False) -> None:
+    cron_line = _build_cron_line(interval, thoughts)
+
+    if remove:
+        current = _get_current_crontab()
+        if _CRON_COMMENT not in current:
+            print('No workstream cron entry found.')
+            return
+        # Remove our lines
+        lines = current.splitlines()
+        new_lines = [l for l in lines if _CRON_COMMENT not in l and 'ws sweep' not in l]
+        new_crontab = '\n'.join(new_lines) + '\n'
+        result = subprocess.run(
+            ['crontab', '-'], input=new_crontab, capture_output=True, text=True, timeout=10
+        )
+        if result.returncode == 0:
+            print('Removed workstream cron entry.')
+        else:
+            print(f'Failed to update crontab: {result.stderr}')
+        return
+
+    if install:
+        current = _get_current_crontab()
+        # Remove any existing workstream entry first
+        lines = current.splitlines()
+        lines = [l for l in lines if _CRON_COMMENT not in l and 'ws sweep' not in l]
+
+        lines.append(_CRON_COMMENT)
+        lines.append(cron_line)
+        new_crontab = '\n'.join(lines) + '\n'
+
+        result = subprocess.run(
+            ['crontab', '-'], input=new_crontab, capture_output=True, text=True, timeout=10
+        )
+        if result.returncode == 0:
+            print(f'Installed cron entry ({interval}):')
+            print(f'  {cron_line}')
+        else:
+            print(f'Failed to install crontab: {result.stderr}')
+        return
+
+    # Default: just print what would be added
+    print(f'Cron entry ({interval}):')
+    print(f'  {cron_line}')
+    print()
+    print('To install, run: ws cron --install')
+    print('To install with thoughts sweep: ws cron --install --thoughts')
+    print('To remove: ws cron --remove')
+
+
+def get_command() -> Command:
+    cmd = Command(_cron_handler, name='cron', doc='Set up periodic sweep via crontab.')
+    cmd.add('--interval', parse_as=str, missing='daily',
+            doc='Sweep frequency: hourly, daily, weekly (default: daily)')
+    cmd.add('--thoughts', parse_as=True, doc='Include --thoughts flag in sweep')
+    cmd.add('--install', parse_as=True, doc='Install the cron entry')
+    cmd.add('--remove', parse_as=True, doc='Remove the workstream cron entry')
+    return cmd