Skip to main content

​
Quickstart

This guide will get you from installation to your first voice coding session in minutes.
Make sure you’ve completed Installation before starting this guide.

​
Quick Start in 4 Steps

1

Attach a workspace

Navigate to your project directory and attach it:
cd ~/projects/myapp
duck .
This command:
  • Starts the daemon if needed
  • Registers the workspace
  • Creates or resumes a session for this repo
  • Streams live events to your terminal
You’ll see output like:
Attached: /Users/you/projects/myapp
Session: myapp-1
Streaming events...
2

Start a voice session

With the terminal running duck ., press and hold the hotkey:Option+DYou’ll see a recording indicator in the menu bar and your terminal.
3

Speak your request

While holding Option+D, speak naturally:
  • “List all TypeScript files in the src directory”
  • “Where is the authentication logic defined?”
  • “Run the test suite and tell me what failed”
Release the key when done speaking.
4

Watch and listen

The agent will:
  • Show your transcribed speech in the terminal
  • Execute tools (search, read files, run commands)
  • Stream all output to your terminal in real-time
  • Speak the response back to you
All file reads, command executions, and edits are visible in your terminal.

​
Your First Interaction

Here’s what a typical session looks like: 
$ duck .
Attached: /Users/you/projects/myapp
Session: myapp-1
Streaming events...

[user] List all TypeScript files in the src directory

[tool:bash] ls src/**/*.ts
  src/index.ts
  src/utils/helper.ts
  src/components/Button.ts
  src/services/api.ts

[assistant] I found 4 TypeScript files in the src directory: 
index.ts, helper.ts, Button.ts, and api.ts. 
Would you like me to look at any of these?

​
Interrupting the Agent

You can interrupt at any time:
1

Start speaking

While the agent is speaking or working, just start talking. The agent will:
  • Stop speaking immediately
  • Abort the current operation (if auto-abort is enabled)
  • Listen to your new request
2

The terminal shows what happened

[system] Interrupted by user
[system] Run aborted

[user] Actually, show me the tests instead
Auto-abort on barge-in is enabled by default. You can change this in Settings to use “steering” mode instead, which queues your message for after the current tool finishes.

​
Common Commands

Here are some useful commands to try:

​
Attach and Follow

# Attach current directory and stream events
duck .

# Attach a specific directory
duck ~/projects/myapp

​
Send Typed Messages

You can also send typed messages without using voice: 
# Send a message to the active session
duck say "fix the auth bug"

# The output streams to your terminal just like voice

​
Session Management

# List sessions for the current workspace
duck sessions

# List all sessions across all workspaces
duck sessions --all

​
System Health

# Check that everything is working
duck doctor

​
Understanding the Terminal Output

The terminal shows everything that happens:
PrefixMeaning
[user]Your transcribed speech or typed message
[assistant]The agent’s response (also spoken to you)
[tool:bash]Bash command being executed
[tool:read_file]File being read
[tool:edit_file]File being edited
[tool:grep_search]Search being performed
[system]System messages (interruptions, session changes)
All bash commands and file edits are executed in your workspace. Review the output carefully, especially for write operations.

​
Keyboard Shortcuts

ShortcutAction
Option+DPress and hold to activate voice agent
Option+Shift+DOpen Settings window
Ctrl+C (in terminal)Stop following the session stream

​
Tips for Effective Voice Coding

Instead of “update the config”, say “update the webpack.config.js file in the root directory”.
Voice works best for focused requests. Break large refactors into smaller steps.
The spoken response is a summary. The terminal has the full details, diffs, and output.
If the agent goes off track, just start speaking. Interruptions are instant.
When the agent makes edits, review the diffs in your terminal before committing changes.

​
Next Steps

CLI Reference

Learn all available duck commands and options

Multi-Session Workflows

Work with multiple sessions across different repos

Voice Configuration

Customize voice behavior and interruption settings

Troubleshooting

Common issues and solutions

Build docs developers (and LLMs) love

Get started for freeTalk to us