agent-tools
Python CLI tools for:
- transforming raw text into TTS-ready narration and synthesizing it in one command
- transforming piped text through either the private Codex backend used by local Codex or an experimental Claude Code CLI wrapper
- synthesizing the result to WAV with Kokoro-82M
- auto-TTS of completed Codex and Claude Code replies through installed desktop hooks
This repo is intentionally wired to local Codex and Claude Code installs.
Release policy:
- semantic-release owns version bumps, changelog updates, and
py-v*tags - do not manually edit
project.versioninpyproject.tomlduring normal work - do not create release tags by hand unless the release workflow explicitly calls for it
Status
This is an experimental public package with a private Codex dependency and an experimental Claude Code CLI transform path.
The transform command mirrors the current request shape used by the local Codex source tree and depends on ChatGPT-backed auth in ~/.codex/auth.json.
The Claude Code path uses the official claude CLI in headless -p mode with a constrained
single-turn wrapper. It does not rely on any private Claude Code API.
It does not use:
codex execcodex app-server- the public OpenAI API key flow
That means:
- you must already be logged into local Codex
- backend compatibility can break if Codex internals or backend contracts change
- this package is best suited for users who already use local Codex
Requirements
- Python 3.11+
- local Codex already logged in via ChatGPT
- local Claude Code CLI installed if you want Claude-backed transforms or Claude auto-TTS integration
espeak-nginstalled for best Kokoro English fallback behavior
Install
cd repos/agent-tools
uv venv
uv pip install -e ".[dev]"
Public package install:
pip install ai-nd-co-agent-tools
UI-enabled install:
pip install "ai-nd-co-agent-tools[ui]"
Install a CUDA-enabled PyTorch stack for this CLI environment:
agent-tools install-cuda
Pass an explicit track if you do not want auto-detection:
agent-tools install-cuda --cuda-track cu130
Usage
Single-command path: ttsify
echo "Turn this note into natural spoken narration." | agent-tools ttsify --output-file out.wav
ttsify uses a built-in rewrite prompt stored in the package and then pipes the transformed text
into Kokoro TTS.
Default ttsify settings:
- model:
gpt-5.4-mini - reasoning effort:
medium - voice:
af_heart
Configurable via env vars:
AGENT_TOOLS_CODEX_MODEL=gpt-5.4-mini
AGENT_TOOLS_CODEX_REASONING_EFFORT=medium
AGENT_TOOLS_KOKORO_VOICE=af_heart
AGENT_TOOLS_KOKORO_LANGUAGE=a
AGENT_TOOLS_KOKORO_SPEED=1.0
AGENT_TOOLS_KOKORO_DEVICE=auto
AGENT_TOOLS_TRANSFORM_PROVIDER=codex
AGENT_TOOLS_CLAUDE_CODE_MODEL=haiku
AGENT_TOOLS_CLAUDE_CODE_EFFORT=low
AGENT_TOOLS_CLAUDE_CODE_BARE=false
Claude Code transform models are intentionally limited to:
haikusonnet
opus is rejected by the CLI and runtime wrapper.
CLI flags override env vars.
Queue for playback on Windows:
echo "Turn this note into natural spoken narration." | agent-tools ttsify --output-mode play --source agent-a
Desktop integrations
Install both supported desktop integrations:
agent-tools install-integrations
Install only one provider if needed:
agent-tools install-codex-integration
agent-tools install-claude-integration
- On native Windows Codex, this installs a
notifycommand in~/.codex/config.toml. - On non-Windows, this keeps the Stop-hook integration path.
- Claude Code integration installs an AgentTools
Stophook into~/.claude/settings.jsonand writes the hook script to~/.claude/agent-tools/stop_tts.sh. - The compatibility alias
agent-tools install-codex-stop-hookremains available.
Windows debug logs:
~/.codex/notify_tts.log~/.codex/notify_tts_agent_tools.log
On Windows, Codex passes the notify payload as the final JSON argv argument to the installed Python command. No PowerShell or bash wrapper is used.
This enqueues the generated audio, starts the background controller if needed, and returns immediately.
Claude Code hook logs:
~/.claude/agent-tools/stop_tts.log~/.claude/agent-tools/stop_tts_agent_tools.log
Shared performance log:
- Windows:
%LOCALAPPDATA%/AgentTools/state/performance.jsonl - Linux/macOS:
~/.local/share/agent-tools/state/performance.jsonl
Each JSONL row records one completed command or dispatch with stage timings such as
transform_ms, tts_generation_ms, tts_postprocess_ms, enqueue_ms, and total_ms.
You can also manage AgentTools auto-TTS integration from the desktop controller UI and tray menu. AgentTools only needs one backend to be available:
- Codex, with local ChatGPT login working
- or Claude Code installed on PATH
If neither backend is available, the UI shows an info-only message telling you to install or sign in to any one of them first.
Transform text
echo "Rewrite this into short spoken narration." | agent-tools transform \
--system-prompt-file prompt_examples/rewrite_for_tts.md
Optional controls:
echo "Input text" | agent-tools transform \
--system-prompt-file prompt_examples/rewrite_for_tts.md \
--provider codex \
--model gpt-5 \
--reasoning-effort medium \
--fast
Experimental Claude Code-backed transform:
echo "Input text" | agent-tools transform \
--system-prompt-file prompt_examples/rewrite_for_tts.md \
--provider claude-code \
--claude-model haiku \
--claude-effort low
What the Claude wrapper does:
- runs
claude -pin a temporary minimal working directory - forces
--max-turns 1,--tools "",--no-session-persistence, and--output-format json - uses
--system-promptwith the same rewrite prompt file you pass totransform - does not require or use any unofficial Claude Code API
Important limitation:
--claude-bareis supported, but it is off by default because local Claude help shows bare mode only readsANTHROPIC_API_KEYorapiKeyHelperauth. If you rely on normal Claude login state, keep--claude-bareoff.
Text to speech
echo "Hello world." | agent-tools tts --output-file hello.wav
Queue already-prepared speech on Windows:
echo "Hello world." | agent-tools tts --output-mode play --source agent-a
Desktop controller UI
agent-tools ui
If the controller is already running, this focuses the existing window instead of starting a second process.
The controller behavior is:
- when neither Codex nor Claude Code is available, the normal playback UI is hidden and the window shows an info-only message telling you to install or sign in to any one backend first
- when either backend is available, the normal playback UI stays usable
- a single switch soft-disables or re-enables AgentTools auto-TTS processing when the relevant AgentTools hook/integration is installed
- a dropdown chooses the default transform engine used for
ttsifyand desktop auto-TTS: Codex or Claude Code - if the saved/default provider is unavailable but another backend is available, AgentTools falls back automatically unless you explicitly force a provider on the CLI
End-to-end pipeline
cat input.txt | agent-tools transform \
--system-prompt-file prompt_examples/rewrite_for_tts.md \
| agent-tools tts --voice af_heart --output-file out.wav
Notes
ttsifyis the recommended end-user path;transformandttsremain available as building blocks.transformreads stdin by default and writes plain text to stdout.ttsreads stdin by default and writes WAV bytes to stdout unless--output-fileis set.ttsandttsifysupport--output-mode playon Windows.- in play mode, audio is queued into a single background controller process.
agent-tools uilaunches or focuses the popup/tray controller window.- controller shortcuts:
Spacepause/resume,Escstop,Ctrl+Rreplay,Ctrl+Nnext. ttsandttsifydefault to--device auto.- auto device selection uses a real CUDA probe, not just
torch.cuda.is_available(). agent-tools install-cudareinstalls the full PyTorch stack (torch,torchvision,torchaudio) into the current Python environment and validates the full Kokoro import chain in a fresh subprocess by default.transformrefreshes ChatGPT tokens when the Codex backend returns401.- the experimental Claude transform path uses the official
claudeCLI only; it is intentionally limited to one turn with tools disabled - Native Windows Codex uses
notify;hooks.jsonlifecycle hooks are not used there. - semantic-release now owns future Python package version bumps and
py-v*tags.
CPU performance
Measured on this machine on April 15, 2026 with forced CPU:
| Scenario | Wall time | Audio time | Real-time factor |
|---|---|---|---|
| first-ever cold init after dependency/model setup | ~43.1s | n/a | n/a |
| cached init | ~2.9s | n/a | n/a |
| warm short | 0.309s | 4.80s | 0.064 |
| warm medium | 1.199s | 15.53s | 0.077 |
| warm long | 2.514s | 26.70s | 0.094 |
Interpretation:
- warm CPU generation on this machine is about 10x-15x faster than realtime
- the main cost is cold startup/model load, not steady-state synthesis
To reproduce locally:
python scripts/benchmark_tts_cpu.py
Troubleshooting
- Missing
~/.codex/auth.json: runcodex login - Expired auth: rerun
codex loginif refresh fails permanently - Missing
espeak-ng: install it for better English fallback behavior - Slow first run: expected; Kokoro downloads voices/models and initializes the pipeline
- After changing Python versions for the interpreter that runs
agent-tools, rerunagent-tools install-cudain that same interpreter to repair the PyTorch stack for Kokoro
Metadata
Release files for ai-nd-co-agent-tools 0.7.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ai_nd_co_agent_tools-0.7.6.tar.gz | 76.9 kB | With provenance | Details for ai_nd_co_agent_tools-0.7.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ai_nd_co_agent_tools-0.7.6-py3-none-any.whl | Python 3 | none | any | Details for ai_nd_co_agent_tools-0.7.6-py3-none-any.whl |
Total release size: 147.6 kB
Release files / ai_nd_co_agent_tools-0.7.6.tar.gz
| Download URL | ai_nd_co_agent_tools-0.7.6.tar.gz |
|---|---|
| Size | 76.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9773d0fb2c5ed2c544274d5333745cc2e04d724eb4325c2ed38af483e3dc2980
|
|
BLAKE2b-256 checksum How to use checksums |
17fed1261c75957f7966d933c2df916361333add5f2752f7ad109c243fd45e5b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 1, 2026.
Transparency logRelease files / ai_nd_co_agent_tools-0.7.6-py3-none-any.whl
| Download URL | ai_nd_co_agent_tools-0.7.6-py3-none-any.whl |
|---|---|
| Size | 70.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
373e4ecc73cb387feb147cf1f5bf6050cbbb5c939ae94a3408d35b4b4f1a7610
|
|
BLAKE2b-256 checksum How to use checksums |
2961163c149a74c73d93817055b780981571ff053a1c7788f65aae754f2a1095
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 1, 2026.
Transparency logSecurity for ai-nd-co-agent-tools 0.7.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for ai_nd_co_agent_tools-0.7.6.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 1, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.