Installation and your first project

There are four steps. You do them once per computer and once per project. Before you start, you need:

• a Faundr account (this site);
• Claude Code or Codex installed on your computer. The plugin works in both;
• Node.js 20 or newer. Claude Code and the npm version of Codex already need Node, so it's almost always there.

1. Create the project in the dashboard

1. In Projects, click New project.
2. Give it a name (the app's name, for example) and click Create project.

The project belongs to your current organization, and everyone on that team can see it. If you don't have a team yet, the organization is just yours. See Organization, team and account.

2. Install the plugin

You do this once per computer. The same commands, ready to copy, are in My account → Plugin token.

In Claude Code

Open Claude Code and type these two commands, one at a time:

/plugin marketplace add faundr-dev/faundr-plugin
/plugin install faundr@faundr

Then close and reopen Claude Code so the plugin takes effect.

In Codex

With Codex, you install from your terminal (outside Codex). Run these two commands:

codex plugin marketplace add faundr-dev/faundr-plugin
codex plugin add faundr@faundr

Then open Codex and type /hooks. It lists Faundr's hooks (the triggers that load your project memory, log the work and protect the project) and asks you to trust them once. Until you do, Faundr won't run in your sessions.

In Codex, skills start with $ instead of /. Wherever these docs say /faundr:login, type $faundr:login in Codex. You can also just ask in plain words ("set up Faundr in this project").

3. Connect your agent to your account

1. In your agent, run:

/faundr:login

1. Your browser opens Faundr with a code (for example K7QX-M2PD). Check that it matches the code shown in your terminal and click Authorize.
2. Go back to the terminal. Within a few seconds it replies "Signed in… You have N project(s)".

The token is created on your computer and never goes through the chat. Faundr only receives a fingerprint of it (the hash) and starts accepting it once you authorize. It's saved in ~/.faundr/config.json, which only you can read.

The token is personal. It tells Faundr who is using the agent, and it works for projects in all of your organizations. Each person on the team signs in on their own. My account → Plugin token lists one token per computer you've signed in from, with the date it was last used. Delete the ones you no longer use and they stop working right away.

4. Set up the project

Open your agent in the project's code folder and run:

/faundr:setup

Setup checks everything and turns it all on in one go:

• It handles the safe parts on its own. It links the folder to the project when the folder name (or the package.json name) matches exactly one project, builds the code map, the Stack and the first checks (security, quality, tests, design), turns on the status line and reads your skills.
• It asks first about anything that touches project files or needs something from you: creating the git repository, adding .faundr/ to .gitignore, replacing a status line you already use, the rules block in AGENTS.md (only if your team uses another agent), your personal Supabase token and errors from your live app. Anything you decline won't be asked again.

In Codex: the network rule

Codex runs the agent's commands in a sandbox with no internet access. Faundr's commands need the network to save tasks and features to the dashboard, so in Codex, setup asks whether it can create the Codex rule: a file at ~/.codex/rules/faundr.rules that lets only Faundr's command run outside the sandbox. Everything else stays sandboxed. The rule takes effect in your next Codex session.

Until the rule exists, Codex asks for your approval whenever a Faundr command needs the network. That includes your first $faundr:login and your first $faundr:setup.

What it costs from your plan

The code map, the detected Stack and the checks run on your computer, without AI, and use nothing from your Claude or Codex plan. What costs tokens is what the agent writes. Setup lists each of those items with its estimated cost in tokens, as a share of your 5-hour window and your week (when the Faundr status bar is on), and as the equivalent API price in dollars. Then you choose: essentials only (Overview and skill classification), everything, one by one or nothing for now.

The estimate starts from the size of your code and gets better over time. Every time a skill runs, Faundr measures what it actually used and switches to that number for this project (and, scaled by size, for your team's other projects).

Setup also shows how much the end of each response has been costing (the quick design audit and updates to the Overview and Stack) and offers economy mode, which runs those three only when you ask. Proof of work, the handoff note and security always stay on.

You can run /faundr:setup again at any time. It leaves alone whatever is already right and shows what's still missing. To rebuild the map and the checks, run /faundr:setup --refresh. In a regular terminal, faundr setup does the same thing and asks yes or no as it goes.

Linking the folder by hand

If the folder name doesn't match the project, setup asks you to pick one. You can also link it directly:

/faundr:link

On its own, the command lists the projects you can link and asks which one. If you already know the name, add it: /faundr:link My Store.

This creates a small file called .faundr.json in the folder with the project's ID. It's safe to commit. Anyone who clones the repository lands on the right project once they sign in.

The command with your project's ID, ready to copy, is also inside the project under Settings → General.

Check that it worked

Run /faundr:status in your agent. It shows the server in use, the start of your token, the linked project, the branch and whether the code map exists, and it tells you what's left to set up.

Then ask the agent anything and open the project in the dashboard. In Activity → Session log, the session shows up in real time (the conversation is visible only to you; your team sees the summary).

Recommended first steps

/faundr:setup already builds the code map and offers the AI items below, with the cost of each. If you skipped one or want to redo it, these are the commands:

None of these are required. The security, quality, design and test checks start on their own in your next session.

Optional: status bar

Claude Code only, since Codex doesn't let plugins change its screen. Run /faundr:statusline to see Faundr at the bottom of your agent's screen:

Faundr · My Store · Login screen 2/5 · now: Build the form · graph up to date · 1 concern

The bar only reads files on your computer. It uses no tokens and no internet. If you already have a status bar, Faundr won't replace it. To replace it anyway, use /faundr:statusline --force.

Optional: other agents

Claude Code and Codex both run the plugin. If your team also uses Cursor or another agent that doesn't, /faundr:agents-md copies the team's rules and decisions into AGENTS.md (or CLAUDE.md). That way those agents follow the project's memory too. The block updates itself at the start of every session where the plugin runs. To remove it, use /faundr:agents-md --off.

Multiple projects, multiple folders

• Signing in is per computer. You only do it once.
• Linking is per folder. Each repository has its own .faundr.json.
• In a repository with several parts (for example app/ and site/), you can link each folder to a different project. Faundr looks for .faundr.json by walking up from folder to folder and uses the closest one.