Metadata-Version: 2.4
Name: mahorn
Version: 0.1.0
Summary: Windows CLI task completion notification tool for AI agent collaboration
License: MIT
Requires-Python: >=3.8
Requires-Dist: pyttsx3>=2.90
Description-Content-Type: text/markdown

# Horn

> Windows CLI voice notification tool for AI agent collaboration.

Horn plays a Chinese voice notification through Windows Text-to-Speech when your AI agent (e.g. Cursor) completes a task or needs your confirmation — so you can step away from the screen without missing a beat.

---

## Quick Start

**Step 1 — Install**

```bash
pip install horn
```

**Step 2 — Verify**

```bash
horn
```

You should hear: *"Horn 已就绪，等待任务通知"*. If you do, installation is complete.

**Step 3 — Configure Cursor Rules**

Copy `horn.mdc` to your project's `.cursor/rules/` directory (or Cursor's global Rules directory):

```
.cursor/
└── rules/
    └── horn.mdc   ← copy here
```

The `horn.mdc` file is included in the package. Find it with:

```bash
python -c "import importlib.resources as r; print(r.files('horn.rules').joinpath('horn.mdc'))"
```

Then give Cursor a simple task to confirm auto-trigger is working. You should hear *"老板，我开始执行任务了"* at the start.

---

## Commands

| Command | Voice Output | Use Case |
|---------|-------------|----------|
| `horn` | 「Horn 已就绪，等待任务通知」 | Verify installation |
| `horn --start` | 「老板，我开始执行任务了」 | Agent begins a task |
| `horn --done` | 「老板，任务已完成」 | Agent finishes a task |
| `horn --confirm` | 「老板，有事情需要你确认」 | Agent needs your decision |

**Exit codes**: `0` on success, `1` on any error (unknown argument, TTS failure, timeout).

All errors are written to **stderr** only; no stdout output on normal runs.

---

## Requirements

- Windows 10 / 11
- Python 3.8+
- Windows Speech (SAPI) enabled (enabled by default on most Windows installations)

---

## FAQ

### Installation issues

**Q: `pip install horn` fails with a build error.**

1. Make sure you are running Python 3.8 or higher: `python --version`
2. Upgrade pip first: `python -m pip install --upgrade pip`
3. If you see a `pywin32` error, install it manually: `pip install pywin32`

**Q: `horn` command is not found after installation.**

1. Check that Python's `Scripts` folder is in your PATH: `python -m site --user-site`
2. On Windows, the Scripts path is typically `%APPDATA%\Python\PythonXX\Scripts` — add it to your PATH environment variable.
3. Restart your terminal and try again.

**Q: Installation succeeds but `horn` prints an error about SAPI.**

1. Open *Windows Settings → Time & Language → Speech* and confirm the speech service is enabled.
2. Try running the Windows built-in TTS test: *Narrator* or *Windows Speech Recognition*.
3. Restart the Windows Audio service: `services.msc → Windows Audio → Restart`.

---

### No sound

**Q: `horn` runs without errors but I hear nothing.**

1. Check your system volume — make sure it is not muted or set to 0.
2. If using headphones or external speakers, confirm the correct output device is selected in Windows Sound settings.
3. Run `horn` in a terminal and watch for any stderr output that might indicate a silent failure.

**Q: I hear sound but it is very quiet.**

1. The default volume is 100. If you have a `horn.yaml` config file, check the `volume` field.
2. Also check the Windows per-app volume mixer — `horn.exe` may have its own level set lower.

**Q: The voice cuts off mid-sentence.**

1. This may be caused by the 5-second playback timeout. The Chinese phrases are short and should finish well within 5 seconds under normal conditions.
2. If your system is under heavy load, the TTS engine may be slow — try closing other applications.

---

### Cursor Rules not triggering

**Q: Agent completes a task but I hear no voice notification.**

1. Confirm `horn.mdc` is in the correct directory: `.cursor/rules/horn.mdc` (project-level) or Cursor's global Rules directory.
2. Verify the `horn` command is available in the terminal Cursor uses: open Cursor's integrated terminal and run `horn`.
3. In Cursor Settings, check that the Rules file is being loaded (look for it under *Rules for AI*).

**Q: Agent triggers `horn --start` but never triggers `horn --done`.**

1. This is a Cursor agent behavior issue, not a Horn issue. The agent may have stopped following the Rules mid-task.
2. Try re-stating the task and explicitly remind the agent: *"Remember to call horn --done when finished."*
3. Check if the Rules file uses `alwaysApply: true` in the front-matter — this ensures the rule is always active.

**Q: Agent calls `horn` too frequently or at unexpected times.**

1. Review your `horn.mdc` rules — make sure the trigger conditions are clearly scoped to task start, completion, and confirmation only.
2. Use Cursor's Rules management UI to disable and re-enable the rule to force a reload.
