Troubleshooting

Start with diagnostics

Run this from the product repo:

wayform doctor

It checks resolved configuration, login state, gateway reachability, and project selection. Address failed checks before relying on reads or guards.

Runtime hooks fail open, so a coding session can continue even when Wayform is unavailable. No error doesn’t necessarily mean context was loaded.

Authentication isn’t working

Run:

wayform login

Then authenticate the Wayform MCP server in the coding client too. Hook login and client MCP login serve different paths. Start a new coding session after authentication.

For Codex, use codex mcp login wayform in a terminal in the repo. A session started before login can skip loading the server.

GitHub setup is denied

Confirm that:

• The selected memory repo is private and has a first commit.
• The GitHub App can access that repo.
• The repo owner or organization has approved access.
• Your GitHub user is not already linked to a different Wayform space.

If you are joining a team, ask its admin to invite your GitHub username. You should not need someone else’s token.

The desktop app can’t find my agent

Make sure the chosen agent is installed and works from a normal terminal. Check the agent selection and the project’s local folder mapping in app Settings.

Apps opened from Finder or the Dock don’t inherit your shell environment. For a custom gateway, set its URL in app Settings. For CLI or agent discovery problems, check your shell’s PATH and restart the app after changes.

My agent uses the wrong project

Check the project name in .wayform-hook.env and the app’s project mapping. A space can contain more than one project; a project is not the same thing as the space’s GitHub repo name.

For a build, override the project explicitly:

wayform build 12 --client claude --project acme

Use the project that contains the plan. Don’t create a new project just to work around a missing plan.

A plan save conflicts

Someone else may have revised the plan since you opened it. Reload the latest version, reconcile the edits, and save again. Plan history keeps earlier body versions available.

Behavior is old after an update

Update the globally installed CLI:

npm install -g wayform

Restart the affected app or coding client so it picks up the new binary. Run wayform init --remote with your client list if the update includes changed project hooks or skills.

Verify the complete loop

After fixing setup:

1. Ask your agent to record a small, explicit test decision.
2. Confirm a corresponding commit in your private memory repo.
3. Start a new coding session in the same project.
4. Confirm that the agent can retrieve that decision.

If a problem remains, keep the diagnostic output and describe the client and action that failed. Remove tokens, private paths, and sensitive context before sharing logs.