Getting started

This guide walks you from a fresh install to your first shipped change: connect a repository, launch a Workspace, review what the agent did, and open a pull request. The whole pass takes a few minutes.

1. Install and open

Cohalen is a desktop app for Windows, macOS, and Linux, currently in early access. Join the waitlist and we'll send you a build. Download it, open it, and sign in.

2. Connect GitHub

A GitHub connection lets Cohalen push, open pull requests, and merge as your GitHub account, and author your commits as you. Authorize it once. The connection is only needed before you push or ship; if you skip it now, the app prompts you inline at your first push.

3. Connect a repository

A Repository is the git source your Workspaces branch from (defined fully in Core concepts). Connect one: open a folder that is already a git repository, or clone one from a remote. Your clone stays on your machine, and new Workspaces branch from it.

4. Launch your first Workspace

A Workspace is one unit of parallel work: an isolated git worktree owned by one agent (Core concepts has the full definition). Launch one, choose the agent (Claude Code, Codex, or Cursor), and give it a task. For example:

Add a rate limiter to the /api/waitlist route:
- 5 requests per minute per IP
- return 429 with a Retry-After header
- cover it with a test

The agent works in the background. Launch more Workspaces to run several agents at once; each has its own worktree, so they never step on each other's files.

Every Workspace has a spend cap, enforced by the Spend kill-switch and on by default. When a Workspace reaches its cap, its agent stops, so a runaway loop can't turn into a runaway bill.

5. Review the Changeset

When the agent finishes its turn, open the Diff. It shows the Changeset: everything the task changed, as one whole, and the same set of files the pull request will contain. Leave a Note on a diff line for the agent to address, or edit the file yourself.

6. Check and ship

Checks is the last pass before Ship. It aggregates every signal that decides whether the Workspace can merge (Git status, Check runs, Deployments, Notes, and Todos) into a single Verdict at the top, such as Uncommitted changes or Ready to merge; a blocked Workspace reads as blocked, with a count of what remains. The Verdict drives one contextual action at a time:

1. Commit & push
2. Create the pull request
3. Merge

Cohalen executes the merge through your GitHub connection; branch protection on GitHub still applies.

Next: Core concepts, the full model behind these steps.