Troubleshooting

# Start with doctor

rift --version
rift doctor
rift status

Doctor is read-only by default. It checks setup and reports findings with suggested remedies, including integration and encryption-key problems. Run it in the project with the issue so the result describes the right repository.

Read the proposed remedy before applying it. When a finding offers a safe repair, rift doctor --fix can apply supported fixes. It does not automatically repair every integrity problem. Keep captured history and project keys when investigating a failure.

# My agent is working, but no sessions appear

1. Check that you are using Claude Code, Codex, or Antigravity. A detected but unsupported agent is not captured.
2. Check that the agent is working in the project or worktree you set up.
3. Restart the agent after setup or changes to integration settings.
4. Approve its project trust and hook prompts. Rift cannot approve those on your behalf.
5. Run a small task, then check rift session list and rift doctor again.

Use the agent setup guide to review settings. Do not infer working capture solely from the presence of configuration files.

# Setup conflicts and worktrees

If setup names an edited or externally owned file, follow its finding. Rift refuses to overwrite configuration it cannot safely manage. Do not delete another tool's settings just to clear the warning.

A new clone needs setup on this machine. A linked Git worktree may need adoption into an already configured project:

rift worktree status
rift worktree list

If the status calls for it, run rift worktree adopt from the affected worktree. If the Rift command itself is missing, check the installation location and PATH in the installation guide.

# Display problems and empty views

Try rift --ascii for a simpler display. If a key behaves differently from what you expected, dismiss the current menu or overlay and check the hint bar. Shortcuts depend on the view.

Little history or no Recall savings can be normal for a new project. Check that capture is healthy, use the agent on actual work, and compare the same reporting period. See Recall & savings before interpreting an empty or estimated number.

# Report an issue

rift doctor --report

This prints counts, states, and versions. Paths, names, and messages are replaced with their lengths. It runs read-only and sends nothing automatically. Review the output before pasting it into a GitHub issue.

• Your OS, CPU architecture, terminal, Rift version, and agent version.
• What you expected and what actually happened.
• The smallest steps that reproduce the issue, using non-sensitive examples.
• The diagnostic report, if you choose to share it.

Keep credentials, private source, customer data, and unnecessary session content out of public reports. See privacy & data for what Rift stores locally.