Projects

Every AI agent session starts from zero unless someone remembers the context. Projects are that someone. They hold your stack, your repos, your docs, and your decisions so agents do not start every session asking "what framework are we using?". Without projects, you repeat the same context over and over. With projects, agents start with everything they need.

A project is the main container in Almirant. It groups boards, work items, sprints, documents, repositories, and configuration under a single entity. All your team's work is organized within a project.

Creating a project

Almirant includes a guided wizard for creating projects. Access it from the sidebar menu or from the /projects/new route.

Wizard steps

1. Name and description -- Define a unique name and an optional project description.
2. Visual appearance -- Choose a representative color and icon to quickly identify the project in the navigation.
3. Tech stack -- Specify the project's technologies (languages, frameworks, databases). This information is used by the AI to contextualize tasks.
4. Environment URLs -- Register the production and staging URLs for quick access and so the AI can reference them.
5. Organization and client -- Associate the project with an organization and optionally with a client.
6. Confirmation -- Review the details and create the project.

Configuration fields

Field	Description	Required
name	Project name	Yes
description	General project description	No
color	Color for visual identification in the sidebar	No
icon	Representative project icon	No
techStack	Array of technologies used (e.g., ["Next.js", "PostgreSQL"])	No
productionUrl	Production environment URL	No
stagingUrl	Staging environment URL	No
client	Associated client name	No
organizationId	Organization that owns the project	Yes

Project dashboard

When accessing a project (/projects/[id]), a dashboard is displayed with:

• Work items summary -- Counters by type and current status.
• Active boards -- List of the project's boards with direct access.
• Active sprint -- Information about the current sprint, if one exists.
• Repositories -- GitHub repositories connected to the project.
• Recent activity -- History of changes and project events.

Doc links

Each project can have links to external documentation. Doc links allow you to associate relevant URLs (Confluence, Notion, Google Docs, internal wikis) with the project so that both the team and the AI have quick access to context.

To add a doc link:

1. Access the project.
2. Go to the Doc Links section.
3. Enter the URL and a descriptive title.
4. Save the link.

Project notes

Projects include a notes system for recording decisions, technical context, or any relevant information that doesn't fit into a work item. Notes are associated with the project and visible to the entire team.

Repositories

Connect GitHub repositories to the project so the AI can reference code, create pull requests, and link commits with work items. See the integrations section for more details on GitHub configuration.

Project screenshots

You can attach screenshots to the project to visually document the current state of the application, mockups, or any graphical reference.

Transferring a project

A project can be transferred between organizations. The transfer is atomic and includes:

• The project with all its configuration.
• All associated work items (including ideas and milestones).
• The boards and column remapping.

To transfer a project:

1. Access the project settings.
2. Select Transfer project.
3. Choose the destination organization.
4. Confirm the transfer.

warning

The transfer moves the entire project. Make sure the destination organization has the appropriate permissions and configuration before proceeding.

Deleting a project

Deleting a project is permanent and removes all associated data (boards, work items, sprints, documents, notes, repositories). This action cannot be undone.

1. Access the project settings.
2. Select Delete project.
3. Confirm by typing the project name.

danger

Deleting a project permanently removes all boards, work items, sprints, and associated data irreversibly.

For developers

For Developers

Application routes

Route	Description
/projects	List of all projects
/projects/new	Project creation wizard
/projects/[id]	Project dashboard

MCP tools

The following tools are available via MCP to manage projects programmatically:

Tool	Description	Main parameters
list_projects	Lists all projects in the organization	organizationId (optional if projectId is in session)
create_project	Creates a new project	name, description, techStack, productionUrl, stagingUrl
update_project	Updates fields of an existing project	projectId, fields to update
get_project	Gets the complete details of a project	projectId
get_project_roadmap	Gets the project roadmap with epics and features	projectId

Example: Create a project via MCP

Tool: create_project
Parameters:
  name: "My Web Application"
  description: "SaaS platform for inventory management"
  techStack: ["Next.js", "PostgreSQL", "Tailwind CSS"]
  productionUrl: "https://app.example.com"
  stagingUrl: "https://staging.example.com"

Example: Query the roadmap

Tool: get_project_roadmap
Parameters:
  projectId: "project-uuid"

Returns the hierarchical structure of the project with epics, features, and their current progress.