Enable Voice in Settings → Voice. Hold the microphone or space bar to speak, or click the web microphone for continuous listening. You can interrupt a spoken reply. The mobile app supports push-to-talk.

Ask how a Pencil feature works, find an object, read its details, or ask what needs your input. Help answers link to Pencil documentation; object answers use the live records you can access.

With Write actions enabled, capture an idea or create a task, project, product, feature, requirement/user story, goal, initiative, epic, milestone, sprint, iteration, customer, bug, persona, team, deliverable, inline file, content item, or agent memory. The same required fields and permissions apply as in the normal UI. Ask which creation fields are available when needed. Dates use your device's timezone.

The voice panel shows result links and a personal attention queue. Select a question before saying “use option two” when several chats need answers. You can also name the chat or task explicitly. Approving a tool or repository action requires a decision about that specific action.

Connect coding chats

Enable Coding chat connections in Voice settings and pair your own device through Settings → Gateway. Each person's external chats stay private to that person. Other members and workspace administrators do not gain access to them. Write actions must also be enabled to send spoken answers.

Codex#

Run the following against the same shared app server as your Codex chats:

pencil-gateway voice codex

For a custom server, pass its local control socket:

pencil-gateway voice codex --socket /absolute/path/to/control.sock

This attaches through codex app-server proxy; it does not start or replace a Codex server. A desktop app or CLI using an independent server without a control socket cannot be controlled through this connection. Unloaded threads are shown as disconnected, not as completed. Questions and single-action command/file approvals exposed by the connected server can be answered. Other permission forms remain in Codex's native UI.

Claude Code#

Install Pencil's opt-in hooks into your user settings:

pencil-gateway voice install-claude

For project-only installation, pass --settings /path/to/project/.claude/settings.local.json. Existing settings and hooks are preserved, with a .pencil-backup file created on the first change. Reload the settings or restart the Claude Code session if its installed version requires it. Terminal, IDE, and Claude Code desktop sessions connect when they load those settings. Ordinary Claude.ai conversations are not Claude Code sessions.

The hooks report session/turn activity and forward AskUserQuestion and tool-permission requests. The original Claude input and choices are retained locally. A spoken response is handed back to that exact waiting hook. If the connection fails or no answer arrives within nine minutes, the hook leaves Claude's native prompt available. Existing permission policies still apply.

The hook installer requires Claude Code 2.1.250 or newer. The Codex adapter was checked against Codex 0.162.0-alpha.17.2; it requires the installed app-server proxy interface and a shared control socket.

Remove only Pencil's hooks with:

pencil-gateway voice install-claude --remove

Every command supports --account work for a named paired profile. Install hooks separately for the profile that should receive your local chat activity.

Desktop or terminal chats through MCP#

When a chat has no shared Codex socket or does not load Claude hooks, configure its local Pencil MCP server command with voice enabled:

pencil-gateway mcp --voice-provider codex
# Or, in Claude Code:
pencil-gateway mcp --voice-provider claude

Use the paired local server, rather than OAuth mode. Configure the command and arguments in your coding app's MCP settings and restart that connection. If your client allows a tool timeout, allow at least nine minutes for a voice question; shorter client timeouts cancel the waiting question and leave the agent to ask natively.

The connection gives the agent instructions and three tools: voice_start_chat, voice_chat_status, and voice_ask_user. Each conversation registers its own returned chat ID. Questions wait in the original MCP tool call and return the spoken answer directly to that conversation. Agent-reported status is labeled in the chat title; it depends on the agent reporting changes and does not prove native process activity. This connection cannot approve native provider permissions. Plain text questions that the agent does not submit through a supported hook or voice tool stay in the native app.

Existing conversations become visible after they connect and publish activity. Pencil does not scrape unconnected chat history or automatically attach to every desktop process.

Understand delivery and status

“Queued” means your answer is saved for the connected device. “Delivered” means the local bridge handed it to the provider. Work is reported as running only when subsequent provider activity confirms it. If delivery cannot be confirmed, check the original chat before trying again; Pencil does not automatically repeat an uncertain approval.

Idle means the agent finished its current turn, not necessarily its task. A stale connection is shown as disconnected after ninety seconds without activity. Pencil task status is labeled separately from native process activity. Disconnected or unconnected sources may have newer questions in their original app.

On web, enable “Announce new questions” in the voice panel to hear new attention items while the panel is open. It is off by default. Your microphone controls and permissions remain visible and under your control.