Projects help you organize related sessions and configure shared defaults.

Creating Projects

From New Session Dialog

Click + New Session
In the Project dropdown, select + New Project
Enter a project name
Choose a working directory
Continue creating your session

From Sidebar

Right-click in the session list
Select New Project
Configure project settings

Project Settings

Each project can have:

Setting	Description
Name	Display name in sidebar
Working Directory	Default path for new sessions
Default Agent	AI agent to use (Claude Code, Codex, etc.)
Default Model	Model to use (sonnet, opus, etc.)

Assigning Sessions to Projects

When Creating

Select a project in the new session dialog. The session inherits project defaults.

After Creating

Right-click a session
Select Move to Project
Choose the target project

Session Groups

Within projects, organize sessions into collapsible groups:

Creating Groups

Right-click a session
Select Move to Group
Enter a new group name or select existing

Group Hierarchy

📁 My App Project
   📂 Features
      └─ Session: Auth module
      └─ Session: Dashboard
   📂 Bug Fixes
      └─ Session: Fix login
   └─ Session: Main development

Collapsing Groups

Click the group header to collapse/expand. Great for managing many sessions.

Uncategorized Sessions

Sessions not assigned to a project appear under "Uncategorized" at the bottom of the sidebar.

Dev Server Templates

Projects can have pre-configured dev server settings:

{
  "devServer": {
    "command": "npm run dev",
    "portEnvVar": "PORT",
    "env": {
      "NODE_ENV": "development"
    }
  }
}

Create a .agent-os.json file in your project directory. When you start a dev server for this project, it uses these settings automatically.

Project Workflows

Multi-Feature Development

Use projects to separate concerns:

📁 Backend API
   └─ Session: New endpoints
   └─ Session: Database migration

📁 Frontend
   └─ Session: New components
   └─ Session: Styling updates

A/B Testing Approaches

Keep parallel experiments organized:

📁 Auth Refactor
   📂 Approach A - JWT
      └─ Session: Implementation
   📂 Approach B - Session-based
      └─ Session: Implementation

Client Projects

Organize by client:

📁 Client: Acme Corp
   └─ Session: Feature request #123
   └─ Session: Bug fix #456

📁 Client: Example Inc
   └─ Session: New integration

Deleting Projects

Right-click the project
Select Delete Project
Choose whether to delete contained sessions or move them to Uncategorized

Bulk Operations

Select multiple sessions across projects:

Shift+click - Select range
Cmd/Ctrl+click - Toggle individual selection

Then use bulk actions:

Delete selected
Move to project
Move to group