Troubleshooting

What to do when something in Faundr doesn't work the way you expect. Always start here:

/faundr:status

It shows the server in use, whether you have a token, which project the folder is connected to, the branch and where the plugin's error log lives. It also tells you what's left to set up.

The dashboard doesn't show my sessions

Check these in order:

1. Is the plugin installed? In Claude Code, /plugin lists your installed plugins. In Codex, run codex plugin list in your terminal. If Faundr isn't there, see Installation and your first project. After installing, close and reopen your agent.
2. Did you log in? If /faundr:status shows "token (not set)", run /faundr:login.
3. Is the folder connected? Your agent needs to be open in the code folder, or in a folder inside it, and that folder needs a .faundr.json. If it isn't connected, run /faundr:link.
4. Is it the right project? /faundr:status shows the connected project. If it's the wrong one, run /faundr:link with the right name.

If all of that checks out, look at the plugin's error log at ~/.faundr/hook.log. Faundr never blocks your agent. When something fails, it writes it there and moves on.

"No token. Sign in first"

This computer has no saved token. Run /faundr:login, check the code in the browser and click Authorize.

"Invalid token"

The token on this computer is no longer valid. It may have been deleted in My account → Plugin token, for example. Run /faundr:login again.

"Folder not linked to a project"

The command needs a connected folder. Run /faundr:link in your code folder. If you work across several folders, each one needs its own .faundr.json, or has to sit inside a folder that has one.

/faundr:link doesn't list my project

• The project may belong to another organization. The link command lists projects from all your organizations, so double-check the name.
• Your role may be Viewer. Viewers can read the dashboard but can't connect folders. Ask an Owner or Admin to change your role under Team.

The /faundr:… commands don't show up

The plugin isn't loaded. Run /plugin to check that it's installed and enabled, and reopen your agent after installing or updating. In Codex, skills start with $: type $faundr to see the list.

Faundr doesn't show up in my Codex sessions

Codex only runs Faundr's hooks after you trust them. Open Codex, type /hooks and trust Faundr's. Codex asks again after each plugin update.

A Faundr command says "fetch failed" in Codex

Codex runs the agent's commands without internet access. Run $faundr:setup and accept the Codex rule, which lets only Faundr's command use the network. It takes effect in your next session. Until then, approve it when Codex asks to run the command outside the sandbox.

The agent keeps going after it seemed done

That's the end-of-response check. Faundr asked the agent to prove the code works, leave a handoff note, review screens or check the definition of done. This is expected. Claude Code labels the request "Stop hook error", but nothing went wrong. In Codex, it shows up as a new request right below the reply. The last reply, the one after the notice, is the complete one: it carries over what mattered from the previous reply along with the result of the check. See What Faundr does on its own.

The agent asked me to confirm a command

Faundr flagged the command as risky because it could delete work or data. Read the explanation and confirm only if that's really what you want. In Codex, the command is blocked and the agent asks you in chat. If you say yes, it runs the same command again and Faundr lets it through once. When the risk is to your files, a checkpoint has already been saved. See Protection.

A command was blocked

Faundr blocks anything that can't be undone (wiping a disk, resetting the production database) and packages that don't exist. The agent shouldn't look for a workaround. If you're sure, run the command yourself in your own terminal.

A finding won't close after the fix

For most findings, Faundr only closes them after rerunning the check and confirming the problem is gone. If one stays open:

• the fix may not have worked. Rerun the check (/faundr:security-scan, /faundr:quality-scan) and read the details;
• an E-n error closes when the same command passes again, so rerun the command that failed;
• for a live app error, use "Resolved in next deploy". It closes for good once the new version is live.

The code map says "map updating" or is empty

• If the project has never built a map, run /faundr:map.
• "Updating" is normal after edits. The map is rebuilt in the background at the end of each response.
• If it stays out of date, run /faundr:map again.

Tests don't run

• Faundr only runs tests when someone asks: !faundr tests-run.
• If the tests look like they use your production database, Faundr won't run them until you confirm. Create a .env.test pointing to a test database.
• If a tool is missing (the test runner, coverage), Faundr shows you the install command. It never installs anything on its own.

/faundr:undo says it needs git

Checkpoints are stored in the project's git repository. If the folder doesn't use git yet, the agent offers to run git init. Checkpoints start being saved from then on.

The end-of-response check uses a lot of tokens

The end-of-response check is the most token-hungry part of Faundr. You can see how much it uses under Insights → Tokens, in the "End-of-response check" slice. It almost always fires only on responses that changed files, and each request (handoff note, Stack, Overview) has a frequency limit.

To spend less, turn on economy mode: the quick design review and the Stack and Overview updates then run only when you ask. /faundr:setup shows what the end of responses cost over the last 30 days and offers the mode. From a terminal, faundr setup --economy all turns it on and faundr setup --no-economy turns it off. Proof, the handoff note and security always stay on.

One of my skills doesn't show up in the dashboard

Faundr reads skills from three places, in both Claude Code and Codex: the repo (the .claude/skills and .agents/skills folders), your personal skills (in ~/.claude/skills, ~/.agents/skills or ~/.codex/skills) and the plugins enabled for this folder (in Codex, the ones turned on in config.toml). Every session rereads the list on its own. If a new skill still isn't under Workflows → Skills, run /faundr:skills. It reads them again and writes when to use each one. A skill that finds problems only sends its results to the dashboard once it's marked Connected, which /faundr:skills does and you can change in the skill's details. See Workflows.

/faundr:browse says the key is missing

The fast browser uses Jev, an outside service that needs a key. Put the key in an environment variable on your computer and run faundr browse-key --env TYPESAFE_API_KEY in a terminal (swap in your variable's name). Never paste the key into the chat. If the command uses your own Chrome (--chrome) and says the extension didn't respond, install or reload the Faundr extension at chrome://extensions.

The app won't start when the folder is in OneDrive

Folders synced by OneDrive, Google Drive or iCloud can confuse development tools, which sometimes stop finding packages that are already installed. If npm run dev says packages like react aren't installed when they are, move the project to a folder outside the sync, such as C:\dev. This isn't a Faundr issue, but it trips up a lot of people who are just starting out.

Still stuck?

Send these to the Faundr team:

• the output of /faundr:status;
• the last lines of ~/.faundr/hook.log;
• the plugin version, shown in /plugin.