mahorn 0.1.0

Windows CLI task completion notification tool for AI agent collaboration

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

pip install horn

Step 2 — Verify

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:

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.