Metadata-Version: 2.4
Name: earwarden
Version: 1.0.1
Summary: Answer Claude Code permission prompts by voice, with confirmation strength set by risk.
Author: rehaan
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Typing :: Typed
Requires-Dist: metaphone==0.6
Requires-Dist: pydantic>=2.11,<3
Requires-Dist: pyyaml>=6.0,<7
Requires-Dist: mlx-audio==0.6.4 ; platform_machine == 'arm64' and sys_platform == 'darwin' and extra == 'voice'
Requires-Dist: misaki==0.9.4 ; platform_machine == 'arm64' and sys_platform == 'darwin' and extra == 'voice'
Requires-Dist: spacy>=3.8 ; platform_machine == 'arm64' and sys_platform == 'darwin' and extra == 'voice'
Requires-Dist: num2words>=0.5 ; platform_machine == 'arm64' and sys_platform == 'darwin' and extra == 'voice'
Requires-Dist: numpy>=1.26 ; platform_machine == 'arm64' and sys_platform == 'darwin' and extra == 'voice'
Requires-Dist: sounddevice>=0.5 ; platform_machine == 'arm64' and sys_platform == 'darwin' and extra == 'voice'
Requires-Dist: onnxruntime>=1.20 ; platform_machine == 'arm64' and sys_platform == 'darwin' and extra == 'voice'
Requires-Python: >=3.11
Project-URL: Repository, https://github.com/rk-python5/Earwarden
Project-URL: Changelog, https://github.com/rk-python5/Earwarden/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/rk-python5/Earwarden/blob/main/docs/quickstart.md
Project-URL: Issues, https://github.com/rk-python5/Earwarden/issues
Project-URL: Security, https://github.com/rk-python5/Earwarden/blob/main/SECURITY.md
Provides-Extra: voice
Description-Content-Type: text/markdown

# Earwarden

Maker-checker for AI agents, in your ear. Earwarden is a local macOS service that answers Claude Code
permission prompts by voice through your AirPods, with confirmation strength set by risk:

- **Tier 1:** a nod or a "yes".
- **Tier 2:** a random challenge word plus your voiceprint.
- **Tier 3:** keyboard only, never by voice.

Everything runs on your Mac: no cloud calls at runtime, and no account or API key of its own.

## Install

You need a Mac with Apple Silicon (macOS 14 or later), AirPods or another headset,
[uv](https://docs.astral.sh/uv/), Claude Code and Xcode's command line tools:

```sh
uv tool install 'earwarden[voice]'
earwarden setup      # hooks, the helper app, and the voice models
earwarden enroll     # your voiceprint, about 3 minutes with the AirPods in
earwarden service install --voice --stem
```

[docs/quickstart.md](docs/quickstart.md) has the five-minute version with what to expect. Without
`[voice]`, or without a headset, every prompt stays on Claude Code's screen, as it always has.

## Status

Earwarden 1.0 passed its test suite, a red-team suite and recorded-audio checks, and has run live
on one setup: an M2 MacBook Air with AirPods 4 and one speaker's voice. Other headsets, rooms and
voices are untested, and the voiceprint's threshold isn't calibrated on other people. Voice is a
convenience check, never identity proof, and tier 3 is never approvable by voice. Read
[SECURITY.md](SECURITY.md) for what it does and doesn't promise, and
[docs/redteam.md](docs/redteam.md) for the attacks it was tried against. Until
P-20 in [decisions.md](decisions.md) closes after longer use, try voice in a scratch project
first.

## Documents

- [Quick start](docs/quickstart.md), [how tiers work](docs/how-tiers-work.md) and
  [privacy](docs/privacy.md)
- [SECURITY.md](SECURITY.md), the [red-team table](docs/redteam.md) and
  [attribution](docs/attribution.md) for every model and library
- [Technical design and build plan](docs/design/earshot-technical-design-build-plan.pdf)
- [Decisions](decisions.md): decisions, proposals and open questions
- [Changelog](CHANGELOG.md)
- [Releasing](docs/releasing.md) and [CLAUDE.md](CLAUDE.md): working rules for maintainers and
  Claude Code sessions in this repo

## Development

Everything Earwarden installs stays inside this folder, in venvs: uv itself, the Python 3.11 it
downloads, every library and every model. Nothing goes into your system or shell profile
(decisions.md, D-013). In each new terminal, from the repo:

```sh
source dev/activate
```

The first time, this puts uv into a venv in `.tools/` using your Mac's `python3`. Then:

```sh
uv sync
uv run ruff check . && uv run ruff format --check . && uv run mypy && uv run pytest
```

To remove everything, delete `.tools/` and `.venv/`.

The PyPI distribution is `earwarden`; the import name and commands are `earwarden`.

## License

Apache-2.0. See [LICENSE](LICENSE).
