# Chat Interface
Source: https://docs.coddo.ai/features/chat
Talk to Claude Code or Codex through a rich visual interface with streaming, diffs, and more.
The Chat view is where you interact with your agent — **Claude Code** or **Codex CLI**. Instead of working in a terminal, you get a rich UI with real-time streaming, tool use visualization, and interactive blocks.
![Chat view showing tool use and todo blocks]()
## Chat threads
Each project can have **multiple chat threads**. You can create new threads for different tasks or conversations. Threads are persisted locally in your project's `.coddo/threads/` directory.
* **Create** a new chat from the sidebar
* **Resume** a previous conversation — Coddo reuses the provider's native session system to maintain context
* **Pin** a chat to keep it at the top of the sidebar
* **Rename** a chat via the **more** menu
* **Delete** threads you no longer need
When a Kanban task starts, a chat thread is **automatically created and linked** to it.
## Chat modes
Coddo supports two chat modes that change how the agent responds. Switch modes from the **mode selector** in the chat input area.
### Execution mode
The default mode. The agent **reads, writes, and runs code** in your project. It executes tools, creates files, runs commands, and makes real changes to your codebase.
### Plan mode
The agent only **analyzes and plans** without making any changes. It reads your code and proposes a strategy, but does not write files or run commands. Use this when you want to:
* Get an implementation plan before committing to changes
* Understand a complex part of the codebase
* Review architecture decisions
You can set the default chat mode in **Settings**.
## Real-time streaming
Messages from the agent are **streamed in real time** as they're generated, with your codebase as context. Your last message is **pinned at the top of the chat view** with sticky scroll, so you always keep sight of what you asked while the agent responds below.
## Providers and models
Coddo supports both **Claude Code** and **OpenAI Codex CLI** as execution backends. Pick the provider in the model selector inside the chat input area or in the task creation dialog. Provider and model info also show up in the statistics view.
### Claude models
| Model | Description |
| -------------- | ----------------------------- |
| **Sonnet 4.6** | Fast and performant (default) |
| **Opus 4.7** | Most intelligent |
| **Haiku 4.5** | Fastest and most economical |
### Codex models
| Model | Description |
| ------------------- | ----------------------------------- |
| **GPT-5.5** | Latest general-purpose OpenAI model |
| **GPT-5.4** | High-performance generation |
| **GPT-5.4 Mini** | Smaller and faster |
| **5.3 Codex** | Codex-tuned model |
| **5.3 Codex Spark** | Lightweight Codex variant |
You can set a default model in **Settings** and override it per chat or per task. The chat view remembers the last-used model for each conversation and restores it when you come back.
If no provider is configured, the model selector redirects you to **Settings** where you can authenticate Claude and/or Codex.
## Message types
### Text messages
Standard markdown-formatted messages with full rendering support - headings, lists, code blocks, tables, and more.
The chat input uses a **rich text editor** with support for bold, italic, inline code, code blocks, and lists — so you can format your messages before sending.
### Voice dictation
Every chat input and task instruction field has a **mic button**. Click it to record, click again to stop, and the transcribed text is dropped straight into the field — ready to edit or send. See the [Voice Dictation](/features/voice-dictation) page for details, language settings, and limits.
### Tool use blocks
When the agent uses a tool (reading files, writing code, running commands), you see a **Tool Use Block** showing:
* The tool name and input parameters
* The output/result
* Expandable details for long outputs
### Skill cards
When a chat invokes a [skill](/features/skills), the message renders as a dedicated **skill card** with the skill name, icon, author, and key parameters — so you can see at a glance which skill ran and how.
### Diff viewer
For worktree task threads, a **visual diff viewer** shows all changes made by the task compared to the base branch - with syntax highlighting showing exactly what was added, modified, or removed.
### Question blocks
When the agent asks you a question with multiple options, you get an interactive **Question Block** with clickable choices and descriptions.
### Todo blocks
The agent's internal task lists are rendered as **Todo Blocks**, showing you the planned steps and progress.
## Image support
You can include images in your messages:
* **Drag and drop** images directly into the chat input
* **Paste** images from your clipboard
* Supports all common image formats (PNG, JPG, GIF, WebP, SVG, etc.)
This is useful for sharing mockups, screenshots, or design references with the agent.
## Duration & cost tracking
Each message displays its **duration**, **token count**, and **cost** — so you can track how long the agent takes to respond and how much each interaction costs.
## Chat header quick actions
The chat header gives you one-click access to the most common task operations:
* **Checkout** — switch to the task's branch
* **Cancel** — stop the current run
* **Archive** / **Delete** — clean up the thread
* **Diff** — open the diff viewer for the chat's changes
The header also surfaces keyboard shortcut hints on hover so you can learn them as you go.
# CLAUDE.md / AGENTS.md Editor
Source: https://docs.coddo.ai/features/claude-md
Configure how your agent behaves in this project with the built-in instructions editor.
The **CLAUDE.md** file (and its Codex equivalent **AGENTS.md**) is a special configuration file that tells your agent how to behave in this project. Coddo includes a built-in editor so you can manage it without leaving the app.
## What is CLAUDE.md / AGENTS.md?
`CLAUDE.md` is a markdown file at the root of your project that gives Claude Code project-specific instructions. **`AGENTS.md`** plays the same role for Codex. Both are read by the agent every time it starts a session.
Coddo's project-init flow generates both files and keeps them in sync. Edits made in the built-in editor write to whichever file your active provider expects.
Common things to include:
* **Project structure** - Describe your file organization
* **Tech stack** - List frameworks, libraries, and tools
* **Conventions** - Coding style, naming patterns, file naming
* **Build commands** - How to build, test, and run the project
* **Important rules** - Things Claude should always or never do
## Using the editor
1. Click the **CLAUDE.md** icon in the sidebar
2. The editor opens as a full-screen overlay
3. Edit the markdown content
4. Changes are saved directly to the `CLAUDE.md` file in your project root
A well-written CLAUDE.md / AGENTS.md dramatically improves your agent's output quality. The more context you give, the better the results.
## Generate with AI
If you don't have a `CLAUDE.md` or `AGENTS.md` file yet, or if you want to start fresh, click the **Regenerate** button. Coddo will analyze your project's codebase and automatically generate complete instruction files tailored to your project — including the tech stack, file structure, conventions, and build commands.
This is the fastest way to initialize your project configuration.
## Example CLAUDE.md
```markdown theme={null}
# My Project
## Stack
- React 19 + TypeScript
- Tailwind CSS v4
- Zustand for state management
## Commands
- `npm run dev` - Start dev server
- `npm run build` - Production build
- `npm run test` - Run tests
## Conventions
- Use functional components with hooks
- Name components in PascalCase
- Use kebab-case for file names
- Always add TypeScript types
## Rules
- Never use `any` type
- Always handle errors with try/catch
- Write tests for new features
```
## Tips
* Keep it concise — the agent reads the entire file for every session
* Focus on what's unique to your project
* Update it as your project evolves
* Include examples of patterns you want Claude to follow
# Git Integration
Source: https://docs.coddo.ai/features/git
Manage branches, commits, merges, and worktrees - all from the Coddo UI.
Coddo includes a full **Git integration** so you never have to leave the app to manage version control. The Git view has two tabs: Branches and Changes.
## Branches tab
View and manage all your local branches:
* **Create** new branches with sanitized names
* **Switch** between branches
* **Delete** local and remote branches
* See the **current branch** highlighted
* View **ahead/behind** status compared to the remote
* Visualize branch relationships in a tree structure
## Changes tab
A visual staging area for your Git workflow:
See all modified, added, and deleted files with their status indicators.
Stage individual files or all changes at once. Click on a file to see its diff.
Write a commit message and commit your staged changes.
Push your commits to the remote repository.
## Git and execution modes
The Git workflow differs depending on which execution mode your task uses.
### Worktree tasks
When a task runs in worktree mode, Coddo creates an isolated Git worktree with a dedicated branch (e.g. `coddo/1-fix-login`). The agent (Claude Code or Codex) works entirely inside this worktree.
Once the task is done, you **validate and merge** the branch back into the base branch from the Git view. Coddo handles:
* **Clean merges** - Automatic merge with no conflicts
* **Merge conflicts** - A conflict resolution dialog **automatically opens** when conflicts are detected, showing all conflicted files
* **Abort merge** - Cancel a merge in progress
* **Finalize merge** - Complete the merge after resolving conflicts
You can open conflicted files in your code editor to resolve them, then finalize the merge from Coddo.
### AI-assisted conflict resolution
When conflicts come up, the conflict dialog includes a **one-click button** that opens a new chat pre-filled with the right prompt to resolve them. The AI inspects the conflicted files, proposes a resolution, and the merge can be finalized once you accept.
### Direct tasks
When a task runs in direct mode, the agent works directly in your current working directory. Changes appear immediately in the Changes tab.
You can enable **auto-commit** in Settings (or per task) to automatically commit changes when the task completes. Otherwise, you stage and commit manually from the Changes tab.
## Push
After committing your changes, click **Push** to upload your local commits to the remote repository.
## Kanban header integration
The Kanban board header shows Git status at a glance:
* **Diff stats** - Files changed, insertions, and deletions
* **Ahead counter** - How many commits ahead of the remote. Hover to see the commit count in a tooltip
* **Commit & Push** button for quick operations
# Kanban Board
Source: https://docs.coddo.ai/features/kanban
Track your tasks visually with a drag-and-drop Kanban board integrated with Claude Code and Codex.
The Kanban board is the heart of Coddo's task management. It gives you a visual overview of all your tasks and their progress, updated in real time as your agent (Claude Code or Codex) works.
![Coddo Kanban board with tasks across columns]()
## Columns
Tasks flow through five columns. A **bar chart** at the top of the Kanban view shows the task count per column at a glance.
| Column | Description |
| --------------- | ------------------------------------------- |
| **Backlog** | Ideas and future tasks not yet planned |
| **Todo** | Tasks planned and ready to be worked on |
| **In Progress** | Tasks currently being executed by the agent |
| **Review** | Completed tasks awaiting your review |
| **Done** | Finished and reviewed tasks |
## Creating tasks
Click **+ New Task** from the Kanban view or from the **+ button in the sidebar** to open the task creation dialog. Each task gets a sequential number (TASK-00001, TASK-00002, etc.). Each task has:
* **Title** - A short name for the task
* **Instruction** - Detailed description of what the agent should do, with a **rich text editor** supporting bold, italic, code, and lists. You can also **dictate** the instruction with the mic button — see [Voice Dictation](/features/voice-dictation)
* **Tags** - Color-coded labels for categorization
* **Execution mode** - `worktree` (isolated branch), `direct` (current branch), or `last used`. The default is configurable in **Settings**
* **Provider & model** - Choose Claude (Sonnet 4.6, Opus 4.7, Haiku 4.5) or Codex (GPT-5.5, GPT-5.4, GPT-5.4 Mini, 5.3 Codex, 5.3 Codex Spark)
* **Images** - Attach reference images or mockups (drag-and-drop or paste)
* **Destination column** - Choose where the task is created (Backlog or Todo). The default is configurable in **Settings**
* **Auto-commit** - Per-task toggle for direct mode tasks
Use the **Reset** button to clear all fields and start over.
![Task creation dialog with title, instruction, tags, and execution mode]()
If you close the task creation dialog before submitting, all fields (title, instruction, tags, mode, model, images) are **preserved** and restored when you reopen it.
For worktree mode, you select a **base branch** (e.g. `main`). Coddo automatically generates a branch name like `coddo/1-fix-login`.
For direct mode, you can optionally enable **auto-commit** and select a target branch.
Write clear, detailed instructions for best results. The instruction is what the agent uses to understand what you want.
## Drag and drop
Reorder tasks within and between the **Backlog** and **Todo** columns by dragging them. Tasks in later columns (In Progress, Review, Done) cannot be dragged.
## Filters
Narrow the board to what matters right now:
* **Filter by column** — focus on a single Kanban stage
* **Filter by tag** — show only tasks matching one or more tags
Filters apply across board and list views.
## Task queue
When a task is moved to **Todo**, Coddo's queue runner automatically picks it up and starts execution. Worktree tasks can run **up to 5 in parallel** — each in its own isolated worktree, so they don't conflict. Direct mode tasks run sequentially to prevent conflicts on the same branch. You can configure the maximum number of concurrent tasks in **Settings**.
The **queue position** is displayed next to each task in the sidebar, so you can see where each task stands.
During execution you can:
* **Stop** a running task
* **Cancel** a task and move it back to backlog
* Track real-time progress (current tool, completed tools, todo items)
## Task details
Click on any task to open the **Detail Panel** on the right side, which shows the linked chat conversation. From the task card you can:
* Edit the title and instruction
* Manage tags
* See Git branch information and **last-modification timestamp** (1h, 1d, 1mo, etc.)
* **Checkout** the task's branch directly from the card for quick branch switching
* **Click the diff stats** on the card to jump straight to the chat with the diff viewer open
* Track duration
* View attached images
## Tags
Create custom tags with colors to organize your tasks. Tags are defined per project and can be managed from the **Tag Manager** in the Kanban view. Choose from 12 colors.
Examples: `bug`, `feature`, `refactor`, `urgent`, `design`
## Execution modes
When creating a task, you choose how the agent interacts with your Git repository.
### Worktree mode (default)
Coddo creates a **Git worktree** - a full, isolated copy of your repository checked out on a dedicated branch. The agent works inside this worktree without touching your main working directory.
* You select a **base branch** (e.g. `main`) and Coddo generates a branch name like `coddo/1-fix-login`
* Up to **5 worktree tasks can run in parallel**, each in its own isolated copy. Configure the concurrency limit in **Settings**
* When the task is done, you review the changes and **merge the branch** back into your base branch from the Git view
* The worktree is cleaned up after merging
This is the recommended mode for most workflows.
### Direct mode
The agent works directly in your **current working directory**, on whatever branch is currently checked out.
* You can optionally select a **target branch** to work on
* You can enable **auto-commit** to automatically commit changes when the task finishes
* Only **one direct task** can run at a time since they share the same files
* Changes appear immediately in your working directory
Direct mode is simpler and faster - best for quick fixes or when you don't need branch isolation.
### Default execution mode
You can set which mode new tasks default to in **Settings**:
| Option | Behavior |
| ------------- | ----------------------------------- |
| **Worktree** | Always default to worktree mode |
| **Direct** | Always default to direct mode |
| **Last used** | Use whatever mode you selected last |
## Archiving
Completed tasks can be **archived** to keep your board clean. You can:
* Archive individual tasks
* **Batch archive** all tasks in the Done column
* View archived tasks in a collapsible section
* Unarchive or permanently remove archived tasks
## View modes
Switch between two layouts:
* **Board view** - Classic Kanban columns side by side
* **List view** - Collapsible vertical list, compact and scannable
## Persistence
All Kanban data is saved locally in your project's `.coddo/kanban.json` file. Changes are persisted automatically as you work.
# Settings
Source: https://docs.coddo.ai/features/settings
Customize Coddo's appearance, language, models, and behavior.
Access settings from the **gear icon** in the sidebar to customize your Coddo experience.
## Theme
Choose your preferred appearance:
| Theme | Description |
| ---------- | ----------------------------------------- |
| **Light** | Clean, bright interface |
| **Dark** | Easy on the eyes for long coding sessions |
| **System** | Automatically matches your OS preference |
## Language
Coddo is available in two languages:
* **Francais** (French) - Primary language
* **English** - Full translation available
Switch languages instantly from the settings. The entire UI updates immediately.
## Providers
Coddo can run tasks and chats with either **Claude Code** or **OpenAI Codex CLI**. Authenticate each provider from Settings — the provider step is also part of onboarding and can be skipped if you want to configure it later.
| Provider | Models |
| --------------- | ---------------------------------------------------------- |
| **Claude Code** | Sonnet 4.6, Opus 4.7, Haiku 4.5 |
| **Codex CLI** | GPT-5.5, GPT-5.4, GPT-5.4 Mini, 5.3 Codex, 5.3 Codex Spark |
## Default models
Set the default model for chats and tasks separately. The default applies when you create a new chat or task — you can always override it per item.
You can also jump to the **Codex usage** view from Settings to track Codex consumption alongside the Claude API usage dashboard.
## Execution
Configure how tasks and chats behave by default:
| Setting | Options | Description |
| -------------------------- | ----------------------------- | ---------------------------------------------------- |
| **Default execution mode** | Worktree / Direct / Last used | Which mode new tasks default to |
| **Default chat mode** | Execution / Plan | Whether new chats default to execution or plan mode |
| **Default column** | Backlog / Todo / Last used | Which column new tasks are created in |
| **Concurrency** | 1 to 5 | Maximum number of worktree tasks running in parallel |
## Notifications
Coddo sends **native OS notifications** to keep you informed when the app is in the background:
* **Chat completed** — When the agent finishes a response
* **Action required** — When the agent needs your input (e.g. a question or approval)
Notifications use your operating system's native notification center.
## Git settings
* **Direct mode auto-commit** - Automatically create Git commits when a task in direct mode completes
* **Direct mode branch picker** - Show a branch selector when creating tasks in direct mode
## Voice dictation
Pick the **transcription language** Whisper should use for the mic button in chat and task creation. Pinning the language meaningfully improves accuracy on short utterances. See [Voice Dictation](/features/voice-dictation) for the full details.
## Account
Signing in with a **Coddo account** is **optional**. You only need it for:
* Voice transcription quota (free tier and subscription)
* Cross-device account sync of name, avatar, and plan
All project data — chats, tasks, attachments — stays local regardless of account state.
## Privacy
**Anonymous metrics** are **opt-in**. Toggle them on if you want to help us improve Coddo with anonymized usage data — nothing is sent unless you explicitly enable it.
## API usage
A direct link to your [Claude API usage dashboard](https://claude.ai/settings/usage) to monitor your consumption. The **Codex usage** entry takes you to the Codex consumption view in the same way.
## Keyboard shortcuts
macOS menu bar shortcuts for common actions:
| Shortcut | Action |
| ------------- | --------------------- |
| `Cmd+N` | New chat |
| `Cmd+T` | New task |
| `Cmd+Shift+B` | Create branch |
| `Cmd+Shift+S` | Toggle sidebar |
| `Cmd+Shift+G` | Open Git view |
| `Cmd+Shift+A` | Open Statistics view |
| `Cmd+Shift+P` | Open CLAUDE.md editor |
## Open with
Open your project in an external application directly from Coddo. Coddo automatically detects installed apps on your machine and organizes them by category:
* **Editors** - VS Code, Cursor, Windsurf, Zed, Sublime Text, JetBrains IDEs (WebStorm, IntelliJ, PyCharm, etc.), Xcode, and more
* **Terminals** - Terminal, iTerm, Warp, Alacritty, Kitty, Ghostty, etc.
* **Git clients** - Fork, Sourcetree, Tower, GitKraken, GitHub Desktop
Coddo remembers the last app you used and sets it as the default.
## Application info
The settings page displays:
* **Current version** - Your installed Coddo version
* **Check for updates** - Manually check if a newer version is available (also accessible from the macOS menu bar)
* **What's New** - An in-app changelog showing the latest features and changes for each version
## Multi-project
All your projects live in a **single window**. The sidebar includes a **project switcher** that lets you navigate between projects instantly. You can:
* **Add projects** — create new or open existing folders
* **Reorder projects** — drag and drop to organize them
* **Switch projects** — click to jump between them, each with its own chat, Kanban board, and Git state
Coddo remembers your open projects. When you **restart the app**, it automatically reopens the projects from your last session.
# Skills
Source: https://docs.coddo.ai/features/skills
Extend Claude Code and Codex with custom skills — create your own or install from the registry.
Skills are **reusable instructions** that extend what your agent can do. Think of them as templates or plugins that give Claude Code or Codex specific expertise for particular tasks.
## What are skills?
A skill is a set of instructions (in markdown) that tells the agent how to handle a specific type of task. For example, a skill could teach Claude or Codex:
* How to write tests following your project's conventions
* How to generate API documentation
* How to create components matching your design system
* How to review code for security issues
## Creating skills
The easiest way to create a skill is to describe what you want and let Coddo generate it with AI:
1. Open the **Skills** view from the sidebar
2. Click **+ New Skill**
3. Describe what the skill should do in plain language
4. Choose the scope: **Project** (this project only) or **Global** (all projects)
5. Coddo uses an AI-powered skill creator to generate the skill content
6. The skill is saved and immediately available for use
You can cancel the generation at any time.
Be specific in your description. Instead of "write tests", say "write unit tests using Vitest with TypeScript, using describe/it blocks, with setup and teardown".
## Skill scopes
| Scope | Location | Description |
| ----------- | ----------------------------------------------------------- | ------------------------------------------------------------------ |
| **Project** | `.agents/skills/` (Coddo) and `.claude/skills/` (symlinked) | Available only in the current project |
| **Global** | `~/.claude/skills/` and mirrored to `~/.codex/skills/` | Available across all your projects, for both Claude Code and Codex |
Global skills are mirrored to both Claude and Codex skill directories automatically, so a skill you install once works with both providers.
## Skills registry
Browse and install community-created skills from the **Recommended** section:
1. Open the Skills view
2. Scroll to the recommended skills section
3. Click the download button to install a skill
4. Installed skills are immediately available for use
## Install from an external source
You can also install any skill published on GitHub or another registry by pasting its **install command**:
1. Open the Skills view and click **+ Install**
2. Paste a command like `npx skills add https://github.com/owner/repo`
3. Choose **Project** or **Global** scope
4. Coddo runs the installer and the skill is ready to use
This is the fastest way to bring in a skill without creating it from scratch.
## Managing skills
From the Skills view, you can:
* **View** installed skills and their details
* **Search** skills by name or description
* **Uninstall** skills you no longer need
* **Refresh** the skill list to detect changes
# Statistics
Source: https://docs.coddo.ai/features/stats
Track your coding activity, costs, and productivity with visual analytics.
The Stats view gives you a **dashboard overview** of your coding activity across your project. It helps you track usage, costs, and productivity over time.
## Summary cards
Five KPI cards at the top show your totals:
| Metric | Description |
| ------------ | -------------------------------------------------- |
| **Chats** | Total chat sessions |
| **Messages** | Total messages exchanged with Claude Code or Codex |
| **Duration** | Total time spent in chat sessions |
| **Cost** | API usage cost in USD |
| **Tasks** | Total tasks (active and archived) |
## Activity heatmap
A GitHub-style **activity heatmap** shows your daily coding activity over the last 18 weeks. Each cell represents a day, and the color intensity shows how active you were.
## Charts
### Bar chart
Interactive bar chart to visualize trends over time. Switch between different metrics:
* **Cost** - Track your spending over time
* **Messages** - See message volume trends
* **Chats** - Monitor chat session frequency
* **Tasks** - Track task completion rate
Provider and model breakdown is also surfaced — so you can see how much you're using Claude vs Codex over time.
### Tasks distribution
A donut chart shows the distribution of your tasks across the 5 Kanban columns (Backlog, Todo, In Progress, Review, Done).
## Time granularity
View your data at two levels of detail:
* **Day** - Daily totals for trend analysis
* **Hour** - Hourly breakdown for detailed patterns
All statistics are computed from your local chat and task data. Nothing is sent to external servers.
# Voice Dictation
Source: https://docs.coddo.ai/features/voice-dictation
Dictate task instructions and chat messages directly inside Coddo, powered by OpenAI Whisper.
Voice dictation is built into every input field in Coddo. You click the mic, you speak, and the transcribed text lands in the field — ready to edit or send.
## Where it works
A **mic button** appears in:
* The **chat input** — for free chats with Claude Code or Codex
* The **task creation dialog** — for the title and instruction fields
One click to start recording, one click to stop. The text appears in place as soon as transcription finishes.
## How it works
Transcription runs on **OpenAI's Whisper** through the Coddo backend. Audio is sent for processing and is not retained beyond the processing window — nothing is stored on Coddo's servers.
Accuracy is strong on technical terms, file names, and spoken code fragments. Pinning the **transcription language** in Settings further improves accuracy on short utterances.
## Quotas
| Plan | Words per week | Max recording length |
| ---------------------- | -------------- | ------------------------ |
| **Free** | 1,000 words | 30 seconds per recording |
| **Basic subscription** | Unlimited | Unlimited |
The current usage is visible in Settings. Once the free quota is exhausted, dictation pauses until the start of the next week or until you upgrade.
Voice dictation requires a Coddo account so the quota can be tracked. All your project data still stays local.
## Settings
In **Settings → Voice dictation** you can:
* Choose the **transcription language** (default is auto, but pinning helps short clips)
* See your current weekly usage
* Open the upgrade flow if you want unlimited dictation
## Platform support
Voice dictation works on **macOS, Windows, and Linux** — anywhere Coddo runs. The mic uses your operating system's default audio input; pick the right input device in your OS sound settings.
## Use cases
* **Bug report on the fly** — describe the bug aloud while it's still in front of you, then send it as a task instruction
* **Long task briefs** — a 20-second voice brief carries more context than a hurried sentence typed between two screens
* **Hands-on flow** — kick off another task without leaving the file you're editing
## What about Whisper Island?
Coddo's voice dictation only works inside Coddo's input fields. If you want voice transcription **everywhere on your Mac** — Slack, Notion, your IDE, your browser, your mail client — install [Whisper Island](/whisper-island/index). It shares the same backend, the same account, and the same quota.
# Creating Your First Project
Source: https://docs.coddo.ai/guides/first-project
A step-by-step guide to setting up your first project in Coddo.
This guide walks you through creating a project in Coddo and getting it ready for AI-powered development.
## Step 1: Open Coddo
Launch Coddo from your Applications folder. If this is your first time, complete the [onboarding flow](/installation#first-launch) first.
## Step 2: Create or open a project
From the **sidebar**, you have two options:
### Create a new project
1. Click **New Project** from the sidebar
2. Choose a **parent directory** where the project folder will be created
3. Enter a **project name**
4. Coddo creates the folder and initializes it
### Open an existing project
1. Click **Open Project** from the sidebar
2. Navigate to your existing project folder
3. Coddo detects the project and initializes the `.coddo/` directory
## Step 3: Understand the project structure
When Coddo initializes a project, it creates a `.coddo/` directory:
```
your-project/
├── .coddo/ # Coddo data (auto-created)
│ ├── threads/ # Chat thread files
│ ├── attachments/ # Task images and attachments
│ ├── kanban.json # Kanban board state
│ └── settings.json # Project settings
├── CLAUDE.md # Claude Code instructions (optional)
├── AGENTS.md # Codex instructions (optional)
└── ... your code
```
The `.coddo/` directory is local to your machine. It is automatically added to `.gitignore` by Coddo.
## Step 4: Set up CLAUDE.md / AGENTS.md
Before chatting with your agent, create a `CLAUDE.md` (Claude Code) or `AGENTS.md` (Codex) file to give it context about your project. Use the [built-in editor](/features/claude-md) or create it manually — Coddo can also generate both with AI from your codebase.
Key things to include:
* Your tech stack and frameworks
* Build and run commands
* Coding conventions
* Important project rules
## Step 5: Create your first tasks
Switch to the **Kanban** view and start creating tasks:
1. Click **+ New Task**
2. Write a descriptive title
3. Add detailed instructions for the agent
4. Choose a provider (Claude Code or Codex), a model, and an execution mode (worktree or direct)
5. Optionally add tags and attach images
6. The task appears in the **Backlog** column
## Step 6: Start coding with your agent
1. Move a task to **Todo** - Coddo's queue runner automatically picks it up
2. Watch the task move to **In Progress** as the agent starts working
3. Click on the task to see the live conversation in the detail panel
4. When done, the task moves to **Review** - check the changes
5. Validate and merge (worktree) or commit (direct), then move to **Done**
## Tips for success
* **Write clear instructions** - The more specific your task instructions, the better the agent's output
* **Use worktree mode** for independent tasks that can run in parallel
* **Review changes carefully** - Check the diff before merging
* **Iterate** - If the first attempt isn't right, send another message from the review state
# Git Workflow
Source: https://docs.coddo.ai/guides/git-workflow
How to use Coddo's Git integration for a smooth version control workflow.
This guide covers how to use Git effectively within Coddo, from branching strategies to handling merge conflicts.
## Basic workflow
The typical Git workflow in Coddo follows these steps:
Open the **Git** view > **Branches** tab > click **+ New Branch**.
Name your branch descriptively (e.g., `feature/add-login`, `fix/header-bug`). Coddo automatically sanitizes branch names.
Create a Kanban task linked to the branch. Chat with Claude Code or Codex to implement the changes.
Open the **Changes** tab to see modified files. Stage the files you want to commit, write a message, and commit.
Click **Push** to upload your commits to the remote repository.
## Worktree-based workflow
When using **worktree mode** for tasks, Coddo manages branches automatically:
1. **Task created** - You select a base branch (e.g., `main`)
2. **Task starts** - Coddo creates a Git worktree with a dedicated branch (e.g., `coddo/1-fix-login`)
3. **Task runs** - The agent works in the isolated worktree
4. **Task completes** - You review changes and merge the branch
5. **Cleanup** - The worktree is removed after merging
This is ideal when working on multiple features simultaneously.
## Handling merge conflicts
When merging branches, conflicts can occur. Coddo helps you handle them:
1. **Detection** - Coddo detects conflicted files and shows them in a list
2. **Resolution** - Open conflicted files in your editor to resolve them
3. **Finalize** - After resolving all conflicts, finalize the merge
4. **Abort** - If needed, abort the merge to return to the previous state
## Remote operations
### Fetch
Download the latest changes from the remote without merging:
* Click **Fetch** in the Git view to update your local tracking branches
### Pull
Fetch and merge remote changes into your current branch:
* Click **Pull** to stay up to date with your team's changes
### Push
Upload your local commits to the remote repository:
* Click **Push** after committing your changes
## Branch management tips
* **Use descriptive names** - `feature/user-auth` is better than `branch1`
* **Branch per task** - Each Kanban task should have its own branch for clean history
* **Delete merged branches** - Clean up branches after they're merged
* **Stay up to date** - Regularly pull from the main branch to avoid large merge conflicts
* **Use worktree mode** - For parallel tasks, worktrees keep everything isolated
# Task Workflow
Source: https://docs.coddo.ai/guides/task-workflow
Understand the full lifecycle of a task - from creation to completion.
This guide explains how tasks move through the Coddo pipeline, from initial idea to completed work.
## The task lifecycle
```
Backlog > Todo > In Progress > Review > Done
```
Each stage represents a step in your development workflow:
### 1. Backlog
**Purpose:** Capture ideas and future work.
Add tasks here when you think of something that needs to be done, but you're not ready to work on it yet. Tasks in backlog are just placeholders - they don't need detailed instructions.
### 2. Todo
**Purpose:** Tasks queued for automatic execution.
When a task is moved to Todo, Coddo's **queue runner** automatically picks it up and starts executing it. Before moving a task here, make sure:
* The task has a clear **title**
* The **instruction** is detailed enough for the agent
* You've configured the **execution mode** (worktree, direct, or last used — the default is configurable in **Settings**)
* You've picked a **provider** (Claude Code or Codex) and a **model**
### 3. In Progress
**Purpose:** Tasks currently being executed.
When the queue runner picks up a task:
1. A **chat thread** is linked to the task (or created automatically)
2. If using **worktree mode**, a Git worktree is created
3. The agent (Claude Code or Codex) reads the task instruction and begins working
4. Progress is shown in real time (current tool, completed tools, todo items)
During execution you can:
* **Stop** the task to pause execution
* **Cancel** the task and move it back to backlog
* Watch the chat conversation in the detail panel
### 4. Review
**Purpose:** Verify completed work before marking as done.
After the agent finishes:
1. Review the changes in the **Chat** view (diffs, tool outputs)
2. For worktree tasks, validate and merge the branch
3. For direct mode tasks, commit and push changes
4. You can also send another message to ask for additional changes
### 5. Done
**Purpose:** Completed and reviewed tasks.
Move tasks here when you're satisfied with the result. Done tasks can be:
* **Archived** to clean up the board
* **Unarchived** if you need to revisit them
## Execution modes explained
### Worktree mode (default, recommended for parallel work)
```
main branch -----------------------------------
|-- coddo/1-fix-login (worktree)
|-- coddo/2-add-tests (worktree)
```
Each task gets its own Git worktree and branch. Up to **5 worktree tasks can execute in parallel**, configurable in Settings. Benefits:
* **Parallel execution** - Up to 5 tasks can run simultaneously
* **Isolation** - Changes don't interfere with each other
* **Clean merges** - Each task's changes are on a separate branch
### Direct mode (simpler workflow)
Tasks run on your current branch. Benefits:
* **Simpler** - No branch management needed
* **Faster** - No worktree creation overhead
* **Auto-commit** - Optionally commit changes automatically
Only one task can run in direct mode at a time, since they share the same working directory.
## Task + Chat relationship
Every in-progress task is linked to a chat thread. This means:
* Opening a task shows the full conversation in the detail panel
* The agent has the task instruction as context
* Duration from the chat is attributed to the task
* You can continue the conversation from the review state
## Best practices
1. **Break work into small tasks** - Smaller, focused tasks get better results than large, vague ones
2. **Write detailed instructions** - Include what you want, any constraints, and examples
3. **Use tags** - Categorize tasks (bug, feature, refactor) for better organization
4. **Review before marking done** - Always check the changes before completing a task
5. **Archive regularly** - Keep your board clean by archiving done tasks
# Introduction
Source: https://docs.coddo.ai/index
Coddo is a visual interface for Claude Code and Codex CLI - Chat, Kanban, and voice dictation in a desktop app.
## What is Coddo?
Coddo is a **desktop application** that gives you a visual interface for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and [OpenAI Codex CLI](https://platform.openai.com/docs/codex). Instead of working in the terminal, you get a beautiful chat UI, an integrated Kanban board to track task execution in real time, and built-in voice dictation to brief tasks at the speed of speech.
A native chat UI with streaming, tool use visibility, plan mode, and rich message blocks.
Track your tasks from backlog to done with drag-and-drop, filters, and real-time updates.
Create a task, pick a branch, and let Claude Code or Codex handle the rest automatically.
Dictate task briefs and chat messages with the built-in mic — powered by OpenAI Whisper.
Branches, commits, merges, and one-click AI conflict resolution — all without leaving the app.
Switch between projects instantly from the sidebar — all in a single window.
Extend Claude Code and Codex with reusable skills. Install from URL or generate them with AI.
Everything runs locally. Your conversations, code, and project data never leave your machine.
Available on macOS, Windows, and Linux (coming soon).
## How it works
Download Coddo for macOS or Windows from [coddo.ai](https://coddo.ai/download). Linux version is coming soon.
Create a new project or open an existing folder. Coddo initializes a `.coddo/` directory to store your chats and tasks locally.
Create tasks on the Kanban board, chat through the visual interface, dictate briefs by voice, and watch your tasks progress in real time.
## Whisper Island
Voice transcription, **everywhere on your Mac**. Speak in Slack, Notion, your IDE, your browser, or your mail client — and the text is pasted into the active app. Whisper Island shares the same account and quota as Coddo's built-in voice dictation.
Voice dictation across every macOS app, with a notch or pill overlay.
## Get started
Download and install Coddo on your machine.
Create your first project and run your first task in minutes.
Explore all the features Coddo has to offer.
Step-by-step guides for common workflows.
# Installation
Source: https://docs.coddo.ai/installation
Download and install Coddo on macOS or Windows.
## Prerequisites
Coddo runs on top of two CLIs: **Claude Code** (from Anthropic) and **OpenAI Codex CLI**. You don't need both — install whichever provider you want to use, or both to switch between them per task.
### Claude Code
Claude Code is a CLI tool from Anthropic. Install it with one of the following:
The simplest way to install Claude Code:
```bash theme={null}
curl -fsSL https://claude.ai/install.sh | bash
```
```bash theme={null}
brew install claude-code
```
If you already have Node.js installed:
```bash theme={null}
npm install -g @anthropic-ai/claude-code
```
Verify it works and authenticate:
```bash theme={null}
claude --version # Should print a version number
claude # Follow the prompts to authenticate
```
You need an active Claude subscription (Claude Pro, Team, or Enterprise) to use Claude Code.
### OpenAI Codex CLI
Codex CLI is OpenAI's coding agent. Install it via npm or Homebrew:
```bash theme={null}
npm install -g @openai/codex
```
```bash theme={null}
brew install codex
```
Verify it works and authenticate:
```bash theme={null}
codex --version # Should print a version number
codex # Follow the prompts to authenticate
```
You need an OpenAI account with API access to use Codex. Coddo supports the GPT-5.5, GPT-5.4, GPT-5.4 Mini, 5.3 Codex, and 5.3 Codex Spark models.
You can install either CLI on its own — Coddo will detect what's available and let you pick the provider per chat or per task. The provider step in onboarding can also be skipped if you want to configure it later from Settings.
## Download Coddo
Download the `.dmg` file from [coddo.ai](https://coddo.ai/download).
1. Open the `.dmg` file
2. Drag **Coddo** into your **Applications** folder
3. Open Coddo from Applications
Download the `.exe` installer from [coddo.ai](https://coddo.ai/download).
1. Run the `.exe` installer
2. Follow the installation steps
3. Open Coddo from the Start menu
If Windows SmartScreen flags the installer, click **More info** then **Run anyway** to proceed.
Linux version is coming soon.
## First launch
When you open Coddo for the first time, you'll go through a quick onboarding:
1. **Welcome screen** - Overview of Coddo
2. **Provider check** - Coddo detects which CLIs are installed (Claude Code, Codex, or both) and verifies they're authenticated. You can skip this step and configure providers later from Settings
3. **Login** - Sign in with your Coddo account (Google or email/password) — optional
4. **Ready** - You're all set to start using Coddo
Creating a Coddo account is free and optional. All your project data stays local on your machine regardless.
## Updates
Coddo checks for updates automatically. When a new version is available, you'll see a banner in the app. You can also check manually from **Settings → Check for updates**.
# Quick Start
Source: https://docs.coddo.ai/quickstart
Create your first project and run your first task in under 5 minutes.
## Create your first project
After completing the onboarding, you can add a project from the sidebar.
Click **New Project** or **Open Project** from the sidebar. For a new project, choose a parent directory and a project name. Coddo will create the folder and initialize it with a `.coddo/` directory for storing chats and tasks.
You can also open an existing project folder - Coddo will initialize the `.coddo/` directory automatically.
Once your project is open, you'll see:
* **Sidebar** (left) - Project switcher, task threads (todo/in-progress/review), and chat threads
* **Main area** (center) - The active view (Kanban, Chat, etc.)
Git, Statistics, and CLAUDE.md are accessible via the **more** button in the sidebar.
Switch to the **Kanban** view and click **+ New Task**. Give it a title, pick a provider (**Claude Code** or **Codex**) and a model, and write an instruction describing what you want the agent to do. For example:
```
Title: Add a README
Instruction: Create a README.md file with a project description,
installation instructions, and usage examples.
```
Move your task to the **Todo** column. Coddo's queue runner automatically picks it up, creates a chat thread, and starts the agent.
The agent will:
* Analyze your project
* Execute the changes
* Show you tool outputs and progress in real time
Click on the task to watch the conversation.
Once the agent finishes, the task moves to **Review**. Check the changes in the chat and the diff viewer. For worktree tasks, validate and merge the branch. Move your task to **Done** on the Kanban board.
## What's next?
Learn about all the chat features -streaming, plan approval, diffs, and more.
Master task management with columns, tags, and execution modes.
Understand the full lifecycle of a task from creation to completion.
Learn how Coddo integrates with Git for seamless version control.
# Overlay Modes
Source: https://docs.coddo.ai/whisper-island/features/overlay
Pick between the floating pill and the macOS notch overlay.
Whisper Island has two overlay modes. Both keep the window **always on top** and **click-through** outside the visible shape, so they never get in the way.
## Pill
A floating overlay near the top of the screen, centered horizontally. Works on every Mac.
* Compact when idle
* Animates when you're recording
* Can be hidden with `Cmd+Shift+H` and re-shown with the same shortcut
* Survives Spaces and full-screen apps — it stays put on the current desktop
The pill is the default mode. Pick this if you don't have a notch, or if you prefer a clearly visible indicator.
## Notch
The overlay tucks into the macOS notch area on MacBooks that have one. Visually, the pill sits inside the black notch space.
* Invisible when you don't need it
* Uses a private window level so it sits above the menu bar without stealing focus
* The visible shape is the only interactive area — the cursor passes through the rest of the window
The notch mode uses `nswindow-napi` and a few macOS workarounds (`SetFrameOrigin`, `DisableFrameConstraint`) to keep the window sitting at the top of the screen even after `constrainFrameRect`. If those fail to load (rare), Whisper Island falls back to a high `screen-saver` window level — the overlay still works, it just sits slightly below the notch.
### Switching modes
Change modes in **Settings → Display**. The old overlay is destroyed and a fresh one is created — no need to restart the app.
## Visibility shortcuts
| Shortcut | Action |
| ------------- | ------------------------------------------------------------------------ |
| `Cmd+Shift+H` | Show / hide the pill (no-op in notch mode) |
| `Cmd+Shift+L` | Expand / collapse the overlay (shows transcription state, history, etc.) |
## Why two modes?
The pill is for visibility — you always know where it is. The notch mode is for absence — the overlay only appears when you speak. Pick whichever matches the way you want to feel the app in your day.
# Recording Modes
Source: https://docs.coddo.ai/whisper-island/features/recording-modes
Push-to-talk vs toggle — pick the one that matches the way you dictate.
Whisper Island can record audio in two modes. Switch from **Settings → Recording**.
## Push-to-talk
**Hold the shortcut to record, release to transcribe.**
* Press and hold the mic shortcut
* Speak while holding
* Release the shortcut — recording stops and Whisper transcribes immediately
* The text is pasted into the active app via `Cmd+V`
Push-to-talk is best for short utterances and when you want full control over the start and end of each clip. There's no risk of leaving the mic on by mistake.
Push-to-talk uses a JXA helper that polls `CGEventSourceFlagsState` to detect when you release the modifier keys. The process exits as soon as the modifier mask is no longer fully held — no `System Events` fallback, no double-fire.
## Toggle
**Tap the shortcut to start, tap again to stop.**
* Tap the mic shortcut to start recording
* Speak
* Tap the shortcut again to stop and transcribe
Toggle is best for longer dictations — emails, task briefs, doc paragraphs — when you don't want to keep a key held down. The overlay clearly shows you're still recording.
## Which one should you pick?
| If you... | Use |
| ---------------------------------------------------------------------- | ---------------- |
| Dictate short messages and want zero false starts | **Push-to-talk** |
| Write long emails, docs, or task briefs | **Toggle** |
| Want a hands-free flow once recording starts | **Toggle** |
| Frequently switch between two-second corrections and longer dictations | **Push-to-talk** |
## What gets pasted
The text is written to the clipboard, then `Cmd+V` is simulated via `osascript … System Events keystroke "v"`. After 200 ms, the previous clipboard content is restored — unless you've enabled **Keep transcript in clipboard** in settings (see [Settings](/whisper-island/features/settings)).
Pasting requires **Accessibility access**. If the text doesn't appear in the active app, check **System Settings → Privacy & Security → Accessibility** and make sure Whisper Island is enabled.
## Hallucination filter
Whisper occasionally returns known hallucinations on silent or near-silent recordings (`sous-titres réalisés par…`, `merci`, `you`, etc.). Whisper Island filters these out automatically — if you didn't speak, nothing gets pasted.
# Settings
Source: https://docs.coddo.ai/whisper-island/features/settings
Customize Whisper Island — language, display mode, clipboard behavior, and more.
Open Whisper Island's settings from the tray menu (menu bar icon → **Settings**) or by clicking the gear on the overlay.
## Display
| Setting | Options | Description |
| ------------------ | ------------ | ------------------------------------------------------------------------------ |
| **Display mode** | Pill / Notch | Where the overlay lives. See [Overlay Modes](/whisper-island/features/overlay) |
| **Start at login** | On / Off | Launch Whisper Island automatically when you log in |
| **Show tray icon** | On / Off | Keep the tray icon visible in the menu bar |
## Recording
| Setting | Options | Description |
| ------------------ | --------------------- | ----------------------------------------------------------------------------------------- |
| **Recording mode** | Push-to-talk / Toggle | How the shortcut behaves. See [Recording Modes](/whisper-island/features/recording-modes) |
| **Input device** | System default | The OS audio input is used. Change in System Settings → Sound |
## Language
| Setting | Options | Description |
| -------------------------- | -------------------- | ---------------------------------------------------------- |
| **Transcription language** | Auto / FR / EN / ... | Pinning meaningfully improves accuracy on short utterances |
| **App language** | EN / FR | Whisper Island's own UI language |
## Clipboard
Whisper Island writes the transcript to the clipboard, simulates `Cmd+V`, and then restores your previous clipboard content after 200 ms.
| Setting | Description |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Keep transcript in clipboard** | If enabled, the transcript stays in the clipboard instead of being replaced by the previous content. Toggle live with `Cmd+Shift+V` |
| **Restore delay** | Time before the previous clipboard is restored (default: 200 ms) |
## Shortcuts
Rebind all four global shortcuts. See [Shortcuts](/whisper-island/features/shortcuts) for the full list and the rebinding flow.
## Account
| Action | Description |
| ----------------- | ---------------------------------------------------------- |
| **Sign in / out** | Manage your Coddo account session |
| **Usage** | See your current weekly transcription word count and limit |
| **Plan** | Free or Basic subscription |
Whisper Island shares its account, quota, and backend with [Coddo's voice dictation](/features/voice-dictation). Anything you transcribe in either app counts against the same weekly quota.
## Auto-update
| Setting | Description |
| --------------------- | --------------------------------------------------------------- |
| **Check for updates** | Manually check for a newer Whisper Island build |
| **Install update** | Visible when an update has been downloaded — restart applies it |
The **What's New** dialog opens once on first launch after a version bump, listing the changes for that release.
## Reset
If something goes sideways, you can:
* **Sign out** to clear your session (`auth.json` is encrypted with a machine-derived key — moving it between machines fails decryption and the file is recreated on next sign-in)
* **Reset settings** to factory defaults (overlay mode, shortcuts, language)
Both actions are reversible — re-sign-in or re-customize and you're back where you were.
# Shortcuts
Source: https://docs.coddo.ai/whisper-island/features/shortcuts
Global shortcuts for the mic, overlay visibility, and clipboard behavior.
Whisper Island registers a handful of **global shortcuts** so you can drive it from any app without bringing the window forward.
## Default shortcuts
| Shortcut | Action |
| ----------------- | ------------------------------------------ |
| `Cmd+Shift+Space` | Mic toggle / push-to-talk |
| `Cmd+Shift+H` | Show / hide the pill (no-op in notch mode) |
| `Cmd+Shift+L` | Expand / collapse the overlay |
| `Cmd+Shift+V` | Toggle clipboard inclusion |
All four are **rebindable** from Settings → Shortcuts.
## Rebinding
Open Settings → Shortcuts, click the shortcut you want to change, and press the new combination. Whisper Island pauses all global shortcuts while you're recording the new one to avoid accidental triggers, then re-registers them when you confirm.
Pick combos that include at least one modifier (`Cmd`, `Ctrl`, `Alt`, `Shift`). Single-key shortcuts would conflict with normal typing.
## Coexistence with Coddo Desktop
When Coddo Desktop is running, it creates a lockfile (`/tmp/coddo-desktop-active.lock`). Whisper Island detects this and the mic shortcut becomes a no-op so the same key combo doesn't double-fire — Coddo Desktop owns it instead.
Quit Coddo Desktop and Whisper Island reclaims the shortcut automatically.
## During onboarding
While the onboarding window is open, Whisper Island registers only a minimal set of temporary shortcuts. The full set is installed once you complete onboarding so you don't accidentally trigger transcription during the tour.
## Tray menu
The tray icon (menu bar) gives you menu-based access to the same actions: open Settings, show / hide the overlay, switch display mode, install pending updates, and quit.
# Whisper Island
Source: https://docs.coddo.ai/whisper-island/index
Voice transcription everywhere on your Mac. You speak, the text is pasted into the active app.
## What is Whisper Island?
**Whisper Island** is a macOS app from the Coddo team that turns voice transcription into a system-wide shortcut. You hold (or toggle) a global shortcut, you speak, and the transcribed text is pasted directly into the active app via `Cmd+V` — Slack, Notion, your IDE, your browser, your mail client. Anywhere, without leaving the window you're in.
The overlay lives in your MacBook's **notch**, or as a floating **pill** near the top of the screen. Always there, never in the way.
A floating pill near the top of the screen, or an overlay tucked into the MacBook notch. Pick the one that suits your workflow.
Hold a shortcut to record, release to transcribe. Or tap once to start, tap again to stop.
One login, one quota, two apps. Voice usage is shared with Coddo's integrated dictation.
Audio is captured locally and sent to the Coddo backend only for transcription. Your OpenAI key never leaves the server.
## How it works
By default `Cmd+Shift+Space`. Configurable from Settings.
Hold the shortcut (push-to-talk) or tap to start (toggle). The overlay lights up while recording.
Whisper Island writes the transcribed text into the active app via `Cmd+V`, then restores your previous clipboard.
## Designed to disappear
Whisper Island is built to be invisible between uses and pixel-perfect when you speak.
* The notch mode uses macOS-private window levels so the overlay sits above the menu bar without stealing focus.
* The pill mode is click-through except inside the visible shape — your cursor passes right through the rest of the window.
* When Coddo Desktop is running, the mic shortcut becomes a no-op so the same key combo doesn't double-fire.
## Who is it for?
If you write a lot every day — messages, docs, emails, task briefs — voice transcription gives you back hours every week. Whisper Island is designed for people who want the speed of voice without leaving the app they're already in.
## Get started
Download and install Whisper Island on your Mac.
Set up your shortcut and dictate your first message.
Choose between the pill and the notch overlay.
Push-to-talk vs toggle, and when to use each.
Whisper Island is **macOS only** for the moment. On Windows and Linux, you can still use Coddo's built-in [Voice Dictation](/features/voice-dictation) inside the Coddo app.
# Installation
Source: https://docs.coddo.ai/whisper-island/installation
Download and install Whisper Island on macOS.
## Requirements
* **macOS** (Apple Silicon or Intel)
* A **Coddo account** — used for transcription quota
* **Microphone access** and **Accessibility access** (Whisper Island will prompt you on first launch)
Whisper Island is macOS only for the moment. If you're on Windows or Linux, use [Coddo's built-in voice dictation](/features/voice-dictation) instead.
## Download
Get the latest `.dmg` from coddo.ai/whisper-island.
1. Open the `.dmg` file
2. Drag **Whisper Island** into your **Applications** folder
3. Open Whisper Island from Applications
## Grant permissions
On first launch, macOS will ask for two permissions. Both are required.
### Microphone
Whisper Island uses your default audio input to capture what you say. macOS shows the standard microphone prompt the first time you record. If you decline, re-enable it from **System Settings → Privacy & Security → Microphone**.
### Accessibility
Pasting text into other apps requires Accessibility access — Whisper Island simulates `Cmd+V` to inject the transcript. macOS shows the Accessibility prompt automatically. If you skipped it, enable Whisper Island in **System Settings → Privacy & Security → Accessibility**.
Without Accessibility access, transcription succeeds but the text isn't pasted into the active app.
## Sign in
After permissions, sign in with your **Coddo account**. The login opens in your browser and comes back to the app via a deep link (`coddo://`). Your session is stored locally and encrypted with a machine-derived key — moving the file to another Mac will not work, you'd sign in again.
If you don't have a Coddo account yet, you can create one for free during this step.
## Updates
Whisper Island checks for updates automatically. When an update is downloaded, the tray menu shows **Install update (vX.Y.Z)** — click it to restart and apply the new version. A short **What's New** screen opens once on first launch after a version bump.
# Quick Start
Source: https://docs.coddo.ai/whisper-island/quickstart
Set up Whisper Island and dictate your first message in under 2 minutes.
## 1. Pick an overlay mode
Open Whisper Island's settings (tray icon → **Settings**) and choose:
* **Pill** — a floating 420 × 120 overlay near the top of the screen. Works on any Mac.
* **Notch** — the overlay sits inside your MacBook's notch area. Best on notched MacBooks.
Switch any time — the overlay reshapes itself live.
## 2. Pick a recording mode
In Settings → Recording:
* **Push-to-talk** — hold the shortcut, speak, release. Best for short utterances.
* **Toggle** — tap to start, tap to stop. Best for longer dictations.
## 3. Bind a shortcut
The default mic shortcut is `Cmd+Shift+Space`. Change it in Settings → Shortcuts. You can also rebind:
| Shortcut | Action |
| ----------------- | ----------------------------- |
| `Cmd+Shift+Space` | Mic toggle / push-to-talk |
| `Cmd+Shift+H` | Show / hide the pill |
| `Cmd+Shift+L` | Expand / collapse the overlay |
| `Cmd+Shift+V` | Toggle clipboard inclusion |
## 4. Try it
Click into the text field of any app — Slack, Notion, your IDE, Safari, Mail.
Hold (push-to-talk) or tap (toggle) the mic shortcut. The overlay lights up.
Say something. Release the shortcut, or tap again to stop. The overlay shows a quick "transcribing" state.
The transcribed text appears in the focused field. Done.
## 5. Pick a language
In Settings → Language, choose the language you usually dictate in. Whisper auto-detects, but pinning the language meaningfully improves accuracy on short utterances.
## What's next?
Deep dive into pill vs notch behavior.
Push-to-talk vs toggle — when to use each.
Customize every shortcut Whisper Island uses.
Language, clipboard behavior, autostart, and more.