# Getting started

From an installed coding tool to your first conversation in Zoltbot.

macOS · Early release

## Before you begin

Start with Claude Code or Codex if you already use one. Zoltbot uses your tool’s existing authentication; connecting a coding agent is separate from signing in to a Zoltbot account.

- A Mac running macOS 13 or later.
- At least one installed coding-agent CLI, signed in with its own provider account or configured API access.
- For a source build: Node.js 24, pnpm 11, and Git.

## Get the app

Check the [download page](https://zoltbot.ai/download) for a packaged macOS build. If a download is unavailable, build the public checkout from source. The public README currently documents this source-build path.

```sh
git clone https://github.com/zoltlabs/zoltbot.git
cd zoltbot
pnpm install --frozen-lockfile
pnpm dev:ui
```

- Keep the UI server running. In a second terminal in the same folder, run `pnpm dev:desktop`. This opens the Mac app.
- Source builds leave hosted features disabled unless configured. Local agent setup does not require enabling them.

## Connect your coding agents

Already skipped setup? Open **Settings → Coding agents**, then **Open workspace setup**. This diagnostics screen is also called Doctor.

1. Choose **Get started** in workspace setup. Zoltbot checks this Mac for installed coding tools.
2. On **Connect your coding agents**, select an installed tool. If sign-in is required, use **Sign in**, finish in the window that opens, then choose **Check again**.
3. Choose **Connect** for the selected agents. Setup creates starter profiles for the connected tools.
4. Review the session and MCP-server import steps. Read the consent text and choose what to include; you do not need old sessions to start a new chat.

## Send your first message

In a new chat, sending a message starts the coding tool. **Connect** loads the tool’s commands and modes ahead of time; it is optional before your first message.

1. On **You’re all set**, pick a project, or choose **No project** for a first trial.
2. Choose an agent and enter a small request in **First message**, such as: “Explain what you can help me with. Do not change any files.”
3. Choose **Start**. If you leave the message empty, **Open chat** opens the conversation instead.
4. Read the reply and respond to any question or approval request before continuing.

## Work in a code folder

Create a workspace and set its **Code folder** to the repository you want the agent to work in. Use **Choose code folder** or enter its absolute path. A workspace without a code folder gives each chat its own private app folder.

Before asking for changes, confirm the folder and the profile’s permissions. If the agent cannot connect, follow [Troubleshooting](https://zoltbot.ai/docs/troubleshooting).