Local development with a coding agent

A coding-agent harness can inspect the repository, run the Supacharger and Supabase CLIs, edit files, and verify the result. Use a coding mode with access to the local project and terminal. A normal chat-only conversation cannot prepare files or run local commands.

This guide uses Codex and Claude Code as examples. The Supacharger workflow is the same in any harness that can read the repository, run commands, show diffs, and request approval before sensitive operations.

1. Install the local prerequisites

Install these tools before asking the agent to set up the application:

• Git
• Node.js 22 or later
• npm 11, as declared by the Supacharger core package
• Docker Desktop or Docker Engine for the local Supabase stack
• a coding-agent harness

The project runs the Supabase CLI with npx, so a separate global Supabase CLI installation is not required. Install the Supacharger CLI globally and verify that it is available:

npm install -g @glowplug/supacharger-cli
supacharger --help

The Stripe CLI is optional until you need to test billing webhooks locally.

2. Choose a coding-agent harness

ChatGPT with Codex

If you are starting from ChatGPT, use its Codex coding environment rather than a standard chat. Codex can work against a local repository from the desktop app or terminal. Follow the current Codex CLI installation guide, open the application directory as the workspace, and start the agent from that directory.

Codex reads repository guidance from AGENTS.md. Supacharger already includes this file, so ask Codex to read it before making changes. Do not run /init over established project instructions.

Claude Code

Follow the current Claude Code setup guide, then start Claude from the application directory:

cd /path/to/your-project
claude

Claude Code reads project guidance from CLAUDE.md. If the project has only AGENTS.md, add a small CLAUDE.md that imports the shared instructions instead of maintaining two divergent copies:

# Project instructions

See @AGENTS.md.

Claude Code supports file imports in CLAUDE.md; see How Claude remembers your project. Review the imported instructions before approving work.

3. Create or open the Supacharger project

To create a new application, run the CLI from the parent directory. The target should be a new or empty directory because supacharger init installs the complete canonical starter there. Never point it at files you need to preserve; for a non-empty target, the CLI can offer to remove the existing contents except .git.

supacharger init my-project
cd my-project

For an existing application, clone it normally and open its repository root in the agent harness. Do not run supacharger init inside an established project.

4. Give the agent the right context

Start with an orientation request that does not authorize changes:

Orient yourself to this Supacharger repository before changing anything.

1. Read AGENTS.md and any more specific instruction files.
2. Inspect README.md, package.json, the lockfile, .supacharger metadata,
   and the local environment example.
3. Verify the available versions of Node, npm, Git, Docker,
   the Supacharger CLI, and the project-scoped Supabase CLI.
4. Report missing prerequisites and the exact local setup commands you propose.

Do not edit files, print secret values, link a hosted project, push migrations,
or change any hosted service yet.

This preflight gives the agent the repository's actual package manager, scripts, ownership rules, and validation commands instead of relying on generic framework assumptions.

You can also direct the agent to Supacharger's maintained setup instructions:

Fetch and follow the appropriate instructions to set me up for Supacharger from
https://app.specdrive.dev/agents/setup-supacharger.md

Before executing commands, compare the instructions with AGENTS.md and the
current repository. Show me any conflict or destructive step first.

Treat fetched instructions like code: confirm the source, review the proposed commands, and do not approve operations outside the current project without understanding why they are needed.

5. Let the agent prepare the local environment

After reviewing the preflight, give the agent a local-only implementation request:

Set up this Supacharger application for local development.

- Follow the repository instructions and use its declared package manager.
- Install dependencies.
- Create .env.local from the supplied example if it does not exist.
- Never invent, reveal, or commit secrets; stop and tell me which values I must add.
- Start the local Supabase stack and apply the local migrations.
- Generate current database types.
- Run supacharger doctor and the repository's relevant checks.
- Start the development server and report the local URL.

Keep all database work local. Do not link, reset, migrate, or reconfigure a
hosted Supabase project. Preserve unrelated working-tree changes.

A typical Supacharger project uses commands like these, but the agent should prefer the scripts declared by the current repository:

npm install
cp .env.local.example .env.local
npx supabase start
npm run db:reset
npm run generate-types
supacharger doctor
npm run build
npm run dev

Some local environment values come from npx supabase status. Add them to .env.local without pasting service-role keys, database passwords, Stripe secrets, or other credentials into the chat transcript.

6. Verify the first run

Before building features, confirm that:

• node --version reports Node 22 or later;
• Docker is running and npx supabase status succeeds;
• the local database resets without migration errors;
• generated Supabase types are current;
• supacharger doctor passes or reports only understood follow-up work;
• the application build succeeds;
• the local application loads; and
• git diff contains only expected setup changes and no secrets.

Ask the agent to summarize every changed file, every check it ran, and anything it could not verify. Review the diff before committing.

7. Keep local and hosted work separate

Local setup does not configure a hosted Supabase project, Vercel, authentication providers, SMTP, email templates, or production secrets. When the local application is healthy, continue with the Full setup guide.

For a hosted step, name the intended account, project, and environment explicitly. Always preview linked database migrations before applying them, and never let an agent infer that production is the intended target.