Quickstart

This page takes you from the download to a first chat. It needs no Codz account, and everything on it is part of the free app.

Before you start

You need a Mac with macOS 14 or later. Codz is a universal app for Apple silicon and Intel.

You also need the agents you want to run. Codz drives each one’s own command-line tool with that tool’s login, so install the CLI and sign in to it the way it asks. These are the install guides Codz itself links to:

OpenRouter needs no CLI: you connect your OpenRouter account in Settings ▸ Models & providers. DeepSeek, a preview, needs the DeepSeek Harness runtime and an API key you paste on the same page. Providers & logins covers every provider, and signing in with more than one account.

Install Codz

1. Download Codz from codz.com/download.
2. Unzip the archive.
3. Move Codz.app into your Applications folder.
4. Open Codz.

The download page also links the archive’s SHA-256 checksum (Verify SHA-256) if you want to check it.

Walk through setup

The first time Codz opens, it walks you through a short setup in its main window. Some steps appear only when they apply, everything you choose can be changed later, and Skip setup asks once, then jumps to the end with the defaults.

1. Welcome. Click Start.
2. Your agents. Codz looks for each agent’s CLI and the history it has already written on this Mac. It reads local files only and never launches an agent to find one. A row marked Not installed has an Install button that opens that agent’s install guide, and Rescan looks again.
3. Permission. Shown only when an agent’s data is on this Mac but macOS refused the read. Click Open System Settings, switch Codz on under Privacy & Security ▸ Full Disk Access, and come back: the step moves on by itself. Continue without it skips it.
4. Project. Shown only when you have no projects yet. A project is a named set of folders Codz is allowed to touch. Codz suggests the folders your agents have worked in most; pick one or more, or choose a folder yourself, then give the project a name and click Create project.
5. Trust. Choose where new chats start. Full access edits files on its own and asks before running commands, Ask answers questions without editing files, and Plan proposes a plan and edits nothing until you approve it. You can change the mode in any chat.
6. Appearance. Pick an accent and a theme, and whether Codz opens at login and shows the number of working agents in the menu bar.
7. Extras. Signing in for synced history and connecting your phone are both optional, and both are part of Codz Pro. Click Continue to skip them.
8. Ready. Click Open Codz, or Start a chat in the project you just created.

To see setup again, choose Codz ▸ Setup Assistant…, or open Settings ▸ General and click Replay next to Replay welcome. Nothing is reset.

Run your first chat

1. Click New chat at the top of the sidebar, or press ⌘N.
2. Click Choose project in the composer and pick a project, or Choose folder… to use any folder.
3. Pick a model from the model button in the composer.
4. Type what you want done and press Return.

The agent’s work streams into the chat. Files it changes stay one click away in the rail beside it, and by default a command it wants to run waits for you to allow or deny it. Press ⌘. to stop a turn. Modes & approvals explains what each mode lets an agent do.

To add more projects later, choose File ▸ New Project… (⌘⇧N).

If the agent isn’t ready

The composer tells you before you send, and keeps your draft:

• Set up Claude (or another agent) means its CLI wasn’t found on this Mac. For Claude Code, Codex and Cursor, Install Claude (and so on) installs a copy that Codz manages. For OpenCode and DeepSeek, Setup guide opens the install guide. Then click Check again.
• Connect OpenRouter or Connect DeepSeek means the account or key is missing. Add it in Settings ▸ Models & providers.
• You’re not signed in to Claude (or Codex) means the CLI has no working login. Click Sign In and finish in your browser; Codz picks it up as soon as you’re done.

Keep an eye on your agents

Codz also sits in the menu bar as a bolt, with the number of agents working right now beside it. Click it for the working agents, your plan limits and the local servers on this Mac, and click Open Codz to bring the window back. The menu bar keeps watching your agents while the window is closed, and Launch at login starts Codz when you sign in to your Mac.

Menu bar & widgets covers the popover and the desktop widgets.

Use Codz from the terminal

Codz’s command-line tool, codz, is the app’s own executable, and the download doesn’t add it to your shell. Link it once:

mkdir -p ~/.local/bin
ln -s /Applications/Codz.app/Contents/MacOS/Codz ~/.local/bin/codz

Add ~/.local/bin to your PATH if your shell doesn’t already include it, then run codz doctor to check data access and your agent CLIs. CLI overview lists every command.

Troubleshooting

An agent shows as not installed

A row marked Not installed means Codz found neither the agent’s CLI nor any history it wrote. Install the agent (the row’s Install button opens its guide), sign in to it, then click Rescan. Outside setup, open Settings ▸ General and click Check now next to Re-run environment check.

An agent needs Full Disk Access

A row marked Needs Full Disk Access means the agent’s data is on this Mac but macOS refused the read. Click Fix, or open System Settings ▸ Privacy & Security ▸ Full Disk Access and switch Codz on. If setup then says Still blocked, click Relaunch Codz, or quit and reopen Codz: macOS sometimes needs a relaunch before it notices the new permission.

Next steps