Stuck?
Start here.

Most problems are a daemon that stopped or a login that expired. Two commands tell you which one. When they do not, a person answers.

first aid
$ cast status

  Version   v1.1.132
  Auth      * authenticated
  Daemon    * running (PID 23887)
  Last sync 0 seconds ago
  Queue     empty
  Convex    * connected

$ cast doctor

  Codecast Doctor  (v1.1.132)

  ✓ auth          authenticated
  ✓ daemon        running, heartbeat 2s ago
  ✓ convex        connected (last sync 2s ago)
  ✓ sync backlog  clear
  ! guidance      run `cast install --all`
  ✓ end-to-end    round trip 1.4s

  ✓ codecast is healthy

Four commands before you write in

Run them in this order. Each one either fixes the problem or tells the next one where to look.

  1. 01cast status

    Is the daemon running, and is this machine signed in? The answer is on the first two lines.

  2. 02cast doctor

    Proves the whole loop: daemon, server, and a live message round trip through a throwaway agent. It names the first thing that fails.

  3. 03cast logs -n 100

    The daemon writes down why it did what it did. Read the last hundred lines before you guess.

  4. 04cast restart

    Restarts the daemon and installs a pending update first. Fixes most of what the first three commands find.

Common problems

New sessions never show up in the inbox

The daemon is not running. Start it with cast start, then run cast setup once so it starts at login and you never think about it again.

The CLI says this machine is not authenticated

Run cast auth to sign in through the browser. On a machine with no browser, create a setup token under Settings, then CLI, and run cast login <token>.

A message sent from the web never reaches the agent

The agent's terminal pane is gone. Use Restart session in the conversation header, or run cast restart <session>. The daemon resumes the transcript in a fresh pane.

The CLI is behind the dashboard

Run cast update, then cast restart. The CLI updates itself on a schedule, and this forces the update now.

The desktop app is stuck on an old version

Run cast desktop-update from any terminal. It replaces the app outside the macOS updater. You can also get the current build from the download page.

Remove Codecast from a machine

Run cast uninstall. It removes the CLI, the daemon, and its login item. Add --keep-config to keep ~/.codecast for a later reinstall.

Send a report we can act on

A report with these five things usually gets fixed on the first reply.

  1. 01Which agent: Claude Code, Codex, Cursor, Gemini, OpenCode, Pi, or Grok.
  2. 02Your OS, and whether the daemon runs on a laptop or a remote box.
  3. 03A link to the session, if the problem is about one session.
  4. 04What you expected, what happened instead, and when it started.
  5. 05The output of the diagnostics command.
diagnostics command
$ cast --version; cast status; cast doctor --no-e2e; cast logs -n 200

The logs describe what the daemon did, not what your agent said. Skim them before you send if your project names are sensitive.

Questions we get

Which agents does Codecast capture?

Claude Code, Codex, Cursor, Gemini, OpenCode, Pi, and Grok. The daemon watches each agent's own session files, so there is nothing to change in how you run them.

Does it work offline?

Yes. The daemon keeps watching and queues what it cannot send. The web and desktop apps paint from a local cache, so your inbox opens before the network answers. Everything catches up when you are back online.

Who can see my sessions?

Only you, until you share. Every session starts private. You share one conversation at a time, with a teammate or with a link. Secrets are redacted before anything leaves your machine, and you can self host the backend. The security page has the full answer.

Where are the desktop and mobile apps?

The Mac app is on the download page, and the iOS app is on the App Store. Both sign in with the same account as the web.

How do I delete my data?

Open Settings, then Accounts, and choose Delete account. That removes your account and everything under it, and it cannot be undone. To clear one machine, run cast uninstall.

I found a security issue. Where do I send it?

Email [email protected]. Please do not open a public issue for it.

Billing, invoices, or an enterprise plan?

Email [email protected]. Plans and prices are on the pricing page.

Still stuck?

Write to us with the output above. We read every message and reply from a real inbox.

Email supportJoin the community