Projects and workspaces

Model

• A project is a directory you registered on a daemon, usually a git repository. IDs look like prj_a00e87f3186c7681.
• A workspace is one working directory inside a project: the original checkout, a git worktree, or a plain directory. Agents, terminals and scripts run in a workspace. IDs look like wks_b5b04560aaa0b892.
• Projects and workspaces belong to one daemon and are stored in ~/.frogg/projects/.

Add a project

• App: Add project in the sidebar, then choose a folder on the daemon host.
• CLI: frogg project create /path/to/repo.

Import existing Claude Code or Codex sessions with Import session on the home screen. To bring in a whole project with its conversations, from the daemon host or from your computer, use Add project → Import project and conversations; see Import projects and conversations.

Workspaces and worktrees

When you start work you choose isolation:

Isolation	What you get
local	The agent works directly in the checkout
worktree	frogg creates a git worktree on a new or existing branch; your checkout stays untouched

Worktree modes:

Mode	Creates
branch-off	A new branch from a base ref (--base)
checkout-branch	A worktree for an existing branch
checkout-pr	A worktree for a pull request or merge request (--pr-number, --forge)

frogg workspace create --isolation worktree --mode branch-off --new-branch feature/export
frogg agent run --new-workspace worktree --new-branch fix/flaky-test "Fix the flaky upload test"

Worktrees live under ~/.frogg/worktrees/<project hash>/<slug>. Change the root with worktrees.root in config. If you do not name a branch, frogg can generate one from the first prompt.

Unfinished new-workspace forms

If you leave the new-workspace screen before launching, the sidebar shows a New workspace (draft) row, with the project name when one is selected. Selecting it reopens the form with its project, prompt, attachments, provider and model selections, isolation and starting ref.

• A launch in progress stays locked while you navigate elsewhere, so returning to the draft cannot submit it twice.
• If the launch fails, the draft stays in the sidebar with its error so you can retry.
• A successful launch removes the draft.
• The draft rows are kept in memory only. Reloading or restarting the app clears them.

Archiving a workspace removes its frogg-owned worktree once nothing else uses it:

frogg workspace archive wks_b5b04560aaa0b892

Prepare new worktrees

A fresh worktree has no node_modules, .env or build output. Describe setup in frogg.json at the repository root:

frogg.json

{
  "worktree": {
    "setup": ["npm ci", "cp \"$FROGG_SOURCE_CHECKOUT_PATH/.env\" .env"],
    "teardown": "docker compose down"
  }
}

The app nudges you with Set up worktree scripts until a project has setup commands.

Scripts and services

frogg.json scripts run in a workspace. A service gets its own port, env vars and a proxy URL, so the same dev server can run in several worktrees at once.

frogg.json

{
  "scripts": {
    "api": { "type": "service", "command": "npm run dev -- --port $FROGG_PORT" },
    "test": { "command": "npm test" }
  }
}

frogg script start api
frogg script ls

Full reference: project config.

Terminals

Each workspace can have terminals in the app. The CLI and agents can drive them too:

frogg terminal create --name build
frogg terminal send-keys <terminal-id> "npm run build" Enter
frogg terminal capture <terminal-id> --scrollback

Labels and archiving

• Workspaces can be renamed (frogg workspace rename) and labelled in the app.
• Archived agents and workspaces disappear from the sidebar but keep their history. frogg agent ls -a includes archived agents.