Project config (frogg.json)

Put frogg.json in the root of a git repository. The daemon reads it when it creates worktrees and when you run workspace scripts. The file name is frogg.json in every brand. You can edit it from the app in project settings.

An invalid entry is ignored rather than failing the workspace, so check the app or frogg script ls after editing.

Example

{
  "worktree": {
    "setup": ["npm ci", "cp \"$FROGG_SOURCE_CHECKOUT_PATH/.env\" .env"],
    "teardown": "docker compose down",
    "terminals": [{ "name": "shell", "command": "bash" }],
    "servicePorts": { "range": "4100-4199" }
  },
  "scripts": {
    "api": { "type": "service", "command": "npm run dev -- --port $FROGG_PORT" },
    "web": { "type": "service", "command": "API_URL=$FROGG_SERVICE_API_URL npm run web" },
    "docs": { "type": "service", "command": "npm run docs", "port": 4321 },
    "test": { "command": "npm test" }
  },
  "metadataGeneration": {
    "branchName": { "instructions": "Use the form feature/<ticket>-<slug>." },
    "commitMessage": { "instructions": "Conventional commits, imperative mood." }
  }
}

`worktree`

Key	Type	Runs
`setup`	string or string[]	In the background after frogg creates a worktree, in order, in the worktree
`teardown`	string or string[]	When frogg removes the worktree
`terminals`	`[{ name?, command }]`	Terminals opened in a new worktree
`servicePorts`	`{ range }` or `{ portScript }`	How service ports are chosen

Setup and teardown commands receive:

Variable	Value
`FROGG_SOURCE_CHECKOUT_PATH`	The checkout the worktree was created from (alias `FROGG_ROOT_PATH`)
`FROGG_WORKTREE_PATH`	The worktree
`FROGG_BRANCH_NAME`	The worktree’s branch
`FROGG_WORKTREE_PORT`	A port reserved for this worktree

Service ports

{ "range": "4100-4199" } picks a free port in the inclusive range.
{ "portScript": "./scripts/port.sh" } runs a script with arguments <scriptName> <workspaceId> <branch> <cwd> and env FROGG_SCRIPTNAME, FROGG_WORKSPACE_ID, FROGG_BRANCH_NAME, FROGG_WORKTREE_PATH. It must print one port within 10 seconds.
Without either, the daemon’s worktrees.servicePorts applies, then any free port.

`scripts`

Each key is a script name.

Key	Type	Meaning
`command`	string	Shell command, run in the workspace directory
`type`	`"service"`	Optional. A service gets a port, a proxy URL and env vars. Without it, the script runs once in a terminal
`port`	number	Fixed port for a service. Two services with the same fixed port are an error

Services receive HOST, FROGG_PORT, FROGG_URL, and FROGG_SERVICE_<NAME>_PORT / FROGG_SERVICE_<NAME>_URL for every service in the workspace. <NAME> is uppercased with other characters replaced by _, so api becomes FROGG_SERVICE_API_URL.

Service URLs go through the daemon’s service proxy: http://<script>--<branch>--<project>.localhost:<daemon port>. The branch part is omitted on main or master. Set daemon.serviceProxy.publicBaseUrl to publish them under your own domain.

Run scripts from the app’s workspace Scripts menu, or:

frogg script ls
frogg script start api
frogg script stop api

`metadataGeneration`

Instructions appended when frogg generates text for this project.

Key	Used for
`title`	Agent and workspace titles
`branchName`	Worktree branch names generated from the first prompt
`commitMessage`	Commit messages from the app’s commit action
`pullRequest`	Pull request titles and descriptions

Which model generates the text is set per daemon in agents.metadataGeneration.providers (configuration).

A real example

frogg’s own repository uses frogg.json to install dependencies in new worktrees and to run its dev daemon and app as services on per-worktree ports. See frogg.json at the root of the repository.