Reference
Settings
Every page of the Settings window in Codz for Mac, with its rows, their defaults and what each one changes.
The Settings window holds Codz’s preferences for this Mac. Its sidebar groups pages under preferences, agents, workspace and account. This page walks through each one in that order, with each row as it appears and a link to the page that explains the feature in full.
Open Settings
- Choose Codz ▸ Settings… or press ⌘,.
- Click Help and settings (the question mark at the bottom of the sidebar), then Settings. The same menu has Keyboard shortcuts, which opens that page directly.
- Open the account menu at the bottom of the sidebar and choose Settings.
- In the command palette, type a setting’s name. Choosing a result opens its page.
Type in Search settings at the top of the Settings sidebar to narrow the list of pages.
General
How Codz starts and behaves on this Mac, in five groups: Application, Startup, Keep awake, Feedback and Setup.
| Setting | What it does |
|---|---|
| Launch at login | Opens Codz when you sign in to your Mac. Off by default. |
| Show in Dock | Keeps Codz in the Dock and the app switcher. On by default. |
| Menu bar count | Shows the number of agents working in the menu bar. On by default. |
| Keep windows on top | Floats Codz above other windows. Off by default. |
| Restore last task | Returns to the task you had open after Codz relaunches. On by default. |
| Prevent sleep while running | Keeps the Mac awake while a local agent turn is running. On by default. |
| Keep running when the lid closes | Keeps local tasks and manual sessions running with the lid shut, including on battery. Needs the Codz helper. Off by default. |
| Darken display and keyboard when closed | Saves and restores built-in brightness on supported Macs. Requires an open-lid sample; unavailable controls are reported. On within closed-lid mode by default. |
| Low Power Mode when closed | Uses Low Power Mode on battery while closed, then restores the previous mode. Off by default. |
| Mute audio when closed | Mutes the output while closed and restores it on opening or reconnection. Off by default. |
| Lid recovery | Shows pending device restoration. Retry checks it again. After a crash, reopen Codz to restore saved brightness and audio. |
| Closed-lid helper | Shows whether the helper is installed. Set up… installs it. |
| Remove closed-lid helper | Remove restores the previous sleep setting and unregisters the helper. Do this before deleting Codz. |
| Low-battery cutoff | The battery level, from 10% to 50%, at which keep-awake lets go. 20% by default. |
| Manual sessions | Choose a preset, a custom duration from 1 minute to 30 days, or indefinitely. Click a running timed session to add time; Stop ends it. A manual session ends when the Codz host quits or the Mac sleeps. |
| Send feedback | Send Feedback… opens the feedback form. See Get help. |
| Ask for feedback after a screenshot | When you take a screenshot of Codz, offers to send it to the Codz team with a note. On by default. |
| Re-run environment check | Check now looks again for provider CLIs, local data and Full Disk Access. |
| Replay welcome | Replay walks through setup again. Nothing is reset. |
Appearance
The interface, the transcript and code, in three groups: Theme, Transcript and Code and diffs.
| Setting | What it does |
|---|---|
| Base theme | System (the default), Light or Dark. |
| Accent color | Blue (the default), green, orange, purple or graphite, used for selection, links and active controls. |
| High-contrast dark theme | Stronger edges and a deeper dark canvas. Off by default. |
| Reduce transparency | Opaque surfaces for panes and overlays. Off by default. |
| Reduce motion | Less navigation and state-change animation. Off by default. |
| Text size | Small, Medium (the default) or Large, for conversation and settings text. |
| Transcript width | Narrow, Medium (the default) or Wide, the widest the conversation column gets. |
| Code theme | Syntax colours for the file editor: Xcode (the default), Cursor or Codz. |
| Code font | A monospace font installed on your Mac. Leave it blank for the system font. |
| Code block word wrap | Wraps long code lines instead of scrolling sideways. On by default. |
| Tinted diff backgrounds | Shades added and removed lines in file changes and in the Git panel’s diffs. On by default. |
Notifications
When Codz asks for your attention, in two groups: Task notifications and Live agent monitor.
| Setting | What it does |
|---|---|
| Turn completions | When a finished chat posts a notification: Always, When Codz is in the background (the default) or Never. |
| Approval requests | Notifies when an agent stops for your approval or asks you a question, whichever provider it runs on. On by default. |
| Completion sound | Plays a sound when an agent finishes. Off by default. |
| Draw attention | Bounces the Dock icon for approval requests while Codz is in the background. On by default. |
| External agent completions | Notifies when a Cursor, ChatGPT or Claude run Codz is monitoring finishes after at least 30 seconds. On by default. |
| Agent memory | Notifies once when your agents’ processes pass the size below, with what is idle enough to reclaim. On by default. See Performance. |
| Alert at | The size the agent memory alert speaks at, from 4 GB to 64 GB. Sessions, their helpers and Codz’s chats count; desktop apps don’t. 8 GB at first. |
| macOS notification permissions | Open Settings opens notification settings in System Settings, for alerts, sounds and Focus. |
Agent & composer
Defaults for new tasks and how every provider talks to you, in three groups: New tasks, Personalization and Memory. See Modes & approvals and Composer.
| Setting | What it does |
|---|---|
| Default model | Names the model new tasks start on, the first in your loadout. Edit loadout opens Default models. |
| Default mode | Ask, Plan or Full access (the default). In Full access the agent edits files without asking and commands still stop for approval. |
| Default approvals | Reviewed, Accept edits (the default), Auto or Full auto: how much an agent may do without asking in new tasks. |
| Submit messages | Return (the default) or ⌘ Return sends a message. |
| Follow-up behavior | Queue for next turn (the default) lets the current turn finish first; Interrupt and continue stops it and continues with your newest message. |
| Continue on another provider | When a provider hits its usage limit, keeps the task going on the next ready model in your loadout. On by default. |
| Pick the model automatically | New chats start on Auto, which picks one of your loadout models for each message. Each pick costs a fraction of a cent on your connected OpenRouter account. Off by default. |
| Personality | Friendly, Pragmatic (the default) or None. Changes tone, not technical judgment. |
| Custom instructions | Added to every new provider turn. Never put secrets here. |
| Use local memory | Adds your notes to future turns. Off by default. When on, Remember holds the notes and Clear memory erases them. |
Prompts
Manage saved prompts for this Mac and the projects you have added. New prompt creates one; Edit changes an existing prompt. Shared project prompts live in .codz/prompts as Markdown files. Choose a saved prompt from + in the composer, review it, then send it.
Keyboard shortcuts
| Setting | What it does |
|---|---|
| Send message | Return or ⌘ Return. The same setting as Submit messages on Agent & composer. |
| Application | The list of Codz’s shortcuts, for reference. |
| Restore shortcut defaults | Reset sets the send key back to Return. |
The send key is the only shortcut you can change. Every shortcut is listed in Keyboard shortcuts.
Snapshots
Turn on Snapshots to attach a picture of an open window to your draft. Codz asks for Screen Recording access to list and capture windows. In the composer, choose + ▸ Snapshot and pick a window, or set a shortcut to capture the front window from another app. The shortcut can be changed, reset or turned off here.
Voice
Dictate into the composer instead of typing: click the microphone beside the send button, or press ⌥⌘V. The transcript lands in your draft; only Send sends it.
| Setting | What it does |
|---|---|
| Microphone | System default or a microphone you pick. Test microphone records up to ten seconds and plays it back; that audio stays on this Mac. |
| Dictation shortcut | How ⌥⌘V starts and stops a recording: Auto (a quick press toggles, holding records until you let go, the default), Hold or Toggle. |
| Transcribe with | Off (the default; nothing is sent), This Mac, a paired Mac, or OpenAI, Grok Voice Transcribe or OpenRouter through a Mac’s key. |
| Language | Auto lets the model detect it, or pick one the model transcribes. Models that translate offer Translate to English. |
| Models | Pick the languages you speak to see the models that transcribe them, with accuracy and speed from Handy’s benchmark. Download, Use model, Test model and remove are on each row; Use existing uses a model file another app already downloaded. |
| Advanced | Hardware: Auto (the GPU, else the CPU), CPU or a GPU. Unload model: free the model’s memory after it sits idle, 15 minutes by default. |
| Silence filtering | Skips silence before transcription. On by default. |
| Remove filler words | Drops “um” and “uh”. On by default. |
| Dictionary | Names and terms spelled your way, with aliases for what transcription keeps writing instead. Shared dictionary is kept on the Mac that transcribes, for every project or one you pick. |
| Clean up transcripts | A text model fixes punctuation, numbers and spoken corrections before the words go in, with built-in or custom instructions, a Correction cue and a Cleanup model. Off by default; it sends text, never audio. |
Default models
Your loadout: the models the composer offers, in order. New chats start on the first. See Models & loadout.
- Selected models shows the loadout as cards, the first marked as the default. Drag a card to reorder, click it to change its provider, model, effort or Fast, and drag it off the row or use Remove from Loadout to take it out. The first nine cards have the shortcuts ⌃⌘1…9.
- Reset goes back to the models Codz picks for you.
- All models has a column per provider: Claude Code, ChatGPT, Cursor, OpenCode and OpenRouter, plus DeepSeek once its runtime is installed. Click a model to add it, or drag it onto a slot. Long lists have Search models, and a provider that is not ready offers Set up ….
Models & providers
Each provider’s status, versions, logins and defaults. Codz applies CLI defaults without storing credentials; the OpenRouter and DeepSeek keys stay in this Mac’s Keychain. See Providers & logins.
| Group | What it holds |
|---|---|
| Provider status | A row per provider: whether it is ready, its version and where it was found. Update appears when a newer Claude Code, Codex or Cursor CLI is available. |
| Local CLI versions | For Claude Code, Codex and Cursor: Update, Choose version… and Restore previous. Codz installs its own copy and keeps your existing installation. |
| New models | Newly announced models and whether your installed CLI lists them yet. Source opens the announcement. |
| Claude, ChatGPT, Cursor, OpenCode | Continue in … opens the provider’s own app for the settings it owns, and Default model sets the model for new chats (blank uses the provider’s default). |
| Claude accounts, ChatGPT accounts, Cursor accounts, OpenCode accounts | CLI login, the CLI’s own login, and any accounts you added. Use for new chats picks the default; Add … account adds a second login, which for Cursor is an API key. |
| OpenRouter | Connect OpenRouter, or paste an API key; the spend on the key, the model list and a Default model. |
| DeepSeek | A preview: where the runtime is, your API key and a Default model. |
| Configuration on disk | Open folder for Claude’s, Codex’s, Cursor’s and OpenCode’s configuration folders. |
Provider groups also hold that provider’s options:
- Claude: Effort; Prompt suggestions (on by default); Safe mode, which turns off CLAUDE.md, skills, plugins, hooks, MCP servers and other customizations for troubleshooting; Show chats in Claude Desktop; Claude in Chrome; and Bypass permissions, which asks you to confirm because it lets Claude run commands without approval.
- ChatGPT: Config profile, Reasoning effort and Ephemeral sessions, which stops ChatGPT saving new session files.
- Cursor: none of its own. Whether Cursor writes its edits without asking follows the chat’s approval level. See Cursor and OpenCode.
Agent extensions
What shapes Claude, ChatGPT and Cursor before a turn starts: instructions, skills, commands, subagents, MCP servers, hooks and plugins. Provider files stay the source of truth, and Codz never imports their secrets. See Agent extensions.
- Manage integrations: Manage opens a window to discover sources, install and update plugins, and manage MCP authentication through the providers’ own commands.
- Inventory: Scope covers the selected task’s project plus your user extensions, with Refresh; Provider filters by provider; Find searches names, kinds, scopes, providers and paths.
- A summary of the estimated context cost per turn, skills, tools and automation, and anything to review, then every extension found, grouped by kind.
- How context is used explains when each kind reaches the model, and Provider guides links to Codex’s, Claude’s and Cursor’s documentation.
MCP servers
Add and manage the MCP servers Codz starts for its chats across providers. Add server accepts STDIO commands or Streamable HTTP URLs; you can also paste a server's JSON configuration. Saving checks the connection and reports the tools it found or why the check failed. Entered credentials stay in your Keychain.
Browser & tools
Local workspace tools and provider web access, in three groups: Provider tools, Browser panel and macOS permissions.
| Setting | What it does |
|---|---|
| Web search | Lets supported providers search the web. On by default. |
| Web fetch | Lets supported providers read page contents. On by default. |
| Computer use | Lets agents control Mac apps from the Computer panel. On by default. See Computer use. |
| Issue tracker | Lets Claude, ChatGPT, Cursor, OpenCode and OpenRouter read, file, move and comment on the project’s issues. On by default. The tracker is part of Pro; see Issues. |
| Mobile Development | Shows iOS and Android build, run and device tools for mobile projects. On by default. |
| Browser tools | Turns on the Browser panel. On by default. See Browser. |
| Open links in Browser panel | Opens transcript links beside the task instead of in your default browser. On by default. |
| Persist sessions | Shared across tasks (the default) keeps cookies and local storage between launches; Don’t keep discards them. |
| Blocked sites | One host per line. The Browser panel won’t open them. |
| Browser data | Clear… removes the Browser panel’s cookies, caches, local storage and permissions, signing you out of sites there. |
| Computer control | Open Privacy Settings to review the Accessibility and Screen Recording access computer use needs. |
| Always-allowed apps | The apps computer use may control without asking. Reset to be asked again. |
| Locked use | Lets computer use work while the Mac is locked, keeping the screen covered. Stores your Mac password behind Touch ID. Off by default. |
Git
Branch names, diff display and GitHub, in four groups: Branches, Diffs, Attribution and GitHub. See Git & worktrees.
| Setting | What it does |
|---|---|
| Branch prefix | Added to the start of branch names Codz suggests. codz/ by default; clear it for no prefix. |
| Syntax colouring | Colours code in the Git diff viewer, as in the file editor. On by default. |
| Commit attribution | Adds a Co-authored-by: Codz trailer to commits you make in the Git panel. Off by default. |
| GitHub CLI | Where gh is installed. If it isn't, Install adds Codz's own copy for pull requests and cloning, without touching Homebrew or your PATH. |
| Sign-in | The GitHub account gh is signed in to. Connect… signs in with a one-time code. Codz signs in through gh and never stores a GitHub token. |
Whether a task works in the project folder or an isolated worktree is chosen per task. Isolated checkouts that outlive their chats are listed under History.
History
Archived chats and the checkouts Codz keeps. See Imported history.
| Setting | What it does |
|---|---|
| Active tasks, Archived tasks | How many tasks are in the sidebar and in the archive. |
| Archived chats | Each archived chat, with Restore and Delete…. Archive a chat from its ••• menu to move it here. |
| Retained checkouts | Isolated checkouts kept after their chat was deleted, with Reveal and Remove…. Removing deletes only a clean working directory; the branch stays. |
| Chats from other apps | Chats you start in ChatGPT’s Codex mode, Claude Code, Cursor or OpenCode appear in the sidebar as they begin. Refresh rescans all four. |
Data & refresh
How fresh each kind of data is, and your local task history. See Storage & memory and Data & privacy.
| Setting | What it does |
|---|---|
| Agent activity | Updated within a second while agents work. |
| Provider history | Updated within 5 seconds. |
| Usage & performance | Updated within 15 seconds; Performance every second while its page is open. |
| Local-first history | Chat, usage, browser captures and project context stay on this Mac. |
| Cursor usage | Read from Cursor’s signed-in usage API. Codz never invents totals when it is unavailable. |
| Export local task history | Export… saves a private JSON copy of Codz task transcripts and metadata. |
| Delete local task history | Delete… removes Codz’s task records. Provider-owned transcripts, synced usage totals and isolated checkouts are kept. This cannot be undone. |
Connections
Control this Mac from your phone with Codz Remote, a Pro feature. The page opens with your Mac’s own card, under its name. Projects your phone can use and Capability diagnostics appear once Allow connections is on.
| Setting | What it does |
|---|---|
| ⋯ ▸ Rename… | Next to your Mac’s name: the name your devices show. Only devices signed in to your Codz account see it. |
| Version | The Codz version this Mac runs, and Update to … when a newer one is ready. |
| Allow connections | Turns Remote on for this Mac and shows its status, such as Online. Needs a Pro account to turn on. |
| Keep this Mac awake | Prevents sleep while the Mac is plugged in and Remote is on. Off by default. |
| Open Codz at login | Keeps the Mac reachable after a restart. The same setting as Launch at login on General. |
| Devices that can control this Mac | Add device connects an iPhone or iPad. Each connected device has Revoke access; one marked Requires authorization waits for Allow or Deny. |
| Projects your phone can use | The folders a phone may see and control. Add Project… approves one; Remove takes it back. |
| Apps on this Mac | Let other apps use Codz lets Claude Code, Claude Desktop, Cursor and Codex use Codz through its MCP server. On by default. Add… adds it to Claude Code or Codex with their own command; Copy copies the entry for Cursor and Claude Desktop. |
| Capability diagnostics | Which tools this Mac can offer a phone right now. |
Permissions
Review macOS access for Codz, check whether the app recognizes its grants, and choose when agents ask for approval. Use Check permissions to refresh this Mac’s status.
Members
Choose your team to view its members, invitations and available seats. Owners and admins can invite people, change roles and manage access. Actions depend on your role and the member's status. See Teams.
Account
Your Codz account and plan on this Mac. See Codz account and Sync & profile.
Signed out, the page offers Sign up and Sign in (your browser handles sign-in, and Codz never sees your password) and lists what Codz Pro adds. Signed in, it shows:
| Setting | What it does |
|---|---|
| Your name and email | Edit profile opens your settings on codz.com. |
| Your plan | Upgrade to Pro, Manage plan, or View plan when Pro comes through your team. See Billing. |
| Sync usage to | With more than one account or team, which one receives new syncs. See Teams. |
| Log out on this Mac | Signs this Mac out. Chats, projects and history stay. |
| Sync usage | Keeps this Mac’s token history in your account, a few minutes behind. Pro. |
| Upload all history | Shows sync progress. Sync now syncs straight away. |
| Service address | Where this Mac signs in. Leave it at https://codz.com. |
| Device ID | This Mac’s identifier. Copy it when support asks for it. |