agent-cli 0.70.4__py3-none-any.whl → 0.71.0__py3-none-any.whl

agent_cli/agents/transcribe_daemon.py

@@ -296,45 +296,45 @@ def transcribe_daemon(  # noqa: PLR0912
         "user",
         "--role",
         "-r",
-        help="Role name for logging (e.g., 'meeting', 'notes', 'user').",
+        help="Label for log entries. Use to distinguish speakers or contexts in logs.",
     ),
     silence_threshold: float = typer.Option(
         1.0,
         "--silence-threshold",
         "-s",
-        help="Seconds of silence to end a speech segment.",
+        help="Seconds of silence after speech to finalize a segment. Increase for slower speakers.",
     ),
     min_segment: float = typer.Option(
         0.25,
         "--min-segment",
         "-m",
-        help="Minimum speech duration in seconds to trigger a segment.",
+        help="Minimum seconds of speech required before a segment is processed. Filters brief sounds.",
     ),
     vad_threshold: float = typer.Option(
         0.3,
         "--vad-threshold",
-        help="VAD speech detection threshold (0.0-1.0). Higher = more aggressive filtering.",
+        help="Silero VAD confidence threshold (0.0-1.0). Higher values require clearer speech; lower values are more sensitive to quiet/distant voices.",
     ),
     save_audio: bool = typer.Option(
         True,  # noqa: FBT003
         "--save-audio/--no-save-audio",
-        help="Save audio segments as MP3 files.",
+        help="Save each speech segment as MP3. Requires `ffmpeg` to be installed.",
     ),
     audio_dir: Path | None = typer.Option(  # noqa: B008
         None,
         "--audio-dir",
-        help="Directory for MP3 files. Default: ~/.config/agent-cli/audio",
+        help="Base directory for MP3 files. Files are organized by date: `YYYY/MM/DD/HHMMSS_mmm.mp3`. Default: `~/.config/agent-cli/audio`.",
     ),
     transcription_log: Path | None = typer.Option(  # noqa: B008
         None,
         "--transcription-log",
         "-t",
-        help="JSON Lines log file path. Default: ~/.config/agent-cli/transcriptions.jsonl",
+        help="JSONL file for transcript logging (one JSON object per line with timestamp, role, raw/processed text, audio path). Default: `~/.config/agent-cli/transcriptions.jsonl`.",
     ),
     clipboard: bool = typer.Option(
         False,  # noqa: FBT003
         "--clipboard/--no-clipboard",
-        help="Copy each transcription to clipboard.",
+        help="Copy each completed transcription to clipboard (overwrites previous). Useful with `--llm` to get cleaned text.",
     ),
     # --- Provider Selection ---
     asr_provider: str = opts.ASR_PROVIDER,
@@ -368,25 +368,37 @@ def transcribe_daemon(  # noqa: PLR0912
     config_file: str | None = opts.CONFIG_FILE,
     print_args: bool = opts.PRINT_ARGS,
 ) -> None:
-    """Run a continuous transcription daemon with voice activity detection.
+    """Continuous transcription daemon using Silero VAD for speech detection.
 
-    This command runs indefinitely, capturing audio from your microphone,
-    detecting speech segments using Silero VAD, transcribing them, and
-    logging results with timestamps.
+    Unlike `transcribe` (single recording session), this daemon runs indefinitely
+    and automatically detects speech segments using Voice Activity Detection (VAD).
+    Each detected segment is transcribed and logged with timestamps.
 
-    Examples:
-        # Basic daemon
-        agent-cli transcribe-daemon
+    **How it works:**
 
-        # With role and custom silence threshold
-        agent-cli transcribe-daemon --role meeting --silence-threshold 1.5
+    1. Listens continuously to microphone input
+    2. Silero VAD detects when you start/stop speaking
+    3. After `--silence-threshold` seconds of silence, the segment is finalized
+    4. Segment is transcribed (and optionally cleaned by LLM with `--llm`)
+    5. Results are appended to the JSONL log file
+    6. Audio is saved as MP3 if `--save-audio` is enabled (requires `ffmpeg`)
+
+    **Use cases:** Meeting transcription, note-taking, voice journaling, accessibility.
 
-        # With LLM cleanup
-        agent-cli transcribe-daemon --llm --role notes
+    **Examples:**
+
+        agent-cli transcribe-daemon
+        agent-cli transcribe-daemon --role meeting --silence-threshold 1.5
+        agent-cli transcribe-daemon --llm --clipboard --role notes
+        agent-cli transcribe-daemon --transcription-log ~/meeting.jsonl --no-save-audio
+        agent-cli transcribe-daemon --asr-provider openai --llm-provider gemini --llm
 
-        # Custom log file and audio directory
-        agent-cli transcribe-daemon --transcription-log ~/meeting.jsonl --audio-dir ~/audio
+    **Tips:**
 
+    - Use `--role` to tag entries (e.g., `speaker1`, `meeting`, `personal`)
+    - Adjust `--vad-threshold` if detection is too sensitive (increase) or missing speech (decrease)
+    - Use `--stop` to cleanly terminate a running daemon
+    - With `--llm`, transcripts are cleaned up (punctuation, filler words removed)
     """
     if print_args:
         print_command_line_args(locals())

agent_cli/agents/voice_edit.py

@@ -229,15 +229,23 @@ def voice_edit(
     config_file: str | None = opts.CONFIG_FILE,
     print_args: bool = opts.PRINT_ARGS,
 ) -> None:
-    """Interact with clipboard text via a voice command using local or remote services.
-
-    Usage:
-    - Run in foreground: agent-cli voice-edit --input-device-index 1
-    - Run in background: agent-cli voice-edit --input-device-index 1 &
-    - Check status: agent-cli voice-edit --status
-    - Stop background process: agent-cli voice-edit --stop
-    - List output devices: agent-cli voice-edit --list-output-devices
-    - Save TTS to file: agent-cli voice-edit --tts --save-file response.wav
+    """Edit or query clipboard text using voice commands.
+
+    **Workflow:** Captures clipboard text → records your voice command → transcribes
+    it → sends both to an LLM → copies result back to clipboard.
+
+    Use this for hands-free text editing (e.g., "make this more formal") or
+    asking questions about clipboard content (e.g., "summarize this").
+
+    **Typical hotkey integration:** Run `voice-edit &` on keypress to start
+    recording, then send SIGINT (via `--stop`) on second keypress to process.
+
+    **Examples:**
+
+    - Basic usage: `agent-cli voice-edit`
+    - With TTS response: `agent-cli voice-edit --tts`
+    - Toggle on/off: `agent-cli voice-edit --toggle`
+    - List audio devices: `agent-cli voice-edit --list-devices`
     """
     if print_args:
         print_command_line_args(locals())

agent_cli/cli.py

@@ -14,9 +14,32 @@ from .config import load_config, normalize_provider_defaults
 from .core.process import set_process_title
 from .core.utils import console
 
+_HELP = """\
+AI-powered voice, text, and development tools.
+
+**Voice & Text:**
+
+- **Voice-to-text** - Transcribe speech with optional LLM cleanup
+- **Text-to-speech** - Convert text to natural-sounding audio
+- **Voice chat** - Conversational AI with memory and tool use
+- **Text correction** - Fix grammar, spelling, and punctuation
+
+**Development:**
+
+- **Parallel development** - Git worktrees with integrated coding agents
+- **Local servers** - ASR/TTS with Wyoming + OpenAI-compatible APIs,
+  MLX on macOS ARM, CUDA/CPU Whisper, and automatic model TTL
+
+**Provider Flexibility:**
+
+Mix local (Ollama, Wyoming) and cloud (OpenAI, Gemini) backends freely.
+
+Run `agent-cli <command> --help` for detailed command documentation.
+"""
+
 app = typer.Typer(
     name="agent-cli",
-    help="A suite of AI-powered command-line tools for text correction, audio transcription, and voice assistance.",
+    help=_HELP,
     context_settings={"help_option_names": ["-h", "--help"]},
     add_completion=True,
     rich_markup_mode="markdown",
@@ -56,7 +79,7 @@ def main(
         ),
     ] = False,
 ) -> None:
-    """A suite of AI-powered tools."""
+    """AI-powered voice, text, and development tools."""
     if ctx.invoked_subcommand is None:
         console.print("[bold red]No command specified.[/bold red]")
         console.print("[bold yellow]Running --help for your convenience.[/bold yellow]")

agent_cli/config_cmd.py

@@ -20,7 +20,17 @@ from agent_cli.core.utils import console
 
 config_app = typer.Typer(
     name="config",
-    help="Manage agent-cli configuration files.",
+    help="""Manage agent-cli configuration files.
+
+Config files are TOML format and searched in order:
+
+1. `./agent-cli-config.toml` (project-local)
+2. `~/.config/agent-cli/config.toml` (user default)
+
+Settings in `[defaults]` apply to all commands. Override per-command
+with sections like `[chat]` or `[transcribe]`. CLI arguments override
+config file settings.
+""",
     add_completion=True,
     rich_markup_mode="markdown",
     no_args_is_help=True,
@@ -40,30 +50,30 @@ CONFIG_PATH_OPTION: Path | None = typer.Option(
     None,
     "--path",
     "-p",
-    help="Path to config file. Uses auto-detection if not specified.",
+    help="Override auto-detection and use this config file path.",
 )
 CONFIG_PATH_INIT_OPTION: Path | None = typer.Option(
     None,
     "--path",
     "-p",
-    help="Custom path for config file. Default: ~/.config/agent-cli/config.toml",
+    help="Where to create the config file (default: `~/.config/agent-cli/config.toml`).",
 )
 FORCE_OPTION: bool = typer.Option(
     False,  # noqa: FBT003
     "--force",
     "-f",
-    help="Overwrite existing config without confirmation.",
+    help="Overwrite existing config without prompting for confirmation.",
 )
 RAW_OPTION: bool = typer.Option(
     False,  # noqa: FBT003
     "--raw",
     "-r",
-    help="Output raw file contents (for copy-paste).",
+    help="Print plain file contents without syntax highlighting or line numbers.",
 )
 JSON_OPTION: bool = typer.Option(
     False,  # noqa: FBT003
     "--json",
-    help="Output as JSON for automation.",
+    help="Output as JSON with `path`, `exists`, and `content` fields.",
 )
 
 
@@ -149,10 +159,13 @@ def config_init(
     path: Path | None = CONFIG_PATH_INIT_OPTION,
     force: bool = FORCE_OPTION,
 ) -> None:
-    """Create a new config file with all options commented out.
+    """Create a new config file with all options as commented-out examples.
 
-    The generated config file serves as a template showing all available
-    options. Uncomment and modify the options you want to customize.
+    Generates a TOML template with `[defaults]` for global settings and
+    command-specific sections like `[chat]`, `[transcribe]`, etc. Uncomment
+    and edit the options you want to customize.
+
+    Example: `agent-cli config init && agent-cli config edit`
     """
     target_path = _get_config_file(path) or USER_CONFIG_PATH
 
@@ -182,7 +195,9 @@ def config_edit(
 ) -> None:
     """Open the config file in your default editor.
 
-    The editor is determined by: $EDITOR > $VISUAL > platform default.
+    Editor preference: `$EDITOR` → `$VISUAL` → `nano`/`vim` → `vi` (or
+    `notepad` on Windows). If no config exists, run `agent-cli config init`
+    first.
     """
     config_file = _get_config_file(path)
 
@@ -234,7 +249,11 @@ def config_show(
     raw: bool = RAW_OPTION,
     json_output: bool = JSON_OPTION,
 ) -> None:
-    """Display the config file location and contents."""
+    """Display the active config file path and contents.
+
+    By default, shows syntax-highlighted TOML with line numbers. Use `--raw`
+    for plain output (useful for piping), or `--json` for programmatic access.
+    """
     config_file = _get_config_file(path)
 
     if config_file is None: