Agent Shell is a separately installed Emacs package for interactive AI-agent sessions. Emacsvox adds speech and semantic presentation without replacing Agent Shell’s provider setup, session management, prompt editor, or permission controls. See Agent Shell for provider installation and configuration.
The generated emacsvox-agent-shell in Emacsvox Reference Manual section is the exhaustive Emacsvox command and option reference. This chapter follows the tasks a user performs in a session.
Load Emacsvox and start Agent Shell with M-x agent-shell. Emacsvox loads
its integration after Agent Shell and activates both new and already existing
shell buffers. Run M-x emacsvox-agent-shell-enable only when manually
re-enabling support after it was disabled or while diagnosing a live reload.
Compose and submit prompts with Agent Shell’s normal editing commands. The live prompt retains Emacs undo. Submitted transcript text is history rather than editable prompt input. Press C-c C-c to ask Agent Shell to interrupt an active request; its normal confirmation setting still applies.
Emacsvox speaks routine content only at complete turn boundaries. A network pause does not make a partial answer sound complete. A cancelled, refused, or failed turn reports its outcome without replacing the last successfully completed response.
The focused session defaults to response: completed answers and routine
completion feedback are presented, while thought, plan, and tool chatter is
suppressed. An unfocused session defaults to notify: its notification
names the session but does not disclose response or tool content.
fullSpeak responses plus configured thought, plan, and tool detail. Full tool output can contain commands, file contents, or other sensitive provider data.
responseSpeak completed agent responses while suppressing routine thought, plan, and tool content.
notifyPresent routine completion without reading the response body.
quietSuppress routine automatic feedback. Explicit inspection remains available.
autoUse emacsvox-agent-shell-foreground-speech-level or
emacsvox-agent-shell-background-speech-level according to focus.
Press C-c C-q to run
emacsvox-agent-shell-select-speech-level and choose the current
session’s level, including auto. Press C-c C-S-q to run
emacsvox-agent-shell-select-background-speech-level and change the
shared background default.
M-x emacsvox-agent-shell-cycle-speech-level cycles toward less routine
speech; use a prefix argument to restore auto.
Thought content defaults to an icon under
emacsvox-agent-shell-speak-thought-process. Tool feedback is separately
controlled by emacsvox-agent-shell-speak-tool-calls and
emacsvox-agent-shell-tool-output-verbosity. Selecting background
response or full, thought speak, or full tool output is an
explicit disclosure choice.
Automatic response, tool, error, permission, and similar text is limited by
emacsvox-agent-shell-automatic-content-max-characters, which defaults to
2,000 characters. A shortened presentation gives exact omitted character and
line counts and tells you where to inspect the full content. The complete text
stays in the Agent Shell buffer; the limit is applied before Aural compiles the
automatic speech copy.
Permission requests are separate from routine speech levels because they can
block the agent and require a decision. With
emacsvox-agent-shell-speak-permissions enabled, a request interrupts the
appropriate speech stream, identifies the session and requested operation, and
announces its choices. Provider-controlled descriptions and choice labels are
bounded, but the actual permission controls remain in Agent Shell.
If the request belongs to another session, switch to the named buffer. Use
M-x agent-shell-jump-to-latest-permission-button-row to find its latest
permission row, or use Agent Shell’s TAB and S-TAB item navigation.
Move among the buttons and press RET, or use a direct choice key displayed
by Agent Shell. Choice keys are supplied by Agent Shell and the provider, so
the visible permission row is authoritative.
Error blocks remain exceptional feedback rather than routine transcript
chatter. Lifecycle error announcements follow
emacsvox-agent-shell-signal-processing; rendered error content remains
available in the transcript even when routine response speech is quiet.
These commands work from the shell and its associated viewports:
Run emacsvox-agent-shell-speak-last-response. It reads the latest
successfully completed response in full without moving point. This deliberate
operation does not inherit the automatic 2,000-character limit. While a new
turn is busy it explicitly identifies and reads the prior completed response.
Run emacsvox-agent-shell-speak-response-overview. It reports line,
heading, source-block, and table counts plus a bounded opening preview.
These commands remain usable at notify and quiet. If no turn has
completed, they say that no completed response is available rather than
presenting a streaming partial or failed answer.
Use typed block navigation to reach a source block, then:
Run emacsvox-agent-shell-speak-source-block to read the complete rendered
source block with its language and line count.
Run emacsvox-agent-shell-copy-source-block to copy the logical source
through Agent Shell’s public copy operation.
The source commands are explicit operations and do not use the automatic content limit. Ordinary line navigation retains its separate bounded speech policy.
If a request is taking the wrong path, press C-c C-c and confirm the Agent Shell interrupt. A failed or interrupted partial response is not cached as complete. Press C-c r for the preceding completed response, or C-c R for its overview. Read the error block in the transcript for the provider’s details and edit the live prompt before resubmitting.
Use M-x agent-shell-restart when Agent Shell itself needs a fresh process
for the same project. Use M-x emacsvox-agent-shell-enable to reinstall
speech hooks after deliberately disabling them. Neither recovery command
discards transcript files or project work.
If you are changing the integration rather than using it, see Integration Maintenance for its public event, renderer, and compatibility contracts.