What Faundr does on its own

Once the plugin is installed and the folder is linked, Faundr steps in at seven moments in every agent session. This page shows what happens at each one.

Two rules apply to everything here:

• Faundr never blocks the agent because of its own failure. If something on Faundr's side fails (no internet, server down), it exits quietly and logs the reason to ~/.faundr/hook.log. Your work carries on.
• It only acts in linked folders. Outside a folder with .faundr.json, the plugin stays quiet.

1. When the session starts

Faundr builds a summary of the project and hands it to the agent before your first request. The summary is capped at about 10,000 characters and includes:

1. Where the last session left off: requests, commits, completed tasks, the handoff note and the last response. This is skipped when the session just continues a summarized conversation.
2. Team rules, to follow at all times, and technical decisions, so the agent doesn't propose alternatives unless you ask. If space runs out, the decisions for the current feature and the most recent ones go in.
3. Who else is in the project right now, and which files they're in.
4. Budget warning, if spending passed the alert threshold set in Insights → Cost.
5. Requests, messages and team notes written in the dashboard. Each one is delivered only once.
6. Scheduled reminders: skills and workflows the team scheduled for a time that has now come.
7. The current feature and its checklist.
8. The team's active workflows, plus any skills and workflows set to run at the start of a session.
9. Open concerns and what's open in security, errors, quality and tests (only what's new since the previous session is spelled out in full). The quality reminder comes along too, if it's turned on.

Along with it come instructions for the agent to record its work, query the code map (if there is one) and follow design.md (or suggest creating one, if the project has screens and no guide).

2. On every request

Each request goes into the session log. This runs in the background and doesn't slow the agent down.

Before the agent reads your request, Faundr adds short notes, offline, each one only when it applies:

• the request looks like new multi-step work: it suggests planning first with /faundr:planning;
• the request sounds like a rule ("from now on", "never"): it suggests saving it as a team rule;
• the request matches the topic of a team workflow or an enabled skill: it reminds the agent to use it;
• rules and decisions about the request's topic, each one once per session;
• who else is working in the project, when the team has changed since the last note;
• requests and messages that came in from the dashboard or from other sessions.

On the first request of the session, Faundr also kicks off all of these at once, in the background:

3. Before the agent edits a file

Before every file write or edit, Faundr checks the new content on your computer, offline:

• Secret key in the code (Stripe, Supabase service_role, AWS, private keys, Google Cloud, OpenAI, Anthropic, GitHub, GitLab): the edit is blocked, and the agent is told to put the value in .env and read it from code. This doesn't apply to .env and example files. In tests and docs, and for less dangerous keys, Faundr only warns.
• Irreversible migration: if a database migration drops a table or column, empties a table, changes every row, changes a type or renames something, the agent is warned before writing it. It should ask for your OK, make sure there's a recent backup, write how to undo it and, if the published app still uses what's going away, do it in two steps.
• Checkpoint: before the first change in the session, and again every 30 minutes of edits, Faundr saves a snapshot of your files.
• Security alert: if the background check found a new issue in files the agent touched, the agent is told and asks you whether to fix it.
• Broken rule: if the edit introduces a pattern a team rule forbids, the agent is warned.
• File-specific rules and decisions: the ones that apply only to that file arrive before its first edit in the session.
• Who else touches it: if another session on your team is working in the same file, the agent is told. Through the code map, it also learns which other parts use that file before changing it.
• Loop detector: if the same error came back 3 times in a row, or the file is about to change for the 7th time while a command keeps failing, the agent is told to stop, explain to you what's happening, look for the root cause and suggest /faundr:undo.

4. Before the agent runs a command

Before every terminal command (and every SQL statement run through the Supabase tools), Faundr checks what it does. The details are in Disaster protection. In short:

• anything that can't be undone is blocked;
• anything risky makes the agent ask for your confirmation;
• a package that doesn't exist is blocked, and a suspicious package asks for confirmation;
• before the first command that can change files, a checkpoint is saved.

5. After every agent action

• Log: every action goes into the session log.
• Code map: an edited file marks the map as outdated. It's rebuilt at the end of the response.
• Errors: after each check command (build, types, tests, lint, scripts), Faundr reads the output. A failure becomes an E-n in Errors. When the same command passes again, the error closes on its own. Commands like git, grep and the dev server are left out.
• Events: a successful commit, push or deploy, and any new error, get noted. At the end of the response, Faundr asks for the skills and workflows your team attached to that event (see Workflows).
• Commits: a successful git commit clears the "uncommitted" tag from tasks completed before it.
• Plans: a plan approved in the agent's planning mode becomes a feature with a checklist and becomes the current feature.
• To-do lists: the to-do lists the agent builds while it works become tasks in the current feature.

6. At the end of every response

Two things happen.

In the background, without holding anything up:

• the conversation's tokens are added up and sent to Insights (numbers only, never the text);
• if the response changed files, the code map is rebuilt, security and quality are re-checked on the edited files only, design is re-checked if any screen changed, and the checkpoint list is updated.

The end-of-response check, which can ask the agent to keep going. If something is missing, Faundr holds the response open and asks for it, as a list:

1. A request from the dashboard that arrived while the agent was working: handle it before wrapping up.
2. Record the work. The session changed 4 or more files and nothing was recorded in Faundr. If it was a feature or a stage, record what got done. Once per session.
3. Proof that it works. The code changed and no check has passed since then, so the agent should run the build, the tests, the type check or the app and report the result. If it can't run them, it should say so. This is only requested if the project has something to run.
4. Handoff note. Only in big sessions (4 or more files edited, or about 20 minutes of edits), and again every 30 minutes.
5. Quick design review of the edited screens. Only if the project has a design.md, and only listing new issues.
6. Done criteria, once the feature's checklist is finished.
7. Next stage: announce the next one and ask whether to continue, or record the remaining stages.
8. Outdated Stack: update it, once per session.
9. Team skills and workflows set to run at the end of responses that touch certain files, or on an event (commit, push, deploy, new error).
10. Results from a connected skill: if one of your own problem-finding skills ran, record what it found and fixed. See Workflows.
11. Outdated Overview: update it, once per session.

Dashboard requests, events and connected skills count even when the response didn't change any files. Everything else only shows up if the session changed files.

After the steps, the agent writes a complete final response: it repeats what you needed from the previous one (results, open items, questions) along with what the steps changed.

This check never changes code by itself; it only asks the agent. It also doesn't repeat right away, so the agent doesn't get stuck in a loop.

7. When the session ends

The session is marked as ended in the log and the final usage numbers are sent. If that upload gets lost (the computer shut down, the internet dropped), it's resent at the start of the next session.

What you can turn on and off

In a linked folder, the command and key blocks and the security checks are always on. Every other step has a switch in Settings → Automations (the same switches are on each workflow's diagram, under Workflows → From Faundr). When a step is off, it stops running for the whole team starting with the next request.

Economy mode, in Settings → General, turns off the quick design review and the Overview and Stack updates at the end of responses in one go. They run only when you ask.

To turn everything off, disable the plugin (/plugin) or work in a folder that isn't linked.

Some parts have their own controls: