Projects

A project is the unit of work inside an organization: it holds your BMAD workflows, the live task board, task groups, and releases, and it points at one git repository. Everything an agent does — branches, commits, task execution — happens in the context of a project. Before creating one, make sure you have an organization set up (see Organizations & members).

Creating a project

Open Projects → New project in the cockpit, or go to /orgs/<org-slug>/projects/new. The form has three fields:

Field	Required	Constraints
Name	Yes	2–100 characters
Description	No	Max 500 characters, with a live character counter
Git Repository URL	No	Must be a valid URL, or left empty

Any organization member can create projects (the project: create permission is part of the default member role). Creation is subject to your plan's project limit — 5 projects on Free, 20 on Pro, 100 on Ultra. Past the limit you get an error asking you to upgrade; see Plans & billing.

You can create a project without a repository URL and add it later in the project settings, but agents cannot create branches or push code until a repository is linked.

Project slug

The slug is generated automatically from the name: lowercased, special characters stripped, spaces turned into dashes. It is unique per organization — if my-app is taken, the next project named "My App" becomes my-app-2.

The slug appears in every project URL (/orgs/<org-slug>/projects/<project-slug>). Be aware that renaming a project regenerates its slug, which changes all of its URLs.

Linking a git repository

The repository link is what connects the cockpit to your code. Workflows create branches in this repository (see BMAD workflows), and CLI commands such as forge task open fail with an error if the project has no repository URL.

How the field behaves depends on how you signed in:

• Signed in with GitHub — the field becomes a searchable repository picker. It lists your 30 most recently pushed repositories (owned, collaborator, and organization repos), flags private ones with a lock icon, and searches across your account as you type. An "Enter URL manually" option is always available.
• Signed in another way — you paste the repository URL manually.

The GitHub integration uses the OAuth scopes user:email, repo, and read:org. The full repo scope is required because GitHub offers no read-only scope for private repositories — see Security. If you connected GitHub before these scopes were in place, the picker shows a "Reconnect GitHub" prompt.

The repository URL can be changed at any time from the project → Settings.

How the repository is used

The cockpit itself never clones your repository. All git operations run on your machine through the CLI:

• Workflow branches (feature/<workflow-slug>/base and similar) are created and pushed by a connected CLI.
• Task branches are created in the same namespace when agents pick up tasks.
• On an empty (greenfield) repository, the CLI auto-initializes it with an initial commit before creating branches.
• For HTTPS repositories, the CLI reads credentials from your local git credential helper; SSH URLs are used as-is.

Project navigation

The project home page is the live Kanban board. From there, the project navigation gives you:

Page	Route	Purpose
Board	/orgs/<org-slug>/projects/<project-slug>	Live Kanban board with agent streaming — see Tasks & the live board
Workflows	.../workflows	List of BMAD workflows with All / Active / Completed filters and search
New workflow	.../workflows/new	The workflow creation wizard — see BMAD workflows
Task groups	.../task-groups	Groups generated from workflows, with list and dependency-graph views
Releases	.../releases	Release graph, versions and history — see Releases & merge-back
Settings	.../settings	Name, description, repository URL, archive and delete

The projects overview at /orgs/<org-slug>/projects shows a grid of all projects with Active and Archived tabs.

Connecting the CLI

The CLI does not connect to a single project — it connects to your organization, and from there serves every project in it. Once your CLI is linked to the org and running, it receives branch-creation requests, workflow steps, and task dispatches for all projects automatically.

The short version:

forge auth login --server https://forgeai-production-382c.up.railway.app
forge connect

See Authenticating the CLI and Connecting projects for the full setup, including Docker and agent credential configuration.

A connected CLI matters for projects in three places:

• Workflow creation requires a CLI. The workflow form shows "Connect a CLI to create workflows" until at least one CLI device is registered in the organization.
• Branch creation. When you create a workflow on a project with a repository URL, the branch is created by a connected CLI; the wizard shows a live branch status badge.
• Task execution. Tasks on the board are dispatched to connected CLIs with free agent slots.

You can check connection state at any time: the bottom status bar in the cockpit shows a live CLI summary ("N CLIs", agent slot usage) or "No CLI connected", and Settings → CLI Devices lists every registered device with its status.

To work on a project's code locally, use the CLI open commands — for example forge workflow open <workflowId> (the wizard toolbar has a copy button for this exact command) or forge task open <taskId>. Both clone the relevant branch to ~/.forgeai/open/<project-slug>/<branch-slug>/ and open it with your configured opener. The branch slug is the branch name with every slash replaced by --, so feature/user-auth/base lands in feature--user-auth--base/. See the CLI command reference.

Archiving and deleting

Both live in the project → Settings, in the Danger Zone:

• Archive (requires the project: update permission — admin by default) hides the project from active use: visiting an archived project's board or task-groups pages redirects to its settings, where it can be unarchived.
• Delete (requires the project: delete permission — admin by default) is permanent. You must type the exact project name to confirm, and deletion cascades to all workflows, tasks, task groups, and releases in the project. Your git repository is not touched — it lives on GitHub and your machine, not in ForgeAI.

If something looks stuck — branches not being created, tasks not dispatching — check Troubleshooting & FAQ first; the cause is usually a disconnected CLI.