# Carbon Docs

> How to install and use Carbon, the desktop app for coding agents.

Carbon is a free, open-source macOS app that runs coding-agent CLIs (Claude Code, Codex, pi, fx and Grok Build) in one chat window, many sessions at once, each optionally in its own git worktree. Download it from https://carbonhq.sh. Its `carbon` command line (`curl -fsSL https://carbonhq.sh/install.sh | sh`) lets you or an agent create, list and message sessions, save drafts, link issues, share a dev server by public link and drive the built-in browser. Carbon can also run headless on a Linux server and be driven from the Mac app. Reach for these docs to answer what Carbon can do, where in the app a feature lives, and the exact steps, commands and flags.

## Docs

- [Introduction](https://carbonhq.sh/docs): Carbon is a Mac app that runs coding agents in one window, many at a time. Start here to see what it does and where to read next.
- [Connect a server](https://carbonhq.sh/docs/server): Connect a Linux server to the Mac app over SSH. Carbon installs itself there, and your agents run there, not on your laptop.

## Get started

- [Install Carbon](https://carbonhq.sh/docs/get-started/install): What Carbon needs, how to download and install it, how to add an agent CLI, and what happens on first launch.
- [Your first session](https://carbonhq.sh/docs/get-started/first-session): Attach a project, pick an agent, choose a worktree or your own checkout, send a prompt, and follow the agent's work.
- [Updates and channels](https://carbonhq.sh/docs/get-started/updates): How Carbon updates itself, how to join the beta channel, check for updates by hand, read the changelog, and keep the carbon CLI and your agents current.

## Using Carbon

- [Agents](https://carbonhq.sh/docs/using-carbon/agents): The five agent CLIs Carbon runs (Claude Code, Codex, pi, fx and Grok Build), what each supports side by side, how to sign in to each, and what is particular to each one.
- [The composer](https://carbonhq.sh/docs/using-carbon/composer): Pick an agent, model, effort, fast mode and permission mode, send while a turn runs, stop a turn, and read how full the context is.
- [Writing prompts](https://carbonhq.sh/docs/using-carbon/prompts): Use slash commands, mention files with @, tag issues with # and other sessions with &, attach images and files, dictate, and save a task as a draft.
- [Permissions and questions](https://carbonhq.sh/docs/using-carbon/permissions): Answer an agent's permission requests and questions, approve a plan, and know what happens to an open request after a restart.
- [Worktrees](https://carbonhq.sh/docs/using-carbon/worktrees): Run a session in its own copy of the repository, see where it lives and what it starts from, and delete it when the work is done.
- [Sessions and the sidebar](https://carbonhq.sh/docs/using-carbon/sessions): Find sessions in the sidebar, read its marks and groups, pin, settle, set aside, fork, rename and delete sessions, and move between them from the keyboard.
- [Profiles](https://carbonhq.sh/docs/using-carbon/profiles): Group projects into profiles, like work and personal, switch between them in the sidebar, and keep other profiles' sessions and notifications out of sight.
- [Spaces and Pages](https://carbonhq.sh/docs/using-carbon/spaces): Write Markdown Pages, link them to projects, and work on them with agents.

## carbon CLI

- [The carbon command](https://carbonhq.sh/docs/cli): Install the carbon CLI, keep it up to date, and see every command it has for sessions, drafts, issues, the browser, sharing and servers.
- [Sessions](https://carbonhq.sh/docs/cli/sessions): Start, list and message Carbon sessions from the command line, with every flag for model, effort, agent, base branch, issues and fast mode.
- [Orchestration](https://carbonhq.sh/docs/cli/orchestration): Have one agent fan work out into several sessions, review its work with a second model, and pass messages between parent and child sessions.
- [Drafts](https://carbonhq.sh/docs/cli/drafts): Save a task for later with carbon draft, list saved drafts, and start or remove them.
- [Issues](https://carbonhq.sh/docs/cli/issues): Tag a session with the Linear or GitHub issues its work is against using carbon issue link, and remove tags with carbon issue unlink.
- [Browser](https://carbonhq.sh/docs/cli/browser): Drive a session's own browser with carbon browser — open pages, read them, click and type, take screenshots and record videos.
- [Share](https://carbonhq.sh/docs/cli/share): Publish a session's dev server as a public link with carbon share, list live links, and take them down.
- [Servers](https://carbonhq.sh/docs/cli/servers): Make a machine a Carbon server with carbon server, give it a public address, and manage the app's list of servers with carbon machine.

## Settings

- [Settings](https://carbonhq.sh/docs/settings): Open Settings with the gear or ⌘, and find what each tab holds — appearance, spaces, servers, accounts, transcription, integrations, shortcuts, the changelog and About.
- [Accounts](https://carbonhq.sh/docs/settings/accounts): See which account Claude Code, Codex, pi, fx, Grok Build and gh are signed in as, sign in through Terminal or with an API key, reauthorize, sign out, and hide an agent from the picker.
- [Issues](https://carbonhq.sh/docs/settings/issues): Connect Linear with an API key or GitHub through gh, browse and filter issues on the Issues page, change status and priority, tag issues in prompts with #, and see the issues linked to a session.
- [Dictation](https://carbonhq.sh/docs/settings/dictation): Download a speech model, pick a microphone, and dictate into the composer with ⌘D. Transcription runs on your Mac; audio never leaves it.
- [Appearance](https://carbonhq.sh/docs/settings/appearance): Pick a theme and light, dark or system mode, cycle them with ⌘⌥T and ⌘⌥L, zoom the whole app with ⌘= ⌘- ⌘0, and choose where the side panel opens.
- [Notifications](https://carbonhq.sh/docs/settings/notifications): How Carbon tells you a session finished, needs permission or asked a question — a macOS banner, an in-app card, or nothing — plus the ready-to-merge card, ⌘G, the sidebar marks and the dock badge.
- [Shortcuts](https://carbonhq.sh/docs/settings/shortcuts): Every default keyboard shortcut in Carbon, and how to rebind, remove or reset one in Settings → Shortcuts.

## Reference

- [Remote access and sharing](https://carbonhq.sh/docs/reference/remote-access): Keep sessions running after you quit, connect the app to other machines, reach this Mac from another one, share a dev server by public link, and update remote servers.
- [Data on disk](https://carbonhq.sh/docs/reference/data): What Carbon keeps in ~/.carbon, what goes when you delete a session, the environment variables you can set, and where each agent keeps its own data.
- [Privacy](https://carbonhq.sh/docs/reference/privacy): Exactly which analytics events Carbon sends and what they carry, what is never sent, how to turn analytics off with `CARBON_NO_ANALYTICS`, and how surveys and the website measure visits.
- [Troubleshooting](https://carbonhq.sh/docs/reference/troubleshooting): Fixes for common problems — a missing or logged-out agent, a stuck session, a dead permission card, a refused carbon command, silent dictation, missing notifications, gh, worktrees, rate limits — and where the logs are.

## Agent skills

- [carbon-docs](https://carbonhq.sh/docs/.well-known/agent-skills/carbon-docs/SKILL.md): Read the Carbon Docs instead of answering from memory. How to install and use Carbon, the desktop app for coding agents. Use when a task involves Carbon Docs: how it works, how to set it up or configure it, or its API.

## Agent resources

- [llms-full.txt](https://carbonhq.sh/docs/llms-full.txt): The full Markdown of every page in one file.
- [Page Markdown](https://carbonhq.sh/docs/index.md): Append `.md` to any page URL to fetch that page as raw Markdown.
- [JSON API](https://carbonhq.sh/docs/api/docs/pages.json): Page index of the JSON docs API; each entry links the page's JSON and Markdown forms. Described by the OpenAPI document at https://carbonhq.sh/docs/openapi.json.
- [Agent skills](https://carbonhq.sh/docs/.well-known/agent-skills/index.json): Agent Skills discovery index of the skills this site publishes.
- [API catalog](https://carbonhq.sh/docs/.well-known/api-catalog): RFC 9727 linkset of the APIs documented here.
- [AI catalog](https://carbonhq.sh/docs/.well-known/ai-catalog.json): ARD manifest of the agent-facing resources on this site (MCP server, skills, APIs).
- [agent-readability.json](https://carbonhq.sh/docs/agent-readability.json): Manifest of every agent-facing artifact on this site.
- [Sitemap](https://carbonhq.sh/docs/sitemap.xml): Every indexable page URL with its last-modified date.