First-launch help: terminal panel won't open (installed .dmg), and what is the "Companion"?

[bluems]

Hi, thanks for building Cate.

I installed the prebuilt .dmg on macOS and the app opens fine, but I'm stuck right away: when I add a terminal panel, it won't start at all. I'd expect it to just launch my default shell (zsh), but nothing happens — I only tried to open a plain terminal, nothing fancy.

A few questions:

1. Terminal panel won't open. On the prebuilt release, is there anything I still need to set up before terminals work, or should they spawn the default shell out of the box? Where are the app logs located so I can share them?

2. What is the "Companion"? I've seen this term referenced but couldn't find it explained anywhere in the README. What is it, is it required for terminals / AI chat to work, and does it need to be installed separately?

3. Getting-started guide or FAQ? Is there a short first-run walkthrough or FAQ beyond the README? I assumed first launch would guide me through the default setup, but I couldn't find where to start.

Environment: macOS 26.5, Intel, Cate 1.3.0 from the latest release.

Happy to provide logs or screenshots. Thanks!

[PaulHorn]

Thanks for the detailed report, and sorry for the rough first launch.

1. Terminal panel won't open. This is a bug on our side, not anything you missed. You're on an Intel Mac, and the 1.3.0 release shipped a macOS build that only contained the Apple Silicon version of our background "companion" daemon. On an Intel Mac that daemon can't start, and the terminal panel depends on it to spawn your shell, so nothing happens when you add a terminal. Out of the box it should just launch your default shell (zsh), so your expectation was correct.

We've already got a fix that ships both the Intel and Apple Silicon daemons in the macOS build and picks the right one at runtime. It's merged to main and will go out in the next release. Once that's published, updating should make terminals work with no extra setup. I've opened #390 to track it.

For logs in the meantime: the main app log is at ~/Library/Logs/Cate/main.log. That's the most useful one to share, and it should show the companion failing to start. There are also per-terminal session logs under ~/Library/Application Support/Cate/TerminalLogs/, but the main log is what we'd want here.

2. What is the "Companion"? It's a small Node.js background process that Cate starts automatically to do the actual work behind panels: spawning terminals (via node-pty), running the AI agent, filesystem operations, and git. The same daemon runs whether your workspace is local or on a remote machine over SSH, which keeps the behavior identical in both cases. You do not install it separately. It's bundled inside the app and started for you on launch. It is required for terminals and AI chat to work, which is why this bug blocked you completely. You're right that it isn't explained in the README, and we'll fix that.

3. Getting-started guide or FAQ? There isn't a first-run walkthrough yet beyond the README, and that's a fair gap. We'll look at adding a short first-run guide and a FAQ entry covering the companion. For now, on a working build, the intended flow is just: open a project, add a terminal or editor panel, and it works without configuration.

Thanks again for flagging this. The Intel fix is the important one and it's on the way.

[PaulHorn]

Quick update — this is resolved on our side.

The Intel macOS fix is merged to main (#385) and tracked in #390. The next release after 1.3.0 ships both the Intel and Apple Silicon builds of the bundled daemon and picks the right one automatically (Intel gets the x64 build, including under Rosetta), so once you update, terminals should spawn your default shell with no extra setup.

On your second question: we've since renamed the "Companion" to the "runtime" internally for clarity. It's the same thing described above — a small Node.js background process Cate bundles and starts for you to run terminals, the AI agent, filesystem ops, and git; nothing you install or configure separately.

A short first-run guide + FAQ entry explaining the runtime is on our list (your third question is a fair gap).

Thanks again for the clear report and screenshot — that's exactly what made this easy to pin down. Closing this out, but please reopen or ping if terminals still don't open after you update to the next release.

[bluems]

Thanks for the quick fix! Honestly I didn't expect such a fast turnaround — I know this takes up your time either way, so I really appreciate it. Can confirm it's working now.