Skip to main content

​
Projects

A project is a named container that groups tasks, boards, and releases into a coherent initiative. Projects provide the organizational layer between individual tasks and the overall system.

​
What Projects Do

Projects serve three purposes:
  1. Scope tasks — every task belongs to a project, making it easy to filter and track work per initiative
  2. Scope boards — boards can be project-specific, so different teams use pipelines suited to their workflow
  3. Auto-detection — when you run task commands inside a git repo, the project is detected from the working directory

​
Creating Projects

Projects are created explicitly or auto-detected from repository paths (see the Project CLI reference for all commands):
When you create a task inside a repo that has no project, one is auto-created from the repository name.

​
Default Project

When running commands outside a git repository, Genie needs to know which project to scope to. Set a default:
This default is used for genie task list, genie task create, and other task commands when no repo is detected.

​
Projects and Boards

Each project can have multiple boards. A typical setup:
Set the active board for a project:

​
Projects and Tasks

Tasks reference their project via project_id. When listing tasks, you can filter by project:
For scripting, the JSON output includes repoPath for reliable filtering:

​
Project Stats

View a project’s health at a glance:
This displays task counts by stage, active boards, and overall completion metrics.

​
Database Storage

Projects are stored in the projects table (migration 003) with a reference to the repo path. Task-project relationships are maintained through the tasks.project_id foreign key.

​
Best Practices

Map projects 1:1 with git repositories. This makes auto-detection seamless and keeps task scoping intuitive.
Instead of creating separate projects for features vs. bugs, use different boards within the same project.
If you primarily work on one project, genie project set-default saves typing --project on every command.