Reference

Troubleshooting

What Magnum tells you when something is wrong, and what to do about it.

An agent isn't found

When no agent is found, or git is missing or doesn't know who commits, the start screen shows Get set up. Each tool shows its version, or Install, which runs its maker's installer (Retry if it fails). Who commits asks for the name and email git puts on commits. Choose Set up this Mac… in ⌘P (Set up this computer… on Linux) to see it any time.

If you install an agent yourself, in a terminal, reopen Magnum so it finds it. On another machine, a session whose agent isn't installed there offers to install it.

Signing in

A session whose agent isn't signed in shows a card. Sign in to Claude offers Claude account (a subscription) or Anthropic Console (billed by use). Sign in to Codex offers ChatGPT account; an OpenAI key in Settings → Accounts works instead. Sign in to Pi offers Sign in…, or In the terminal.

Finish in your browser. If it didn't open, click Open the sign-in page; for Claude, paste the code the page shows. The agent in your terminal uses the same sign-in. A session on another machine signs its agent in there.

A machine won't connect

Control lists your machines, each with how it stands, and Connect. SSH's questions show in Magnum: a new host asks Trust this host? first. When a connection fails, Magnum says why:

• The host can't be reached: check its name, the network or VPN, and that SSH runs there.

• SSH couldn't sign in: check the user name, and that your key is loaded (ssh-add) or the password is right.

• The host's key changed since it was recorded: check with whoever runs it, then remove the old key with ssh-keygen -R <host>.

• Magnum's node can't run there: a home folder mounted noexec, or an unsupported system.

When a connection drops, Magnum reconnects by itself. The agents there keep working, and what you send goes once it's back; Try now doesn't wait. If SSH needs you, the session says Can't reach and the machine's name, with Reconnect.

A node of another version

Each machine runs Magnum's node at Magnum's own build. Magnum replaces one of another build as it connects, and its agents keep running. On a Mac host, one too old for that is replaced once nothing runs in it, and Control says so. So is a Magnum Helper too old for it, and Magnum says so as it starts. Until then, a Balanced lead there may say "Magnum's tools didn't start", naming both versions.

Magnum's tools didn't start

A Balanced lead says this when the tools it starts workers with didn't start, with why. Try again starts its agent again on the same session, with them. The project's own MCP servers are in Settings → MCP servers, each with how it stands; click one for why it didn't connect.

Magnum Helper

Magnum Helper keeps your agents running after Magnum quits. Its menu bar item shows what runs and what needs you, with Open Magnum, Stop All Agents and Quit (Stops Agents). If Board › Now says "Notifications from Magnum Helper are off", click Open Notification Settings and allow them, or agents can't reach you while Magnum is closed.

A hook failed

A session says so when one of Claude Code's hooks fails, times out, blocks your message or a tool, or tells the agent why it may not stop yet, in a line where it happened (once a turn, for a hook failing on every tool). A hook still running after a second shows above the message box. Settings → Hooks has what each hook runs and where it's saved.

Agents left running

An agent can keep running with no Magnum window on it, after Magnum quit or crashed while it worked. Nothing stops it on its own. Control lists it under its machine as left running, with Open, which reopens its session attached to it, and Stop…; ⌘P has both too. Stopping asks first. It ends the agent and what it runs; the conversation stays in history.

A folder that's gone

When a project's folder was moved or deleted, Magnum says Folder not found, and so does the sidebar. Put the folder back, or choose Remove from sidebar in the project's ⋯ menu. A session on another machine says its folder isn't there any more when it's gone there.

On Linux

Magnum needs glibc 2.35 or newer, as on Ubuntu 22.04 or later. Magnum's shortcuts use Ctrl where a Mac uses Command. There's no menu bar: ⌘P has everything. In a terminal, Ctrl+Shift+C and Ctrl+Shift+V copy and paste, Ctrl+C interrupts, and Ctrl+W, Ctrl+K and Ctrl+L go to the shell.

Magnum's node keeps agents running as Magnum Helper does, and shows in the tray where your panel shows status icons. Android needs ANDROID_HOME, or the SDK where Android Studio puts it.

Getting in touch

Write to [email protected], the address on Magnum's website.