Overview

A chat runs one agent in one project folder. You choose the model, describe the task, and Codz runs the provider for you: Claude Code, Codex, Cursor or OpenCode through its own command-line tool and your existing login, or an OpenRouter or DeepSeek model with your own key.

Everything the agent does lands in the transcript as it happens. Codz stops and asks when the agent needs a decision from you, and keeps every file it touched one click away in the rail.

The main window

• Sidebar. Your projects with their chats, and New chat at the top. Chats you ran in Claude Code, Codex, Cursor or OpenCode outside Codz are listed too. See Projects & sidebar and Imported history.
• Header. The chat’s title, and Chat options (…) with Rename…, Export transcript…, Open in Terminal and more. See Continue outside Codz.
• Transcript. Your prompts, the agent’s work and its answers.
• Composer. Where you write, attach files and choose the model and what the agent may do. See Composer.
• Rail. Panels beside the chat for activity, Git, a terminal, files, a browser and more. Open it with ⌥⌘B. See Workspace.

Start a chat

1. Click New chat in the sidebar, or choose File ▸ New Chat (⌘N).
2. Click Choose project above the prompt, and pick a project, a recent folder or Choose folder….
3. Leave the location on Local to work in the folder itself, or choose Isolated to give the chat its own Git worktree and branch. In a Git repository, the branch chip beside it sets the branch the chat starts from; picking another branch switches the folder to it, and asks first if you have uncommitted changes.
4. Check the model chip at the right of the composer and the access chip at the left.
5. Describe the task and press ↩.

An empty chat asks “What should we build?”, naming your project once you have chosen one. It starts on the first model in your loadout (see Models & loadout) and in your default mode, Full access unless you changed it (see Modes & approvals). An isolated chat waits while Codz creates its checkout, which Git & worktrees explains.

If you press ↩ before choosing a project, Codz opens the project menu. If the model’s provider isn’t set up, a card above the composer says what is missing and keeps your draft; see Providers & logins.

How a turn reads

While the agent works, the turn shows Working for and the time so far, what the agent last said, and the command it is running. Its steps appear as they happen: Thinking… while it reasons, a row for each command, file read and edit, and a shell box with a command’s output and Success or Exit code at its foot.

When the turn ends with an answer, its steps fold under Worked for … and the answer sits below. Click that line to open the steps again. A turn that ends without an answer keeps its steps open.

Some things always stay in view, outside the folded steps:

• Approvals and questions waiting for you. See Modes & approvals.
• Commands that failed or that you denied.
• Pictures a tool returned, such as a screenshot.
• The change card, with Undo and Review. See Reviewing changes.
• Notices where a turn stopped, such as a spent usage limit or an expired login.

Under the latest answer, and any answer you point at, are Copy response, Send the prompt again and Branch in new chat. Point at one of your prompts for Copy message and Edit message, which opens a new chat branched just before that prompt, with the prompt in the composer to change. A branch shares the project folder with the original chat; files are not rewound.

When the agent keeps a to-do list, a Step pill above the composer shows how far along it is. Click it for the checklist, or open the Plan panel in the rail.

Stop a turn

Click the stop button where the send button was, press Esc in the composer, or choose Chat ▸ Stop Generating (⌘.). The work line then reads You stopped after ….

Stopping keeps your draft, and leaves in place anything the agent already changed. If follow-ups are queued, the next one starts. While an approval is waiting, Esc denies it instead of stopping the turn.

Follow up while it works

While a turn runs, the prompt reads “Send a follow-up”. A message you send then waits in Up next above the composer and goes when the turn ends, in the order you queued it. Open Up next to reorder, edit or remove a message.

• To stop the running turn and send the new message straight away, set Settings ▸ Agent & composer ▸ Follow-up behavior to Interrupt and continue.
• With Claude Code and Codex, ⌘↩ delivers a message into the running turn instead of queuing it, while ↩ is your send key.

See While the agent works for the details.

Find your way in a long chat

• Once a chat has four or more prompts and the window has room, short dashes down the left of the conversation mark each one. Point at a dash to preview the prompt, click to jump to it, or press ⌥↑ and ⌥↓ to step between prompts.
• ⌘F finds text in the conversation.
• Chat ▸ Copy Conversation (⌘⇧C) copies the whole chat.
• Chat ▸ Focus Composer (⌘L) puts the cursor back in the prompt.

Goals

A goal says what “done” means for a chat. Type /goal, or choose Chat options ▸ Set goal…, and fill in:

• Outcome: one concrete result.
• Constraints: rules that hold while the agent works.
• Verification: criteria you tick off once the evidence is in.
• Status: Active, Paused, Blocked or Completed.

While a goal is Active, Codz includes it with every message you send in that chat, whichever provider runs it. A Goal bar above the composer shows it; its … menu pauses, resumes, blocks or completes it, and a click on the bar edits it. A goal never sends a message, approves an action or changes the chat’s mode by itself.

Schedules

Chat options ▸ Schedule task… sends a request in the chat on a timetable: Once, Daily, Weekdays or Weekly, at the time you choose.

• Schedules are read-only. The chat has to be in Ask or Plan; a schedule never widens what the agent may do.
• Codz must be open and the Mac awake. A run more than 90 seconds late is skipped, and the reason goes into the schedule’s Run history.
• No approval is automatic. If the provider asks, the run pauses and waits for you.
• The schedule records the chat’s provider, mode, location and model. Changing one of them blocks the runs until you edit the schedule.

Suggested tasks

Claude can suggest work it noticed but didn’t do. In chats that began in Claude’s desktop app, each suggestion shows as a Suggested task card:

• Start with worktree starts a new chat on the same provider and login, in its own worktree, with Claude’s brief as the first message.
• More start options offers Start locally, Send to cloud and Fix in this session, which sends the brief into the current chat.
• The ✕ dismisses a card, and Restore brings it back. Once started, the card shows the new chat’s status and Open.

If a chat won’t start

• ↩ does nothing on a new chat. Choose a project first; Codz opens the project menu for you.
• A card says “Set up …” or “Connect …”. The provider isn’t installed or connected. See Providers & logins.
• The prompt reads “Loading conversation…”. Codz is still reading the chat’s history. Sending and switching models wait until it has loaded.
• The turn ends with “The agent hit an error”. The row quotes the provider’s own message. When a Codex model needs a newer CLI, the row says Codex needs an update and offers Update Codex….

More about agents