Skip to content
Back to search

codealong

MarketplaceWorks with Claude CodeGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/codealong--codealong/badge.svg)](/listings/codealong--codealong)

HTML

<a href="/listings/codealong--codealong"><img src="/api/listings/codealong--codealong/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

On macOS

With [Homebrew](https://brew.sh), which also puts the `codealong` command on your PATH:

brew install --cask codealong/tap/codealong

Or by hand:

1. [Download `Codealong.dmg`](https://www.codealong.com/download), the [latest release](https://github.com/codealong/codealong/releases/latest)'s. 2. Open it and drag Codealong into Applications. 3. Open Codealong.

It runs on Apple silicon and Intel Macs, is signed and notarized by Apple, and keeps itself up to date: when a new version is ready, *Restart to update* shows at the foot of the sidebar. Prefer to build it yourself? See [Building from source](#building-from-source).

On Linux

Download an `.AppImage`, `.deb` or `.rpm` (x86_64 or aarch64) from the [latest release](https://github.com/codealong/codealong/releases/latest); each is signed for automatic updates (`.deb` and `.rpm` install updates when you choose *Restart to update*). Or build it from source, under X11. You need Rust 1.96 or later, Node 22.13 or later (not 23), and Zig 0.17.0; Zig builds the Ghostty terminal library Codealong uses. On Ubuntu 24.04 and Linux Mint 22.x, install the system packages Tauri needs:

sudo apt update
sudo apt install -y build-essential curl wget file git pkg-config libssl-dev \
  libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev \
  librsvg2-dev libxdo-dev

Install Zig and add it to your `PATH`:

mkdir -p "$HOME/.local/zig"
curl -fsSL "https://ziglang.org/download/0.17.0/zig-$(uname -m)-linux-0.17.0.tar.xz" |
  tar -xJ --strip-components=1 -C "$HOME/.local/zig"
export PATH="$HOME/.local/zig:$PATH"

If Linuxbrew's `pkg-config` is earlier on your `PATH` and bundling reports `Can't detect any appindicator library`, point it at Ubuntu's package metadata:

export PKG_CONFIG=/usr/bin/pkg-config
export PKG_CONFIG_PATH="/usr/lib/$(gcc -print-multiarch)/pkgconfig:/usr/share/pkgconfig"

Then clone and build:

git clone https://github.com/codealong/codealong.git
cd codealong
npm ci
npm run tauri build -- --bundles deb   # the binary in ../codealong-target/release, the .deb in its bundle/deb

Each session Codealong starts runs in tmux, shown in your terminal emulator: Ghostty, kitty, WezTerm, Alacritty, foot, Konsole, GNOME Terminal, Ptyxis, Xfce Terminal or xterm (`$TERMINAL` picks one). Keys are Linux's: ⌘ is Ctrl, and ⌥ and ⌃ are Alt. A few things are macOS's alone, the notch, the Claude and Codex apps, and Antigravity's and Cursor's usage among them; [the development notes](docs/development.md#linux) say what else differs.

On Windows

An early build: download the x64 or Arm64 setup `.exe` from the [latest release](https://github.com/codealong/codealong/releases/latest) (it isn't signed with a Windows code-signing certificate yet, so SmartScreen warns; updates are signed and go in at *Restart to update*), or build from source. It builds, its tests pass and it runs on Windows 11 on Arm, but it hasn't had much use there. With Visual Studio's C++ build tools (and their clang, on Arm), Rust, Node, [Git for Windows](https://gitforwindows.org) and [Zig](https://ziglang.org) 0.17:

git clone https://github.com/codealong/codealong.git
cd codealong
npm install
npm run tauri build -- --no-bundle   # codealong.exe in ..\codealong-target\release

Sessions open in [Windows Terminal](https://aka.ms/terminal), running their commands in Git Bash, as Claude Code does on Windows. Keys are as on Linux. Codealong's own terminals aren't there yet, nor typing into a session's terminal, finding its tab or bringing it forward, besides what Linux goes without; [the development notes](docs/development.md#windows) say what else differs.

**You'll need:**

- macOS 13 or later, Linux under X11, or Windows 10 (version 2004) or later (early build), where sessions open in Windows Terminal - At least one coding agent: [Claude Code](https://code.claude.com/docs), the

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 18 lines
  1. {
  2. "name": "codealong",
  3. "owner": {
  4. "name": "Codealong"
  5. },
  6. "metadata": {
  7. "description": "Codealong's plugin for Claude Code: the codealong command and its skill."
  8. },
  9. "plugins": [
  10. {
  11. "name": "codealong",
  12. "source": "./plugin",
  13. "description": "Codealong todos, sessions and accounts from Claude Code. Needs the Codealong Mac app.",
  14. "version": "0.29.0",
  15. "license": "Apache-2.0"
  16. }
  17. ]
  18. }
README.md · README · 1,196 lines
  1. <p align="center">
  2. <img src="src-tauri/icons/128x128@2x.png" alt="" width="112" height="112" />
  3. </p>
  4. <h1 align="center">Codealong</h1>
  5. <p align="center"><strong>Every coding agent you run, in one window.</strong></p>
  6. <p align="center">
  7. Answer your agents from your MacBook's notch. Have an agent review every pull request,<br />
  8. on the plans you already pay for. Start work from any app, on the account with room.
  9. </p>
  10. <p align="center">
  11. It works beside the agents you already run: Claude Code, Codex, OpenCode, Antigravity and Cursor,<br />
  12. in your own terminal and in their desktop apps, on every account and machine you have.<br />
  13. Free and open source, for macOS and Linux.
  14. </p>
  15. <p align="center">
  16. <a href="https://www.codealong.com/download"><img src="docs/images/download.svg" alt="Download for macOS" width="232" height="48" /></a>
  17. </p>
  18. <p align="center">
  19. or <code>brew install --cask codealong/tap/codealong</code>
  20. </p>
  21. <p align="center">
  22. <a href="https://github.com/codealong/codealong/releases/latest"><img src="https://img.shields.io/github/v/release/codealong/codealong?label=release&color=1f6feb" alt="Latest release" /></a>
  23. <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache_2.0-1f6feb" alt="Apache License 2.0" /></a>
  24. <a href="#what-works-with-each-agent"><img src="https://img.shields.io/badge/macOS_13%2B_%C2%B7_Linux-555" alt="macOS 13 or later, and Linux" /></a>
  25. <a href="https://github.com/codealong/codealong/stargazers"><img src="https://img.shields.io/github/stars/codealong/codealong?style=flat&color=d4a72c" alt="Stars on GitHub" /></a>
  26. </p>
  27. <p align="center">
  28. <a href="https://www.codealong.com"><strong>codealong.com</strong></a>
  29. &nbsp;·&nbsp; <a href="#get-started">Get started</a>
  30. &nbsp;·&nbsp; <a href="#a-tour">Tour</a>
  31. &nbsp;·&nbsp; <a href="#what-works-with-each-agent">Supported agents</a>
  32. &nbsp;·&nbsp; <a href="#faq">FAQ</a>
  33. &nbsp;·&nbsp; <a href="docs/guide.md">Full guide</a>
  34. &nbsp;·&nbsp; <a href="#on-linux">Build for Linux</a>
  35. </p>
  36. <p align="center">
  37. <img src="docs/images/notch-demo.webp" alt="A short film of the bar docked in the MacBook notch, over a dusk landscape, working through what waits on you: Command-Return allows a session's git push and goes on to a session that asks a question, an answer is picked, a teammate's pull request that an agent already reviewed is approved, three finished turns are marked seen, and the notch closes with nothing waiting and six agents at work." width="100%" />
  38. </p>
  39. <p align="center">
  40. <sub>Everything that waits on you, a keystroke each, over whatever app you're in:<br />
  41. allow a command, answer a question, sign off on a pull request an agent has reviewed.</sub>
  42. </p>
  43. ## Why Codealong
  44. Running coding agents in parallel gets messy fast: a dozen terminal tabs, the Claude and Codex
  45. apps, two or three accounts, and no way to tell which agent is waiting on you without clicking
  46. through all of them. Then the pull requests they open pile up, waiting on a review.
  47. **Codealong works beside the agents you already run. There's nothing to move into.** It finds
  48. every agent session on your machine, wherever it started, shows what each one is doing, and brings
  49. the ones that need you to wherever you are. Keep starting agents in your own terminal and in the
  50. Claude, Codex and Cursor apps: Codealong reads the records each one already writes. It doesn't
  51. wrap, proxy or replace anything, and it needs no account, no API key and no server.
  52. ## Every agent, account and machine on one board
  53. <p align="center">
  54. <picture>
  55. <source media="(prefers-color-scheme: dark)" srcset="docs/images/sessions-dark.webp" />
  56. <img src="docs/images/sessions-light.webp" alt="Codealong's Sessions view: every agent session on two machines in one list, each with an emoji beside its title to know it by, the three that need you first, then finished turns and running agents. One open on the right wants to run git push, with Deny, Always and Allow. Plan usage for every account runs across the top." width="100%" />
  57. </picture>
  58. </p>
  59. Every session from every agent and account, wherever you started it: your terminal tabs,
  60. background jobs, the Claude and Codex apps. Sorted into *Needs you*, *Your turn*, *Working*, *In
  61. review* and *Idle*, and organized the way your work is:
  62. **project → repo → worktree → branch → pull request**.
  63. - **Read and reply.** Any session's whole conversation, with its tool calls, images and links,
  64. searchable, and a box to reply. Or double-click to open it where it lives: its exact terminal
  65. tab, its Claude app session or its Codex thread.
  66. - **Know where your plan limits stand.** Each account's limits along the window's foot, always in
  67. view, and what your sessions used against what your plans cost.
  68. - **All your machines.** Link them and each shows the others' sessions beside its own; allow it,
  69. and you answer an agent on your desktop from your laptop. An
  70. [iPhone app](https://github.com/codealong/codealong-ios) is on the way.
  71. ## Keep the agents you already run, where you run them
  72. Apps that host your agents, in their own window or their own terminal panes, see only what you
  73. start inside them. Codealong sees what you already run, and leaves it running where it is.
  74. - **Start agents the way you do now.** In your own terminal, as a background job, in the Claude,
  75. Codex, Cursor or Antigravity app. Each shows on the board as it starts: nothing has to be
  76. launched from Codealong, and the quick panel is there for when it's quicker.
  77. - **The desktop apps are on the board too.** A Claude app session or a Codex thread sits beside
  78. your terminal sessions, with its conversation and its status. It takes your reply from
  79. Codealong, and a double-click opens it in its own app.
  80. - **Each agent stays its maker's.** Its own tools, prompts and permission rules, and its new
  81. features the day they ship. Nothing sits between an agent and its model.
  82. - **Nothing to move out of, either.** Quit Codealong and every agent in your terminal or its app
  83. carries on, asking you the usual way.
  84. [What works with each agent](#what-works-with-each-agent) says what Codealong can do with every
  85. one. Where it can't act, it opens the session where it lives.
  86. ## An agent reviews every pull request, at no extra cost
  87. <p align="center">
  88. <picture>
  89. <source media="(prefers-color-scheme: dark)" srcset="docs/images/pr-review-dark.webp" />
  90. <img src="docs/images/pr-review-light.webp" alt="The PRs view: a teammate's pull request waiting on your review, which an agent has read first. Its pill says Agent approves, and its Reviews tab shows the review the agent drafted on your account, with a comment on a line of the migration and a box to approve, comment or ask for changes." width="100%" />
  91. </picture>
  92. </p>
  93. Turn on automatic reviews and each pull request that asks for your review is read by an agent
  94. first, on the account, model and effort you pick, told what to look for by instructions you can
  95. edit. It leaves a **draft review on your own GitHub account**, its comments on the lines they're
  96. about, for you to finish and submit; it can approve for you when it finds nothing that needs
  97. fixing. The PR waits on you only once the agent is done, new commits are reviewed again, and your
  98. sign-off is one keystroke from the notch.
  99. - **No new bill.** A review is an ordinary agent session on the Claude or ChatGPT plan you already
  100. pay for, on whichever account has room. No review bot to pay for by the seat, no API key, no
  101. charge by the token. The Analytics window shows what your sessions would have cost at API prices,
  102. against what your plans cost.
  103. - **Nothing to install on GitHub.** No GitHub App, no admin to ask, no review service in between:
  104. the agent runs on your machine in your checkout, reads the PR through your own `gh` sign-in, and
  105. your code goes only to the model provider you already use.
  106. - **Another model reads what one wrote.** The reviewer prefers another agent than the one that
  107. wrote the PR: Codex reviews what Claude Code wrote, and the other way round.
  108. - **Your own agents' PRs too.** Each PR a session of yours opens can be reviewed the same way, and
  109. the review handed back to the session that wrote it to fix, before a teammate looks. Nothing
  110. goes on GitHub.
  111. - **Shared with your team.** A `.codealong/config.toml` committed to the repo carries what every
  112. review looks for, and which verdicts an agent may never submit.
  113. *Review with…* (⌃⌘R) starts the same review by hand on any PR, and *Ask* puts questions to an agent
  114. that has read the whole diff. More in
  115. [Pull requests, with their agents](#pull-requests-with-their-agents).
  116. ## Your notch is an inbox for your agents
  117. Codealong docks in your MacBook's notch. Closed, it counts everything that waits on you: agents
  118. that want to run something, questions, pull requests to review, finished turns. Press **⌥⌘.** in
  119. any app and it opens on the agent that has waited longest, with the call it wants to run and
  120. **Allow**, **Always** and **Deny**. **⌘⏎** answers and brings up the next one. You never leave
  121. your editor.
  122. - **Approvals, questions and replies.** A question comes as choices to pick, with a box for an
  123. answer of your own. Deny a call and say what to do instead in the same keystroke.
  124. - **Pull requests too.** A PR waiting on your review is in the same queue, with its diff and its
  125. checks: ⌘⏎ approves it.
  126. - **No notch needed.** An external display gets one drawn for it. Or float the bar over every app,
  127. as it does on Linux, keep it in the menu bar, pin a session to your desktop, or work through
  128. everything in the *Waiting on you* window.
  129. - **Later is a key away.** ⌃⌘1 to ⌃⌘7 snooze what can wait, ⌃⌘8 until its usage limit lifts or
  130. the day its reply says the work goes on, and a short sound says when something new needs you.
  131. Approvals and questions are answered there for Claude Code, OpenCode, Antigravity's command line
  132. and any agent you run inside Codealong, and approvals for Codex's and Cursor's command lines in the
  133. terminals that let Codealong answer them; the rest show what they wait on and open where they ask
  134. ([what works with each agent](#what-works-with-each-agent)). More in
  135. [Answer agents without switching apps](#answer-agents-without-switching-apps).
  136. ## Say what you want done, from any app
  137. <p align="center">
  138. <picture>
  139. <source media="(prefers-color-scheme: dark)" srcset="docs/images/quick-dark.webp" />
  140. <img src="docs/images/quick-light.webp" alt="The quick panel: a prompt typed, the todo it matches found, and the agent menu open on Auto, which would start it on claude-work with Opus, above each account's plan usage and models." width="720" />
  141. </picture>
  142. </p>
  143. Press **⌥⌘/** and type. Codealong finds the session, todo or pull request you mean, by its title,
  144. its branch or what was said in it. Or keep typing a prompt and start it: in the worktree it belongs
  145. in or a new one, in a terminal tab, in the background or in the Claude or Codex app, on this
  146. machine or another of yours.
  147. Leave the account on *Auto* and the work goes where there's room: an account near its plan's limit
  148. is passed over, and among the rest it picks the one whose week resets soonest, so no week's
  149. allowance goes unused. More in
  150. [The quick panel](#the-quick-panel-say-what-you-want-done).
  151. ## And a lot more
  152. - **[Todos your agents can work.](#todos-your-agents-can-work)** A list for work you mean to hand
  153. an agent, which agents read, pick up and finish themselves.
  154. - **[Schedules.](#schedules)** Start a session, or message one, every weekday at 9, when a deploy
  155. goes out, when a PR merges or its checks fail. Nothing is spent watching: an agent runs only
  156. when something happens.
  157. - **Sessions that pick themselves back up.** Out of plan usage mid-task? A Claude Code session
  158. offers to move to an account with room and carry on, or moves by itself if you let it. Lid closed
  159. and the network dropped? It's told to carry on once the connection is back.
  160. - **Agents that hear about their PRs.** Turn on nudges and a review, a request for changes or a
  161. failing check goes to the session that opened the PR, which takes it from there. It's never told
  162. to merge.
  163. - **[A board your agents can read too.](#a-board-your-agents-can-read-too)** With the `codealong`
  164. command, agents see what the others are doing in the same repo, message one another and hand
  165. work to another model. One can keep watch over all of them for you.
  166. - **Ask on the side.** `/side <question>` asks a throwaway copy of a session, which never hears of
  167. it. Fork a session, or switch its model or effort, without starting over.
  168. - **[Boards and a canvas](#boards-and-the-canvas)**, and **[voice](#voice-and-meetings)**: your
  169. work as a Kanban or laid out in space, a key held to talk, a session that takes a meeting's
  170. notes. Experiments, off until you turn them on.
  171. - **An app you can change.** Press **⌥⌘,** and a session opens on Codealong's own source, with a
  172. picture of every window: describe what to change, and it improves Codealong itself.
  173. If Codealong is useful to you, [star it](https://github.com/codealong/codealong/stargazers): it's
  174. how other people who run agents find it.
  175. ## Get started
  176. ### Install
  177. #### On macOS
  178. With [Homebrew](https://brew.sh), which also puts the `codealong` command on your PATH:
  179. ```bash
  180. brew install --cask codealong/tap/codealong
  181. ```
  182. Or by hand:
  183. 1. [Download `Codealong.dmg`](https://www.codealong.com/download), the
  184. [latest release](https://github.com/codealong/codealong/releases/latest)'s.
  185. 2. Open it and drag Codealong into Applications.
  186. 3. Open Codealong.
  187. It runs on Apple silicon and Intel Macs, is signed and notarized by Apple, and keeps itself up to
  188. date: when a new version is ready, *Restart to update* shows at the foot of the sidebar. Prefer to
  189. build it yourself? See [Building from source](#building-from-source).
  190. #### On Linux
  191. Download an `.AppImage`, `.deb` or `.rpm` (x86_64 or aarch64) from the
  192. [latest release](https://github.com/codealong/codealong/releases/latest); each is signed for
  193. automatic updates (`.deb` and `.rpm` install updates when you choose *Restart to update*). Or build
  194. it from source, under X11. You need Rust 1.96 or later, Node
  195. 22.13 or later (not 23), and Zig 0.17.0; Zig builds the Ghostty terminal library Codealong uses.
  196. On Ubuntu 24.04 and Linux Mint 22.x, install the system packages Tauri needs:
  197. ```bash
  198. sudo apt update
  199. sudo apt install -y build-essential curl wget file git pkg-config libssl-dev \
  200. libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev \
  201. librsvg2-dev libxdo-dev
  202. ```
  203. Install Zig and add it to your `PATH`:
  204. ```bash
  205. mkdir -p "$HOME/.local/zig"
  206. curl -fsSL "https://ziglang.org/download/0.17.0/zig-$(uname -m)-linux-0.17.0.tar.xz" |
  207. tar -xJ --strip-components=1 -C "$HOME/.local/zig"
  208. export PATH="$HOME/.local/zig:$PATH"
  209. ```
  210. If Linuxbrew's `pkg-config` is earlier on your `PATH` and bundling reports `Can't detect any
  211. appindicator library`, point it at Ubuntu's package metadata:
  212. ```bash
  213. export PKG_CONFIG=/usr/bin/pkg-config
  214. export PKG_CONFIG_PATH="/usr/lib/$(gcc -print-multiarch)/pkgconfig:/usr/share/pkgconfig"
  215. ```
  216. Then clone and build:
  217. ```bash
  218. git clone https://github.com/codealong/codealong.git
  219. cd codealong
  220. npm ci
  221. npm run tauri build -- --bundles deb # the binary in ../codealong-target/release, the .deb in its bundle/deb
  222. ```
  223. Each session Codealong starts runs in tmux, shown in your terminal emulator: Ghostty, kitty,
  224. WezTerm, Alacritty, foot, Konsole, GNOME Terminal, Ptyxis, Xfce Terminal or xterm (`$TERMINAL`
  225. picks one). Keys are Linux's: ⌘ is Ctrl, and ⌥ and ⌃ are Alt. A few things are macOS's alone,
  226. the notch, the Claude and Codex apps, and Antigravity's and Cursor's usage among them;
  227. [the development notes](docs/development.md#linux) say what else differs.
  228. #### On Windows
  229. An early build: download the x64 or Arm64 setup `.exe` from the
  230. [latest release](https://github.com/codealong/codealong/releases/latest) (it isn't signed with a
  231. Windows code-signing certificate yet, so SmartScreen warns; updates are signed and go in at
  232. *Restart to update*), or build from source. It builds, its tests pass and it runs on Windows 11 on
  233. Arm, but it hasn't had much use there. With Visual Studio's C++ build tools (and their clang, on Arm),
  234. Rust, Node, [Git for Windows](https://gitforwindows.org) and [Zig](https://ziglang.org) 0.17:
  235. ```powershell
  236. git clone https://github.com/codealong/codealong.git
  237. cd codealong
  238. npm install
  239. npm run tauri build -- --no-bundle # codealong.exe in ..\codealong-target\release
  240. ```
  241. Sessions open in [Windows Terminal](https://aka.ms/terminal), running their commands in Git Bash,
  242. as Claude Code does on Windows. Keys are as on Linux. Codealong's own terminals aren't there yet,
  243. nor typing into a session's terminal, finding its tab or bringing it forward, besides what Linux
  244. goes without; [the development notes](docs/development.md#windows) say what else differs.
  245. **You'll need:**
  246. - macOS 13 or later, Linux under X11, or Windows 10 (version 2004) or later (early build),
  247. where sessions open in Windows Terminal
  248. - At least one coding agent: [Claude Code](https://code.claude.com/docs), the
  249. [Codex](https://openai.com/codex/) CLI or app, [OpenCode](https://opencode.ai),
  250. [Antigravity](https://antigravity.google) or [Cursor](https://cursor.com)
  251. - A terminal: on macOS, [Ghostty](https://ghostty.org) 1.3 or later (the best supported), iTerm2,
  252. Terminal or [Rex](https://www.superlogical.com/rex) (in beta), and
  253. [tmux](https://github.com/tmux/tmux) (`brew install tmux`) to start sessions while the screen is
  254. locked; on Linux, tmux and a terminal emulator
  255. - For pull requests, the [GitHub CLI](https://cli.github.com) signed in: `gh auth login`
  256. ### Your first five minutes
  257. 1. **Open Codealong.** It finds your agents' accounts by the files they keep: Claude Code's
  258. `~/.claude` and any sibling folders like `~/.claude-work`, Codex's `~/.codex`, OpenCode,
  259. Antigravity and Cursor, including accounts your shell's aliases point at. It looks for git
  260. repos in the folders your agents worked in, and makes a project for each GitHub owner your
  261. recent sessions worked in. Your sessions show up straight away, wherever you started them.
  262. 2. **Go through Set up Codealong**, which opens over the window the first time: tick the
  263. accounts to show, the folders your code lives in, and your terminal and editor, and, if you
  264. like, give each session an emblem beside its title, an emoji a decision model picks or a small picture a
  265. Codex account draws, so the ones side by side read apart. Its last step
  266. installs the agent tools: the `codealong` command on your PATH, Codealong's plugin in each
  267. Claude Code account (so you can answer its permission prompts and questions from Codealong),
  268. and a skill in every other agent that tells it how to use the board. On macOS, the app menu's
  269. Set up Codealong… opens it again, and Settings (⌘,) changes any of it. Group your repos into
  270. projects under Settings › Projects.
  271. 3. **On macOS, say yes when it asks.** The first time Codealong opens or focuses a terminal tab,
  272. macOS asks whether it may control Ghostty, iTerm2 or Terminal. Allow it, so Codealong can bring
  273. the right tab forward and type your replies into it.
  274. 4. **Keep working the way you do.** Start agents in your terminal or their apps as usual. When
  275. you want something done, press **⌥⌘/** from any app. When agents are waiting on you, press
  276. **⌥⌘.** to work through them.
  277. ## A tour
  278. ### The board
  279. <p align="center">
  280. <picture>
  281. <source media="(prefers-color-scheme: dark)" srcset="docs/images/worktrees-dark.webp" />
  282. <img src="docs/images/worktrees-light.webp" alt="Sessions grouped by worktree: each worktree with its repo and how far it is from main, the agents working in it beneath, the ones on a Mac Studio marked, and the most urgent first." width="100%" />
  283. </picture>
  284. </p>
  285. Five views of your work, each in a window of its own if you like (⇧⌘N):
  286. | View | What it shows |
  287. | --- | --- |
  288. | **Sessions** | Every agent session in one list, the ones that need you first, or grouped under each worktree (its branch, its PR, how far it is from main) or each repo, with collapsible sections. Pin the ones you're watching. |
  289. | **PRs** | Every pull request in your repos, with its review, checks and the sessions that worked on it. Tabs for all of them, yours and others', what needs you first in each: Review requested, Ready to merge, Needs work, plus Fixing and Working for PRs an agent is at work on. Group them by worktree or repo too. |
  290. | **Todo** | Work you mean to hand an agent, with notes, screenshots, labels and what each todo waits on, grouped by worktree or repo if you like. |
  291. | **Schedules** | Sessions started, or messages sent, at the times you set or when something happens, with every run and how it went. |
  292. | **Board** (experimental) | Your work on boards you make, for the whole project or for a release or a fix: as **Kanban**, todos and sessions as cards in To do, In progress, In review and Done (or columns of your own), what needs you first in each; as **Canvas**, laid out in space, a frame per repo, a column per worktree, cards you arrange. |
  293. Select anything to see it in the panel on the right; right-click anything for its menu. The
  294. sidebar, a rail of the views until you open it, narrows every view to the machines, time span,
  295. statuses, agents, repos and labels you pick, and saved views bring a setup back. Plan usage for
  296. every account runs along the window's foot.
  297. Every session and worktree has a status:
  298. | Status | What it means |
  299. | --- | --- |
  300. | **Needs you** | The agent asked you something, wants to run something or hit an error, or a Claude Code session has said it's busy for 30 minutes with nothing new (stuck). |
  301. | **Your turn** | It finished a turn you haven't looked at yet. |
  302. | **Working** | It's mid-turn, or a command it left running is still doing something. |
  303. | **In review** | The worktree's pull request is open. |
  304. | **Merged** | The worktree's pull request was merged or closed. |
  305. | **Idle** | Nothing new. A session whose agent has quit is *Stopped*, its conversation kept to resume. |
  306. The Codealong mark shows the most urgent of them all at a glance: red for an error, amber when
  307. you're needed (a review request too), blue for finished work you haven't seen, green while agents
  308. work, and gray when all is quiet.
  309. Along the window's foot, each account's plan limits. Click one for the Analytics window: what your sessions
  310. used and what that would have cost at API prices, against what your plans and any extra usage
  311. actually cost, day by day and by account, model, project and session. An account whose provider
  312. may train its models on what you send (Help improve Claude, ChatGPT's Improve the model for
  313. everyone, Cursor's Share Data, Antigravity's telemetry) has its chip in amber, and its card on hover
  314. turns that off.
  315. ### Answer agents without switching apps
  316. When an agent wants to run a command, Codealong shows the call with **Allow**, **Always** and
  317. **Deny**. When it asks you a question, you get its choices to pick from and a box for your own
  318. answer. You can deny a call and say what to do instead in the same keystroke. The agent's own
  319. prompt stays up too, and whichever you answer first counts.
  320. You can answer from wherever suits you:
  321. - **The notch.** The bar starts docked in your MacBook's notch (an external display gets one
  322. drawn for it; drag the notch there to keep it on that display). Closed, it counts everything
  323. that waits on you, marked as the most urgent of it; click it and it opens on the agent that has
  324. waited longest.
  325. - **The floating bar.** Or float the bar, over every app, on every Space, even over full-screen
  326. apps, with pills for the agents that need you, have just finished or are working, PRs waiting on
  327. your review, your PRs ready to merge, and todos due or ready to start. Hover a pill to read the
  328. conversation and reply. It never takes your keyboard until you click.
  329. - **The menu bar.** Or keep the bar as an icon in the menu bar, with the count of agents that need
  330. you beside it and a menu that lists them, says whether Codealong's server is running, restarts
  331. it, and quits the app with the server or without it.
  332. - **Waiting on you** (⌥⌘. from any app) lists every agent that needs you, the PRs waiting on your
  333. review and yours ready to merge, unassigned todos that are due, and finished turns, oldest first,
  334. in the order Settings › Queue sets. Answer one and the next slides in: inbox zero, for agents.
  335. - **Pinned to your desktop.** Keep a session floating over your other windows, or pin a session,
  336. worktree, todo or PR there as a small card.
  337. A short sound tells you when an agent starts to need you or finishes its turn, so you hear it from
  338. another app: not for the session you just answered, and one at most every few seconds. Pick the
  339. sounds, or turn them off, in Settings › Sounds.
  340. <p align="center">
  341. <picture>
  342. <source media="(prefers-color-scheme: dark)" srcset="docs/images/bar-dark.webp" />
  343. <img src="docs/images/bar-light.webp" alt="The floating bar: pills for the three sessions that need you, finished work, running agents, a PR to review and three todos ready to start." width="720" />
  344. </picture>
  345. </p>
  346. The keys are the same everywhere: **⌘⏎** sends your reply (or allows the call) and moves on to the
  347. next agent waiting, **⌘⌫** denies, **⌘E** marks a finished turn seen, **⌘]** skips, and
  348. **⌃⌘1** to **⌃⌘7** snooze a session for 15 minutes, half an hour, an hour, three hours, until 5 PM,
  349. until tomorrow morning or until next week, and its Snooze menu's Pick a time… for any other.
  350. Where a session's reply says its work goes on later, or its usage limit stopped it, **⌃⌘8**
  351. snoozes it until then.
  352. Approvals and questions can be answered for Claude Code (in a terminal, as a background job or in
  353. the Claude app), OpenCode, Antigravity's command line in a terminal that takes keypresses, and any
  354. agent you run inside Codealong; approvals for Codex's command line too, in a terminal that takes
  355. keypresses, and for Cursor's in Rex, tmux or Codealong's own terminal, where its prompt can be
  356. read. The Codex, Cursor and Antigravity apps show what they're waiting on, and open where they ask.
  357. <p align="center">
  358. <picture>
  359. <source media="(prefers-color-scheme: dark)" srcset="docs/images/waiting-dark.webp" />
  360. <img src="docs/images/waiting-light.webp" alt="The Waiting on you window: Claude Code asks whether to keep rate-limit counters in Redis or in-process, each choice with what it means, and a box for an answer of your own." width="640" />
  361. </picture>
  362. </p>
  363. ### Pull requests, with their agents
  364. Every pull request in your repos is joined to the worktree and sessions behind it, including the
  365. agent that opened it, pushed to it or commented on it. Colored pills show its review, checks and
  366. conflicts, and rows that are your move are marked. Select one for its description, reviews,
  367. checks, comments and diffs.
  368. - **Review, approve and merge** without opening GitHub: merge commit, squash or rebase,
  369. auto-merge, the merge queue, updating the branch. A merge shows everywhere as you confirm it,
  370. and comes back with why if GitHub refuses it.
  371. - **Snooze** a review request until later.
  372. - **Nudge a PR's agent**: its primary session (the one that pushed to it most, usually the one that
  373. opened it, or one you pick) is told when someone reviews, asks for changes or comments, or when
  374. checks fail, so it takes it from there; it's never told to merge. A session whose next step
  375. hangs on a PR can watch it (`codealong pr watch`), and is told of its approval, merge or close
  376. too, resumed for it if it has stopped.
  377. - **Ask about a PR**: put questions to an agent that has read its whole diff.
  378. - **Automatic reviews** (optional): an agent on the account, model and effort you pick reviews each PR
  379. that asks for your review, told what to look for by instructions you can edit (which can have it
  380. start subagents of its own), and leaves a draft review on your account with its comments on the
  381. lines they're about, for you to finish and submit. The agent says whether it would approve or ask
  382. for changes, which the PR's box suggests, and it can approve for you when it finds nothing that
  383. needs fixing. The PR waits on you only once it's done, and new commits get reviewed again.
  384. - **A second opinion on your agents' PRs** (optional): each PR a session of yours opens is
  385. reviewed by an agent on another model or provider (Codex reviews what Claude Code wrote, say),
  386. kept in Codealong and handed back to its primary session to act on. Nothing goes on
  387. GitHub.
  388. - **Settings per repo, and shared with your team**: pick a repo in Settings › Automation to set how
  389. its PRs are reviewed and nudged. A `.codealong/config.toml` committed to the repo shares words
  390. for every review, which verdicts an agent may never submit, and what to suggest turning on, with
  391. everyone on the team; each person takes the suggestions or doesn't.
  392. ### The quick panel: say what you want done
  393. Press **⌥⌘/** in any app. With nothing typed, it lists what needs you. Start typing and it finds
  394. sessions (by title, branch or PR, or by what was said in them), todos and pull requests. Or keep
  395. typing a prompt and start it, choosing:
  396. - **the repo** (⌘T), which starts where new work goes in it, and **the worktree** in it (⌘B): a
  397. new one, one ready for new work, the main checkout, or one with work under way;
  398. - **the account, model and effort** (⌘L), or leave it on *Auto*;
  399. - **where it runs** (⌘O, in the same menu): a terminal tab, in the background, the Claude or Codex
  400. app, or inside Codealong itself. Each account starts where Settings › Accounts says unless you
  401. pick another for that start; *Make default* there changes it;
  402. - and, with other machines linked, **which machine** (⌘D).
  403. *Auto* picks the account with room (or from your routing group in Settings › Routing): an
  404. account at its usage cap (90% by default) has none, and among those with room it picks the one
  405. whose week resets soonest, so no week's allowance goes unused, until it's within 5% of its cap
  406. (`[routing] buffer`) and what's left is for the sessions already on it. A
  407. question that isn't about any of your repos can go to a chat of its own. Type `/` to find your
  408. repos' skills by name.
  409. **Improve Codealong.** The button beside *New session*, or **⌥⌘,** in any app, opens the panel on
  410. Codealong's own source with a picture of every Codealong window as it is: describe what to change,
  411. and the session improves Codealong itself. With Codealong's source in none of your projects, the
  412. panel offers to add one. In the installed app, it first offers to have an agent switch you to
  413. Codealong Dev, a build of the source that runs what you change.
  414. **Optional suggestions.** Turn on a decision model (Settings › Decisions, with your own API key for
  415. [TypeSafe](https://typesafe.ai)'s Jev, OpenAI's or Google's, chosen per project) and the panel
  416. suggests where your prompt belongs: the agent already working on it, a free
  417. worktree, a new chat, or a todo for later, each with how likely it is. It warns you when a running
  418. agent may already be doing the same work, so two agents don't quietly race each other. Everything
  419. else works without it.
  420. ### Every conversation, readable and answerable
  421. Select a session to read its whole conversation, straight from the agent's own records: your
  422. prompts, the replies as formatted text, and every tool call, which opens to show what went in and
  423. what came out (click a file a tool call read or changed to open it). Images you sent and files an
  424. agent sent you (images, videos, audio) show in place, links to pull requests show their status, and
  425. ⌘F finds words anywhere in the window, the whole conversation among it.
  426. The box at the bottom replies the way that agent takes a prompt: typed into its terminal tab, sent
  427. through Claude Code's background service, started as a new turn in the Codex app, or through
  428. OpenCode's service. Paste screenshots or files into it. From there you can also:
  429. - **stop** a turn (Esc or ⌘.), or **send now** to slip a message into the running turn (⌃⏎);
  430. - **switch a session's model or effort** without starting over (a running Claude Code session, a
  431. Codex app thread, or any session run in Codealong);
  432. - **ask on the side**: `/side <question>` asks a throwaway copy of a Claude Code, Codex or Antigravity session,
  433. which never hears of it;
  434. - **fork** a session into a copy that carries on alongside (`/fork`), or **rewind** to an earlier
  435. question in a copy;
  436. - **copy** any code block, or **run** a shell block in a new terminal where the session works;
  437. - **rename, label, pin, snooze, quiet, archive** or **mark as done** (which closes its terminal and
  438. archives it), or **move** a Claude Code session to another account or worktree;
  439. - **pop it out** of the main window into a window of its own, to keep it in view as you work.
  440. Out of room mid-task? A Claude Code session stopped by its usage limit offers to move to an
  441. account with room and carry on, or moves by itself if you let it. Lid closed and the network
  442. dropped? Codealong tells the session to carry on once the connection is back. Terminal quit
  443. partway through a turn? The session says it was cut off, and Carry on picks it up; one running in
  444. Codealong itself is told to carry on as Codealong comes back from a restart.
  445. ### Todos your agents can work
  446. <p align="center">
  447. <picture>
  448. <source media="(prefers-color-scheme: dark)" srcset="docs/images/todo-dark.webp" />
  449. <img src="docs/images/todo-light.webp" alt="The Todo view: todos in progress with the sessions working on them, todos ready to start and ones waiting on others. The one picked shows its description, labels, what waits on it, and its worktree and sessions." width="100%" />
  450. </picture>
  451. </p>
  452. A todo list for work you mean to hand an agent, with notes, screenshots and files, labels, and the
  453. todos each one waits on. Start a session from a todo (⌘N) and the two stay linked: the todo moves
  454. to *In progress*, and the first session on it owns it, so a second agent started on the same todo
  455. is told to send its findings to the first instead of redoing the work. Agents can read and update
  456. the list themselves with the `codealong` command.
  457. ### Schedules
  458. <p align="center">
  459. <picture>
  460. <source media="(prefers-color-scheme: dark)" srcset="docs/images/schedules-dark.webp" />
  461. <img src="docs/images/schedules-light.webp" alt="The Schedules view: a morning CI triage, a check after each deploy, a changelog line when a PR merges and more. The one picked runs when a deploy script prints something new, with its last look and every run." width="100%" />
  462. </picture>
  463. </p>
  464. Work that comes round by itself: a session started, or a message sent to one you keep going, at
  465. times you write in a few words (`weekdays 9:00`, `every 2h`, `monthly 1 9:00`), when a command it
  466. runs every few minutes prints something new (a deploy, a failing build, a new message), when a PR
  467. merges or its checks fail or a todo is ready, or when a script fires it (`codealong schedule
  468. fire`). Each run goes on the account, routing group or Auto you pick, picked again each time, and
  469. what it was for goes to the agent as a file to read, not as words of yours. The Schedules view
  470. (⇧⌘L) lists them with every run and how it went; a run missed while the Mac slept goes once it's
  471. back.
  472. ### Open anything where it lives
  473. Double-click a session to bring forward its exact terminal tab in Ghostty, iTerm2, Terminal or Rex,
  474. its Claude app session or its Codex thread, or to resume it in a new terminal. Open a worktree in
  475. your editor: VS Code, Cursor, Windsurf, Kiro, Zed, Sublime Text, Nova, BBEdit, Xcode, the JetBrains
  476. IDEs or Android Studio. ⌃` opens a terminal in the folder of whatever you're looking at. A worktree
  477. whose dev server is running shows a green globe: click it to open the app, in the Chrome profile
  478. you choose.
  479. ### All your machines on one board
  480. Turn on Settings › Devices on each machine and link them once: on your
  481. [Tailscale](https://tailscale.com) network both show the same six digits and you say yes; anywhere
  482. else, you enter a link code. Each machine then shows the others' worktrees and sessions beside its
  483. own, with a badge saying which machine each one is on. Read any conversation from any machine. Turn
  484. on remote control at a machine, and your other machines can send its sessions messages, answer their
  485. approvals and start work there. Machines talk to each other encrypted end to end, through Tailscale
  486. or [iroh](https://iroh.computer): directly where they can, otherwise through iroh's public relays,
  487. which pass along packets they can't read. There's no Codealong server in between.
  488. **On your iPhone**, [Codealong for iPhone](https://github.com/codealong/codealong-ios) links with
  489. your machines the same way and lists every session, most urgent first, to read, and where a machine
  490. has remote control on, to reply to, approve and start. It's early, and for now you build and install
  491. it yourself: Get the iPhone app, in Settings › Devices, starts an agent that does it with you.
  492. ### A board your agents can read too
  493. The `codealong` command (installed from Settings › Agents) and its skill let your agents see what
  494. other agents are doing in the same repo, pick up and finish todos, check which account has room,
  495. message another session, or start one. It answers in JSON when an agent runs it, and in tables
  496. in your terminal.
  497. ```bash
  498. codealong whoami # which session am I, who else works here, my todos
  499. codealong sessions find "rate limits"
  500. codealong todo list --ready
  501. codealong accounts --usage
  502. codealong start --todo <id>
  503. ```
  504. `codealong --help` lists everything, and so does
  505. [the skill's reference](skills/codealong/references/reference.md).
  506. An agent can also keep watch over your sessions for you: the compass on Sessions' bar, or
  507. `codealong orchestrator start [project]`, starts an orchestrator for a project or for all of them.
  508. Codealong wakes it only when something needs a look, at most every 15 minutes; it tags what waits on
  509. you, suggests replies and flags agents getting in each other's way, without messaging any of them,
  510. and speaks only for what you don't see already ([its skill](skills/codealong/references/orchestrate.md)).
  511. And a session you hand a bigger piece of work can coordinate it (`/codealong:coordinate`): it
  512. splits the work across helper sessions, each in a worktree of its own, that report back to it, and
  513. brings you what they come to ([its skill](skills/codealong/references/coordinate.md)).
  514. ### Boards and the canvas
  515. <p align="center">
  516. <picture>
  517. <source media="(prefers-color-scheme: dark)" srcset="docs/images/canvas-dark.webp" />
  518. <img src="docs/images/canvas-light.webp" alt="A project's board as a canvas: a frame per repo and a column per worktree, with its session, todo and PR cards, and the project's todos that aren't in a worktree yet beside them." width="100%" />
  519. </picture>
  520. </p>
  521. Your project laid out in space, to remember work by where it is. *Tidy* lays it out in a frame per
  522. repo and a column per worktree, and new work comes in by itself beside what it belongs to. Add
  523. notes and frames, pan and zoom as in Figma, and zoomed out, every card becomes a block in its
  524. status color. The canvas and the Kanban are two ways of showing a board you make, for the whole
  525. project or for a release, a fix or an investigation, holding what its rule takes in (a label, a
  526. stage, a repo, what needs you) and what you add from any row's menu. A board's Kanban can have
  527. columns of your own, and agents can put their work on a board with `codealong board add`. Boards
  528. are an experiment, off until you turn them on in Settings › Experimental.
  529. ### Voice and meetings
  530. Voice is an experiment too (macOS 26, Settings › Experimental). Hold ⌥⌘[ and talk, and what you
  531. said is typed where your caret is in Codealong, or from another app into the quick panel, which
  532. opens to hear it; hold ⌥⌘] to talk to your orchestrator from any app. And a session can listen to a meeting: it keeps notes, coaches you a few words at a time
  533. beside your camera, or files a todo for each thing a customer asks for. Press ⌥⌘= as one begins
  534. (Listen now) and Codealong hears it from then on, with a session started for it; or have a
  535. session you already have listen (Listen… in its menu). Let it read your calendar and it counts
  536. down to each meeting and offers to take its notes as it starts, keeping each meeting's transcript
  537. and notes in a folder of its own for any session to work from afterwards. Speech becomes text on
  538. your Mac, with macOS's own model, and no audio is kept ([the guide](docs/guide.md#voice) has the
  539. rest).
  540. ## What works with each agent
  541. **Agents:** Claude Code (in a terminal, as background jobs and in the Claude app), Codex (the CLI
  542. and the app), OpenCode, Antigravity and Cursor (new). The table below says what Codealong can do with every
  543. one.
  544. **Systems:** macOS 13 or later, on Apple silicon or Intel. Linux too, under X11 (`.AppImage`,
  545. `.deb` and `.rpm` on the releases page, or [built from source](#on-linux)): sessions run in tmux,
  546. shown in your terminal emulator, and a few things are macOS's alone, the notch and the Claude and
  547. Codex apps among them ([what differs](docs/development.md#linux)). Windows is an early build
  548. (unsigned setup `.exe` on the releases page, or [built from source](#on-windows)): sessions open in
  549. Windows Terminal, and Codealong's own terminals aren't there yet.
  550. Codealong reads what every agent already writes, so it sees all of them. What it can do from
  551. there depends on what each one lets another program do. **Where it can't act, it opens the
  552. session where it lives.**
  553. | Agent | Sees it | Sends prompts | Answers approvals | Starts sessions | Several accounts | Usage limits |
  554. | --- | :-: | --- | --- | --- | :-: | --- |
  555. | **Claude Code** in a terminal | ✓ | Types into its tab | ✓ | ✓ | ✓ | Weekly, per model |
  556. | **Claude Code** background jobs | ✓ | Its background service | ✓ | ✓ | ✓ | Weekly, per model |
  557. | **Claude app** | ✓ | As a message from another session | ✓ (with the plugin) | Opens it with the prompt | Its signed-in account | Shared with Claude Code |
  558. | **Codex CLI** | ✓ | Types into its tab | In Ghostty, iTerm2, Rex and tmux (with the skill's hook) | ✓ | ✓ | 5-hour, weekly |
  559. | **Codex app** | ✓ | Starts a new turn | In the app | ✓ | Its signed-in account | 5-hour, weekly |
  560. | **OpenCode** | ✓ | Its own service | ✓ | ✓ | ✓ | You bring the provider |
  561. | **Antigravity** | ✓ | Types into `agy`'s tab; the app opens with the prompt on the clipboard | `agy` in a terminal; the app in the app | `agy` in a terminal; the app in its own window | — | Weekly, per model group (with `agy`) |
  562. | **Cursor** (new) | ✓ | `cursor-agent` in a terminal; app chats open with the prompt on the clipboard | `cursor-agent` in Rex, tmux and Codealong's terminal; app chats in Cursor | `cursor-agent` | — | Monthly, Cursor's models and the others |
  563. | **In Codealong** (Claude Code, Codex or OpenCode) | ✓ | ✓ | ✓ | ✓ | ✓ | Per account |
  564. Terminals: Ghostty (the exact tab, keypresses, new tabs beside their worktree), Rex (the same, with
  565. a Rex session for each project), iTerm2 and tmux (typing and keypresses), and Terminal (typing).
  566. Approvals for Claude Code go through Codealong's plugin, which Settings › Agents installs into each
  567. account, and Codex's through a hook it puts in each Codex account beside the skill. *In Codealong*
  568. means the agent runs in Codealong's own panel, over the
  569. [Agent Client Protocol](https://agentclientprotocol.com).
  570. ## Keyboard shortcuts
  571. From any app (change them in Settings › General):
  572. | Keys | What they do |
  573. | --- | --- |
  574. | ⌥⌘/ | The quick panel: find anything, start a session |
  575. | ⌥⌘' | The quick panel on General chat, to start a chat of its own in no project |
  576. | ⌥⌘. | Work through what waits on you, in the notch or the *Waiting on you* window |
  577. | ⌥⌘, | Improve Codealong: the quick panel on Codealong's own project, with pictures of its windows |
  578. | ⌥⌘; | Codealong's window, the one you were in last; pressed there, it hides Codealong |
  579. <details>
  580. <summary>Every key in Codealong's own windows</summary>
  581. | Keys | What they do |
  582. | --- | --- |
  583. | ⇧⌘S · ⇧⌘P · ⇧⌘T · ⇧⌘L · ⇧⌘K · ⇧⌘B | Sessions, PRs, Todo, Schedules, the board as Kanban, as Canvas (with boards turned on); from the notch, the quick panel or the waiting window, Codealong's window on that view |
  584. | ⌘P | Switch project (⌥⌘1 – ⌥⌘9 jump to one, ⌥⌘0 shows them all) |
  585. | ⌘K | The quick panel, in this window's project |
  586. | ⌘N / ⇧⌘N | New session / new window |
  587. | ⏎ | Open the selected session, worktree or PR where it lives |
  588. | ⌘1 – ⌘5 | Open the selected worktree in its terminal, editor, the Claude app, the Codex app or its preview |
  589. | ⌘O | Open the selected PR on GitHub |
  590. | ⇧⌘M | Merge the selected session's PR once it's ready, and mark the session done (it asks first) |
  591. | ⌃⌘↑ / ⌃⌘↓ | Move the selected pin, or todo, up or down |
  592. | ⌘⏎ | In the reply box: send your reply (or allow the call) and go on to the next agent waiting |
  593. | ⌘⌫ | Deny the call (with nothing typed in the box) |
  594. | ⌃⏎ | Send now, into the running turn |
  595. | ⌘1 – ⌘6 | Send a suggested reply, from the reply box (from anywhere in the notch and the waiting window) |
  596. | ⌘. (or Esc in the reply box) | Stop the turn |
  597. | ⌘E / ⇧⌘E | Mark seen / mark as done |
  598. | ⌘] / ⌘[ | Next / previous of what waits on you (in Sessions, the notch and the waiting window) |
  599. | ⌃⌘1 – ⌃⌘7 | Snooze: 15 minutes, 30 minutes, 1 hour, 3 hours, 5 PM, tomorrow morning, next week |
  600. | ⌃⌘8 | Snooze until the time offered: when its usage limit lifts, or when its reply says the work goes on |
  601. | ⌃⌘P · ⌃⌘A · ⌃⌘R · ⌃⌘U | Pin, archive, rename, mark as unread |
  602. | ⌃⌘0 | Move to top: first in every queue of what waits on you |
  603. | ⌃⌘W | Close the session's terminal (the conversation stays, to resume) |
  604. | ⌘F | Find in the window, as a browser does: the list, the panels, the whole conversation |
  605. | ⌘G / ⇧⌘G | Next / previous match (⏎ / ⇧⏎ in the find) |
  606. | ⌥⌘F | Filter where you are: a PR's files, else the view's list |
  607. | ⌃- / ⌃⇧- | Back / forward through the sessions you looked at |
  608. | ⌃` | A new terminal in the folder of what's shown |
  609. | ⌘C / ⌥⌘C | Copy the selected worktree's branch / path |
  610. | ⇧⌘F | Expand the session panel (in Sessions) or the PR panel (in PRs) to the whole window |
  611. | ⌃⌘S | Open or fold the sidebar |
  612. | ⌘= · ⌘- · ⌘0 | Zoom in, out, actual size |
  613. | ⌘R | Reload: read again what the window shows, from GitHub too, keeping your place |
  614. | ⇧⌘U | Analytics: what sessions used and cost, at API prices and paid |
  615. | ⌘, | Settings |
  616. </details>
  617. In the quick panel: **⏎** does the selected row, **⌘⏎** always starts a session, **⌥⏎** opens a
  618. session where it lives, **⇥** answers a session in the *Waiting on you* window, **⌘1** – **⌘9** pick
  619. a row, and **⌘P**, **⌘T**, **⌘B**, **⌘L**, **⌘O**, **⌘D** choose the project, repo, worktree,
  620. agent, place and machine. On a PR waiting on your review, in the notch or the waiting window, **⌘⏎** approves it,
  621. **⌥⌘⏎** comments, **⌃⌘R** has an agent review it and **⌃⌘G** opens it on GitHub. Right-click menus
  622. show every action's keys.
  623. On Linux, ⌘ is Ctrl, and ⌥ and ⌃ are Alt, but for a few keys that would clash there: ⌥⌘1 – ⌥⌘9
  624. are Alt and the digit, ⌃⏎ is Ctrl+Shift+Enter, ⌃\` is Ctrl+\`, and ⌃⌘↑ / ⌃⌘↓ are
  625. Ctrl+Shift+PageUp / PageDown. The menus and buttons show every key as Linux has it. ⇧⌘N and ⇧⌘U
  626. are the macOS menu bar's, which Linux doesn't have; the Analytics button at the foot of the sidebar opens Analytics there.
  627. ## Settings
  628. Everything is in Settings (⌘,), as a form and as the text of
  629. `~/Library/Application Support/Codealong/config.toml` (on Linux, `~/.config/codealong/config.toml`).
  630. Codealong writes that file on first run from what it finds on your machine, and watches it, so you
  631. can edit either. The form saves each change in its place, keeping your comments and order, and
  632. `codealong config check` checks a file you edited by hand.
  633. A repo can share settings with everyone who works on it in `.codealong/config.toml`, read from the
  634. branch its pull requests merge into (so a change goes for the team once it's merged), and
  635. `codealong config check --repo <folder>` checks one before you push it:
  636. ```toml
  637. [reviews]
  638. instructions_file = "review.md" # .codealong/review.md, added after each person's own instructions; or `instructions = "…"`
  639. never_submit = ["approve"] # verdicts never submitted as anyone's review, whatever their `submit` says
  640. auto = true # suggested: each person takes it in Settings or a PR's Reviews tab, or doesn't
  641. post = "comment" # suggested
  642. [reviews.own]
  643. instructions = "Check the tests cover what changed."
  644. auto = true # suggested
  645. send = true # suggested
  646. [pull_requests]
  647. nudge_about = "feedback-and-checks" # for everyone
  648. reviews_first = true # for everyone: PRs waiting on your review come first, before everything else
  649. nudge_by_default = true # suggested
  650. rerequest_after_fixes = true # suggested
  651. ```
  652. Accounts, models, a person's own prompt and what's submitted as them stay each person's: a file
  653. that sets one goes unused, with a notice saying why.
  654. <details>
  655. <summary>An annotated <code>config.toml</code></summary>
  656. ```toml
  657. scan = ["~/projects"] # where repos are found, three levels deep
  658. [apps]
  659. terminal = "ghostty" # or "iterm2", "terminal", "rex", or "codealong": sessions start in a terminal of Codealong's own, in their panel
  660. editor = "cursor" # or "vscode", "zed", "xcode"… (Settings lists those installed), or an app's name
  661. new_terminal = "project" # a tab beside the same worktree, repo or project (in Rex, the project's own session); or "tab", "window"
  662. move_pointer = false # move the pointer to a terminal brought forward on another screen
  663. close_command_tabs_after = 10 # minutes after a command Codealong runs in your terminal ends that its tab closes; 0 keeps it (Settings › General)
  664. tmux = "when-locked" # sessions Codealong starts run in tmux, shown in your terminal: "always"; "when-locked", only while the screen is locked, when Ghostty can't start one; "never" (Settings › General). Either but never, Background starts of agents with no background service run in tmux with no window
  665. run_in = "codealong" # a session's new terminals (⌃`) and the commands you run from it open in a terminal of Codealong's own under the session; "terminal" opens them in your terminal app
  666. [appearance]
  667. theme = "system" # follows the system; or "light", "dark"
  668. zoom = 100 # the windows and the cards in the notch and peek, in percent, 50 to 200 (⌘= ⌘- ⌘0)
  669. glass = true # the main window and the project windows show what's behind them through macOS's glass (on by default; macOS only)
  670. show_keys = true # keyboard shortcuts beside what they do (on by default); false shows them only while you hold ⌘ or ⌃
  671. [shortcuts] # macOS's defaults; on Linux they're Ctrl+Alt+/ and so on
  672. quick_panel = "Option+Cmd+/" # works in every app; "" turns it off (Settings › General)
  673. chat = "Option+Cmd+'" # the quick panel on General chat, to start a chat in no project
  674. waiting = "Option+Cmd+." # the first session that waits on you: the notch, or the waiting window
  675. improve = "Option+Cmd+," # the quick panel to improve Codealong itself, with pictures of its windows
  676. main_window = "Option+Cmd+;" # Codealong's window you were in last; pressed there, hides Codealong
  677. talk = "Option+Cmd+[" # with voice on: held while you talk to the session you're looking at (Settings › Experimental)
  678. talk_orchestrator = "Option+Cmd+]" # with voice on: held while you talk to your orchestrator
  679. listen = "Option+Cmd+=" # with voice on: opens the quick panel set to listen to a meeting from then on (Listen now)
  680. [decisions] # decision models, each feature off until turned on (Settings › Decisions); an old [jev] reads as this
  681. default = "jev" # the model a project that names none goes to; "none" for none. jev is TypeSafe's Jev, always there
  682. quick_panel = false # suggestions as you type in the quick panel
  683. sessions = false # how each turn ended: asks you, stuck, landed, finished, risk
  684. todos = false # links sessions to todos, done hints, new todos' labels
  685. pull_requests = false # review comments that ask for a change
  686. prompts = false # with [experimental] analytics: what each prompt you typed did with the reply before it
  687. [[decisions.models]] # a model of your own naming; each provider's key is in the keychain (Settings › Decisions)
  688. name = "luna"
  689. provider = "openai" # "typesafe" (jev-preview, jev-latest, jev-1.14.0), "openai" (gpt-6-luna) or "gemini" (gemini-decision-1)
  690. model = "gpt-6-luna"
  691. fallback = "jev" # asked when this one fails for now (429, overloaded, unreachable), for what goes by the default only
  692. [emblems] # something to know each session by beside its title (Settings › Appearance)
  693. kind = "off" # "emoji" (a decision model picks one) or "drawn" (an account draws one)
  694. account = "codex" # drawn: the account that draws them; the first that can when unset
  695. prompt = "Pixel art on a 16 by 16 grid, with a dark outline." # drawn: how; Codealong's own when unset
  696. [search]
  697. days = 14 # prompts and replies searched this far back; 0 is titles only (Settings › General)
  698. [devices] # your other devices (Settings › Devices)
  699. enabled = false
  700. name = "" # this machine's name on your other devices; "" is the computer's name
  701. tailscale = true # find them on your tailnet
  702. port = 47471 # the TCP port Codealong listens on there, on this machine's tailnet address only (1024 and up)
  703. iroh = true # reach linked devices anywhere
  704. remote_control = false # let linked devices act on sessions here
  705. in_bar = true # their sessions show in the bar, the notch and Waiting on you too, while they're connected
  706. automations = "first" # what your machines share (a review of a PR, a schedule that runs on one of them) runs on one; "backup" runs it only when no first choice can
  707. [limits]
  708. when_hit = "suggest" # a session stopped at its usage limit offers a move; "move" moves it (Settings › Automation)
  709. continue_when_lifted = true # tell a session still stopped at its limit to carry on once it lifts (Settings › Automation)
  710. [sessions]
  711. block_flagged_sessions = true # block automatic messages, resumes and account moves after a recorded provider flag (Settings › Automation)
  712. continue_after_network_error = true # tell a session a lost connection stopped to carry on once it's back (Settings › Automation)
  713. continue_after_sign_in = true # tell a session its account's sign-in stopped to carry on once the account is signed in again (Settings › Automation)
  714. continue_after_restart = true # tell a session Codealong runs to carry on when Codealong quitting cut off its turn (Settings › Automation)
  715. resume_for_sessions_it_started = true # resume a session that isn't running, out of sight, when one it started, or the one that started it, sends it a message (Settings › Automation)
  716. resume_for_any_session = true # the same for any session's message, telling it it had stopped; the line above is part of it while it's on (Settings › Automation)
  717. resume_for_pr_news = true # resume a PR's primary session that isn't running, out of sight, when its nudge has news that asks for work, or any news of a PR it watches, unless another of the PR's sessions runs (Settings › Automation)
  718. live_replies = false # Claude Code sessions hand Codealong a reply as their terminal shows it, so Codealong shows it as it's written; their terminals then show a reply a paragraph at a time; new sessions only (Settings › Agents)
  719. hibernate_after = 0 # minutes a session in a terminal, or a Claude Code background job, sits idle, wanting nothing from you, before its tab closes or its job stops to free what its agent holds; opening it or replying resumes it; 0 is off (Settings › Automation)
  720. [routing] # Settings › Routing
  721. auto = "" # the routing group Auto uses for new sessions and reviews, where a project's `default` names none; "" picks among accounts of the first harness with room
  722. prompt = "" # instructions for the decision model in the quick panel to suggest an agent, model or routing group for what you type
  723. buffer = 5 # percent below each account's usage_cap left for the sessions already running there: Auto stops favoring its soonest reset, and a fallback group moves on, once it's this close (0 to 50)
  724. [[routing.groups]]
  725. name = "reviewers" # offered in the quick panel, `codealong start --account`, and as the reviewer for PRs
  726. strategy = "alternate-harness" # "usage" (most room / soonest reset), "alternate-harness" (rotates across harnesses), "round-robin", or "fallback" (the members in order, each until it's within `buffer` of its cap)
  727. members = [{ account = "claude-work", model = "opus", effort = "high" }, { account = "codex" }] # each an account on a model (none: Auto's) at an effort (none: the account's own), added in order; [] includes every enabled account that can start
  728. [[routing.groups]]
  729. name = "authorized"
  730. boundary = true # a boundary: only members whose provider says they're on a commercial plan count as in it, and what its members' sessions say stays with sessions in it (`codealong account check --group authorized` for a repo's guard hook)
  731. decisions = "jev" # with boundary: the one decision model that may read its sessions, or "none"; without it, Jev, whatever [decisions] default says
  732. members = [{ account = "claude-work" }] # a boundary lists its members, each in one boundary at most
  733. [reviews]
  734. auto = false # an agent reviews each PR that waits on your review, and again on new commits (Settings › Automation)
  735. account = "" # the account or routing group it runs on; "" for the one Auto would start
  736. model = "" # the model it starts on; "" for the account's or group member's own
  737. effort = "" # the effort it starts at, with an account named; "" for the account's or group member's own
  738. other_harness = true # prefer a harness other than the PR author's (from its session here or Co-Authored-By / Generated with trailers)
  739. drafts = true # review a draft that asks for your review too; being assigned to one doesn't ask
  740. prompt = "" # what it's told to do (what to look for, subagents to start); "" for Codealong's own
  741. start = "no-terminal" # where its session runs, yours too: "no-terminal" (Claude Code's background service, else Codealong); "codealong"; "background" (tmux with no window where the account has neither); "terminal" (in front, as new_terminal says)
  742. post = "draft" # "draft": a draft review of yours to finish; "comment": a comment; "none": stays in the session
  743. submit = "never" # submit the agent's verdict as your review once posted: "approve", "approve-or-request-changes", "approve-or-comment"; "request-changes" or "comment" never approve
  744. [reviews.own]
  745. auto = false # an agent reviews each PR a session of yours opened here, and again on new commits (Settings › Automation)
  746. account = "" # the account or routing group it runs on; "" for Auto's
  747. model = "" # the model it starts on; "" for the account's or group member's own
  748. effort = "" # the effort it starts at, with an account named; "" for the account's or group member's own
  749. other_harness = true # prefer a harness other than the PR's session or trailers
  750. prompt = "" # what it's told to do; "" for Codealong's own
  751. send = true # hand each review to the PR's primary session; nothing goes on GitHub
  752. drafts = false # review your draft PRs too; others' go by [reviews] drafts
  753. [pull_requests]
  754. nudge_by_default = false # every open PR of yours tells its primary session what happens on it (Settings › Automation)
  755. nudge_about = "everything" # what a nudge tells of: "feedback" only comments and changes asked for; "feedback-and-checks" adds failing checks and conflicts; "feedback-and-merges" and "feedback-checks-and-merges" add a merge to those
  756. rerequest_after_fixes = false # ask a reviewer who asked for changes to look again, as you, once fixes are pushed and nobody said so (Settings › Automation)
  757. reviews_first = false # PRs waiting on your review come before everything else in the notch, the waiting window and the quick panel
  758. [queue] # what waits on you, in the order the notch, the waiting window and the main window's panels go through it (Settings › Queue)
  759. order = ["needs", "reviews", "merges", "due", "unread", "ready"] # sessions that need you, PRs waiting on your review, yours ready to merge, unassigned todos due, sessions whose turn ended, unassigned todos ready to start (always last); one left out doesn't wait on you, but the sessions' two always do
  760. due_within = 0 # how many days before its due date an unassigned todo comes due: 0 on the day
  761. [sounds] # a short sound when something starts to wait on you (Settings › Sounds)
  762. needs_you = "Pop" # a session asks you something, waits on a call to allow, or stops with an error (on Linux, "message-new-instant")
  763. your_turn = "Tink" # a session's turn ended (on Linux, "complete")
  764. review_requested = "" # a PR asks for your review; "" is no sound
  765. meeting = "Glass" # a meeting in your calendar is about to start, with [voice] meetings on
  766. volume = 60 # in percent of the system's own; any sound in /System/Library/Sounds or ~/Library/Sounds, or on Linux the freedesktop sound theme's or ~/.local/share/sounds
  767. [repos."github.com/acme/web".reviews] # yours for one repo, over the above and its team's file (Settings › Automation, the repo picked)
  768. account = "claude-work" # any of [reviews] but start, [reviews.own] (as reviews.own) and [pull_requests]; what's left out is as they say
  769. post = "none"
  770. [updates]
  771. check = true # look for a new version by itself (Settings › General); Codealong Dev looks at origin/main
  772. [experimental] # features still being tried out, each off until it's turned on (Settings › Experimental)
  773. boards = false # the Board view, as Kanban and as Canvas, Add to board in the menus, and `codealong board`
  774. voice = false # the keys held to talk, sessions that listen to a meeting (Listen… in a session's menu), and `codealong listen`
  775. analytics = false # who began each session and turn, what your prompts did, how the sessions you marked done stood (the Analytics window, `codealong analytics`)
  776. [voice] # once [experimental] voice is on (Settings › Experimental)
  777. locale = "" # the language spoken, such as "en-US"; "" for this Mac's own
  778. send_on_release = false # what you say to your orchestrator is sent as you let go of the key, not put in its box first
  779. tell_every = 20 # how often, in seconds, a session that listens is told what's new, at most (5 at the least)
  780. meetings = false # as a meeting in your calendar is about to start, offer to take its notes; macOS asks once for your calendar
  781. meetings_folder = "" # where your meetings are kept, a folder each (transcript.md, notes.md, meeting.json); "" for meetings beside this file
  782. meeting_account = "" # the account a meeting's session starts on: an account, a routing group, or "" for Auto
  783. meeting_model = "" # and its model; "" for the account's own
  784. meeting_lead = 1 # how many minutes before a meeting starts it's offered (0 for as it starts, 30 at the most)
  785. meeting_countdown = 5 # from how many minutes before it starts the notch, the floating bar and the Meetings button count down to it, quietly, until it's offered (0 for none, 60 at the most)
  786. meeting_calendars_off = [] # the calendars whose meetings aren't offered, by id; Settings lists them to untick
  787. [debug]
  788. perf_log = false # true logs timings to ~/Library/Logs/Codealong/perf.log, on Linux ~/.local/state/codealong/perf.log (Settings › Advanced)
  789. [prices."some-new-model"] # API prices for a model Codealong has none for yet, dollars per million tokens (the Analytics window)
  790. input = 3
  791. output = 15
  792. context = 1000000 # its context window in tokens, which a session's context pie fills
  793. [[accounts]] # in the usage bar's order: dragging a chip there moves its table
  794. name = "claude-work" # what the board shows
  795. harness = "claude" # claude, codex, opencode, antigravity or cursor
  796. home = "~/.claude-work"
  797. command = "claude-work" # used for `claude-work --resume <id>`
  798. start = "background" # where new sessions start: terminal, background, claude-app (~/.claude only), codex-app (~/.codex only), codealong; a start from the quick panel sets it
  799. # acp = "my-adapter --stdio" # the Agent Client Protocol adapter Codealong runs its sessions through, in place of the installed one
  800. usage_cap = 90 # Auto, routing groups and reviews pass over it once a meter reaches this percent (default 90)
  801. monthly = 200 # what its plan costs you a month, in dollars: Paid in the Analytics window
  802. # per_token = true # it pays by the token (an API key): what its work cost at API prices was paid
  803. # disabled = true # turned off: Codealong starts nothing on it and leaves it out of the usage bar; its sessions still show
  804. # chrome_profile = "Work" # the Chrome profile signed in to it: the pages its sessions make (Claude's artifacts) open there; without it, the default browser
  805. [[accounts]]
  806. name = "codex"
  807. harness = "codex"
  808. home = "~/.codex"
  809. command = "codex" # used for `codex resume <id>`
  810. [[accounts]]
  811. name = "opencode"
  812. harness = "opencode"
  813. home = "~/.local/share/opencode" # OpenCode's data folder, with opencode.db
  814. command = "opencode" # used for `opencode --session <id>`
  815. [[accounts]]
  816. name = "antigravity"
  817. harness = "antigravity"
  818. home = "~/.gemini/antigravity" # the app's data folder; its command line's, ~/.gemini/antigravity-cli, is read with it
  819. [[accounts]]
  820. name = "cursor"
  821. harness = "cursor"
  822. home = "~/.cursor" # the command line's folder; the Cursor app's chats are read with this one
  823. [[projects]]
  824. name = "Acme"
  825. repos = ["github.com/acme/*"]
  826. folders = [] # folders that belong to it too; a repo in one is this project's, whatever its remote
  827. chrome_profile = "Work" # its worktrees' previews, and links into them, open in this Chrome profile; without it, the default browser
  828. default = "authorized" # the routing group a start here on Auto goes on (sessions, schedules, reviews, meetings), in place of [routing] auto; without it, [routing] auto's
  829. decisions = "luna" # the one decision model its sessions' words may go to, or "none"; without it, [decisions] default
  830. ```
  831. </details>
  832. Codealong finds each agent by the files it keeps: Claude Code's `~/.claude` and sibling folders,
  833. `~/.codex` and its siblings, OpenCode's and Antigravity's databases, Cursor's `~/.cursor`, and the
  834. folders your shell's wrappers and aliases point `CLAUDE_CONFIG_DIR`, `CODEX_HOME`,
  835. `CURSOR_CONFIG_DIR` or `XDG_DATA_HOME` at, which also name the account and start it. On first run,
  836. the ones in use or signed in go into config.toml; the rest, and any found later, wait under
  837. Settings › Accounts › *Found on this machine*. What else Codealong keeps beside config.toml is listed
  838. in the guide's [Files Codealong keeps](docs/guide.md#files-codealong-keeps).
  839. ## Privacy and safety
  840. - **Nothing of your work leaves your machine unless you turn it on.** Transcripts stay on the
  841. machine that ran them, and Codealong keeps only titles, statuses and short excerpts in memory.
  842. There's no sign-up, and no Codealong server holds anything of yours. Codealong talks only to
  843. your agents' providers, with their own sign-ins, for plan usage and training settings; to GitHub
  844. through your own `gh` sign-in; and to codealong.com to check for updates, which it answers from
  845. this repo's releases (or, when the site can't be reached, it asks the releases itself). A check
  846. tells codealong.com the version and platform you run, which is how copies in use are counted. It
  847. keeps those with a hash of your IP address, never the address, made with a salt it deletes the
  848. next day (its database can restore deleted rows for 30 days). `[updates] check = false` turns
  849. the checks off.
  850. - **Decision models are opt-in, and chosen per project.** Each feature is off until you add your
  851. own key (TypeSafe's, OpenAI's or Google's) and switch it on, and Settings › Decisions says what
  852. each one sends (what you type, and your sessions' titles, branches and latest lines). A
  853. project's sessions' words go only to the model chosen for that project, or to none; a boundary
  854. group's only to its own. Keys stay in your login keychain (on Linux, the desktop's Secret
  855. Service).
  856. - **Linked devices talk to each other**, encrypted end to end (directly, or through relays that
  857. can't read what they pass along), and read a conversation or search what was said only by
  858. asking the machine it's on. Remote control is off until you turn it on at that machine;
  859. then your linked devices can send prompts, answer approvals, start sessions and end them there,
  860. and each request is written to `~/Library/Logs/Codealong/devices.log` (on Linux,
  861. `~/.local/state/codealong/devices.log`).
  862. - **Git is read-only, except for worktrees you ask for or clean up.** Codealong never commits,
  863. checks out, fetches or resets. When you ask for a new worktree, Claude Code and `cursor-agent`
  864. make their own; for other agents and sessions run in Codealong, Codealong creates a git worktree
  865. under `.codealong/worktrees/` (or runs the repo's trusted `WorktreeCreate` hook). It removes a
  866. worktree, and deletes its branch, only when you clean it up (Clean up worktree…, or Mark as done
  867. on a session whose worktree was made for it) and nothing in it
  868. would be lost: no uncommitted file, no commit that isn't on a remote (or at a merged PR's commit),
  869. nothing running in it. A repo whose worktrees a hook makes has them taken down by its
  870. own `WorktreeRemove` hook. Git runs with `GIT_OPTIONAL_LOCKS=0`, so it never holds a lock your
  871. agents need. A pull request is merged only when you press Merge.
  872. - **Only you allow what an agent does.** Agents can see what another agent is waiting on, and deny
  873. it, but never allow it. With Codealong closed, your agents ask you the usual way.
  874. - **It acts only when you ask.** Codealong types into a session only what you send it, or what
  875. a schedule you made sends when its time comes. Mark as done, Close idle sessions and Close stale
  876. terminals end only the sessions and tabs you pick, and their conversations stay, to resume.
  877. - **Sessions you start** open in a new terminal running the account's own command, with your
  878. prompt passed in the window's environment (`CODEALONG_PROMPT`), so nothing in it is typed or
  879. needs quoting. A session run *In Codealong* is a child of the app, allowed what the agent's own
  880. permission settings allow, and asks only you; it ends when Codealong quits.
  881. macOS will ask you about two things. The first time Codealong opens or focuses a terminal tab, it
  882. asks whether Codealong may control Ghostty, iTerm2 or Terminal (Automation); without that,
  883. Codealong can still open plain Ghostty windows. And a repo in Documents, Desktop or Downloads, or
  884. on a removable drive, makes macOS ask whether Codealong may open that folder, again after each
  885. update. Until you answer, those worktrees show without git, and after ten seconds or so the board
  886. names the folders it's waiting on.
  887. ## FAQ
  888. **Is Codealong really free?**
  889. Yes. It's free and open source under the Apache License 2.0, with no account, no trial and no paid
  890. tier. You pay only for what you already pay for: your agents' subscriptions, and a decision model's
  891. key (TypeSafe's, OpenAI's or Google's) if you turn one on.
  892. **What do automatic reviews of pull requests cost?**
  893. Nothing beyond the plans you already pay for. A review is an agent session on one of your accounts,
  894. so it counts against that plan's usage as any session does, and a reviewer passes over an account
  895. that's near its limit. There's no fee by the seat and no API key. An account that pays by the
  896. token, with an API key of its own, pays for a review's tokens as for any other work.
  897. **Do I have to start my agents from Codealong?**
  898. No. Codealong finds every session on your machine, wherever it started: your terminal tabs, Claude
  899. Code's background jobs, the Claude and Codex apps. Keep starting agents the way you do now, and use
  900. the quick panel when it's quicker.
  901. **Does it wrap or proxy my agents?**
  902. No. Codealong reads the files each agent already writes, and starts new work in the official tool,
  903. in your terminal or the maker's own app. Nothing sits between your agent and its model, and no API
  904. keys are involved. The optional plugin adds the `codealong` command, its skills and two hooks to
  905. Claude Code: one so you can answer its permission prompts from Codealong, and one that tells a new
  906. session its todo and worktree. If you choose to run an agent inside Codealong instead, it talks
  907. to the agent over the Agent Client Protocol.
  908. **Can I use several Claude Code accounts?**
  909. Yes. Each account runs the official Claude Code with its own config folder (`CLAUDE_CONFIG_DIR`),
  910. and Codealong finds them on its own, even from an alias in your shell. Settings › Accounts adds
  911. one, starting it with another account's settings, plugins, skills and MCP servers if you like; the
  912. guide's [Another account of the same agent](docs/guide.md#another-account-of-the-same-agent) has
  913. the steps. Follow each provider's terms for how you use your accounts.
  914. **Does it change my git repos?**
  915. Only when you ask for a new worktree (Claude Code and `cursor-agent` make their own; for other
  916. agents and sessions run in Codealong, Codealong creates one under `.codealong/worktrees/` or runs
  917. the repo's trusted `WorktreeCreate` hook), or when you clean up a worktree (removing it and its
  918. branch only when nothing in it would be lost: no uncommitted file and no unmerged commit that
  919. isn't on a remote). Otherwise it runs git read-only, and a pull request is merged only when you
  920. press Merge.
  921. **Which systems, terminals and editors does it support?**
  922. macOS 13 or later, on Apple silicon or Intel, and Linux under X11. On macOS, Ghostty is the best
  923. supported terminal; iTerm2, Terminal, Rex and tmux work too, and sessions Codealong starts can run in
  924. tmux shown in your terminal, always or only while the screen is locked. On Linux, sessions run in
  925. tmux, shown in your terminal emulator. It opens worktrees in VS Code, Cursor, Windsurf, Kiro, Zed, Sublime Text,
  926. Nova, BBEdit, Xcode, the JetBrains IDEs and Android Studio, or any editor you name.
  927. **Does it run on Linux?**
  928. Yes, under X11, with `.AppImage`, `.deb` and `.rpm` installers on the releases page or built from
  929. source ([On Linux](#on-linux)): sessions in tmux, shown in your terminal emulator's windows, and
  930. editors found by their commands. Some of what macOS gives it has no counterpart there, the notch
  931. among them; [the development notes](docs/development.md#linux) say what, and how to try it in a VM.
  932. **And Windows?**
  933. An early build, with x64 and Arm64 installers (unsigned) on the releases page or built from source:
  934. [On Windows](#on-windows) says how, and what it hasn't yet. Help is welcome:
  935. [Contributing](#contributing) says where Windows support starts.
  936. **Can I answer my agents from my phone?**
  937. Soon: [Codealong for iPhone](https://github.com/codealong/codealong-ios) is early, and for now you
  938. build and install it yourself (Get the iPhone app, in Settings › Devices, has an agent do it with
  939. you). Today you can answer an agent from any of your machines: link them, and turn on remote
  940. control on the machine the agent runs on.
  941. **How is it different from apps that run agents in their own window, or their own terminal?**
  942. Those apps see only the agents you start inside them. Codealong reads the agents you already run,
  943. wherever they run, the Claude and Codex apps among them, across harnesses, accounts and machines,
  944. and sends new work to the right one. You keep your terminal and your apps.
  945. [How Codealong compares](https://www.codealong.com/compare/) goes through them one by one.
  946. ### If something's missing
  947. - **An agent's sessions don't show.** Look under Settings › Accounts › *Found on this machine*, or add
  948. the account there by hand.
  949. - **A repo's worktrees don't show.** Add the folder it's in to Settings › General (Codealong looks
  950. three levels deep). Sessions outside your folders are listed under *Elsewhere*.
  951. - **No pull requests.** Sign in to the GitHub CLI with `gh auth login`. A chip at the end of the
  952. accounts bar says when GitHub is signed out or out of requests.
  953. - **Codealong can't bring a terminal tab forward or type into it.** On macOS, allow it under
  954. System Settings › Privacy & Security › Automation.
  955. - **Your terminal answers only once you bring it forward.** macOS naps it while it's behind other
  956. windows. Turn on Settings › General › Keep \<terminal> awake, then quit and reopen the terminal.
  957. - **Something stopped working in the background.** Codealong says so in a chip at the end of the
  958. accounts bar; click it for what happened and what to open to fix it.
  959. ## Contributing
  960. **Contributions are welcome**, most of all another harness (Gemini CLI, Copilot CLI, Amp, Pi, or
  961. whichever one you run) and Windows support. A harness is one module behind the `Adapter` and
  962. `Reader` in `src-tauri/src/harness.rs`, and [adding a harness](.claude/rules/adding-a-harness.md)
  963. says what one needs. Everything Codealong asks of the OS is in `src-tauri/src/os/`: each area that
  964. makes the OS's own calls has a `macos.rs`, a `linux.rs` and a `windows.rs` giving the same
  965. functions, and what merely differs, a path or a program to run, goes by `os::current()`. The
  966. Windows side is a first cut: it builds, the engine's tests pass and the app runs, but it's had
  967. little use; [what it goes without](docs/development.md#windows) is where to start.
  968. [Building from source](#building-from-source) and
  969. [docs/development.md](docs/development.md) have the rest, and
  970. [CONTRIBUTING.md](CONTRIBUTING.md) what a pull request needs: an issue first for anything bigger
  971. than a fix, and screenshots of any changed UI.
  972. ## Building from source
  973. ```bash
  974. git clone https://github.com/codealong/codealong.git
  975. cd codealong
  976. npm install
  977. npm run tauri dev
  978. ```
  979. You'll need Rust 1.96 or later (`rustup`) and Node 22.13 or later (not 23), with Xcode's command line tools
  980. on macOS, or on Linux the packages [On Linux](#on-linux) names. Builds go to `codealong-target`, a
  981. folder beside the clone, which every checkout and worktree of it shares. A development build uses
  982. the same settings and todos as an installed Codealong, and quits it while it runs.
  983. [docs/development.md](docs/development.md) has the rest: building an app bundle, running the tests
  984. and the UI checks, and a map of the code. [CLAUDE.md](CLAUDE.md) has the notes every change follows.
  985. ## Learn more
  986. - **[codealong.com](https://www.codealong.com)**: the website, with what Codealong does, how it
  987. compares with the other tools, and what it costs.
  988. - **[The guide](docs/guide.md)**: every feature in detail, view by view and window by window.
  989. - **[Developing Codealong](docs/development.md)**: building, testing and the code map.
  990. - **[Codealong for iPhone](https://github.com/codealong/codealong-ios)**: your sessions on your
  991. phone.
  992. - **[Third-party notices](THIRD_PARTY_NOTICES.md)**: the icons, fonts and libraries Codealong
  993. includes, and their licenses.
  994. ## License
  995. Copyright 2026 Gordon L. Hempton. The code is under the [Apache License 2.0](LICENSE); copies
  996. carry the [NOTICE](NOTICE). What it includes from others is under their own licenses, listed in
  997. [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). The Codealong name and logo are trademarks, and
  998. the license doesn't grant rights to them: a fork should go by its own name.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.