Projects API

Manage Git projects and repositories

Overview

The Projects API provides functionality for managing Git repositories, including adding/removing projects, organizing them in folders, and configuring project settings.

Data Structures

Project

id · string · required

Unique identifier (UUID v4)

name · string · required

Display name (derived from repo directory name or folder name)

path · string · required

Absolute path to the original git repository (empty for folders)

default_branch · string · required

Branch to create worktrees from (empty for folders)

added_at · number · required

Unix timestamp when project was added

order · number · default: 0

Display order in sidebar (lower = higher in list)

parent_id · string | null

Parent folder ID (null = root level)

is_folder · boolean · default: false

True if this is a folder (not a real project)

avatar_path · string | null

Path to custom avatar image (relative to app data dir)

enabled_mcp_servers · string[] | null

MCP server names enabled by default for this project (null = inherit from global)

custom_system_prompt · string | null

Custom system prompt appended to every session execution

default_provider · string | null

Default provider profile name for sessions (null = use global default)

default_backend · string | null

Default CLI backend for sessions: “claude” | “codex” | “opencode” (null = use global default)

worktrees_dir · string | null

Custom base directory for worktrees (null = use default ~/jean)

linear_api_key · string | null

Linear personal API key for fetching issues (per-project)

linear_team_id · string | null

Linear team ID to filter issues (null = show all teams)

Commands

List Projects

Retrieve all projects and folders.

Request

const projects = await api.invoke('list_projects');

Add Project

Add a Git repository to Jean.

path · string · required

Absolute path to the Git repository

parentId · string

Parent folder ID (omit for root level)

Request

const project = await api.invoke('add_project', {
  path: '/Users/john/projects/my-app',
  parentId: null
});

Remove Project

Remove a project from Jean (does not delete files).

projectId · string · required

ID of the project to remove

Request

await api.invoke('remove_project', {
  projectId: '550e8400-e29b-41d4-a716-446655440000'
});

Update Project Settings

Update project configuration.

projectId · string · required

ID of the project to update

defaultBranch · string

Branch to create worktrees from

customSystemPrompt · string

Custom system prompt for AI sessions

enabledMcpServers · string[]

List of MCP server names to enable

defaultProvider · string

Default provider profile name

worktreesDir · string

Custom worktrees base directory

Request

const updated = await api.invoke('update_project_settings', {
  projectId: '550e8400-e29b-41d4-a716-446655440000',
  defaultBranch: 'develop',
  customSystemPrompt: 'You are an expert in React development.',
  worktreesDir: '/Users/john/worktrees'
});

Reorder Projects

Reorder projects and folders.

projectIds · string[] · required

Array of project IDs in the desired order

Request

await api.invoke('reorder_projects', {
  projectIds: [
    '550e8400-e29b-41d4-a716-446655440000',
    '660e8400-e29b-41d4-a716-446655440001'
  ]
});

Folder Management

Create Folder

Create a folder for organizing projects.

name · string · required

Folder name

parentId · string

Parent folder ID (omit for root level)

Request

const folder = await api.invoke('create_folder', {
  name: 'Work Projects',
  parentId: null
});

Rename Folder

folderId · string · required

ID of the folder to rename

name · string · required

New folder name

Request

const folder = await api.invoke('rename_folder', {
  folderId: '660e8400-e29b-41d4-a716-446655440001',
  name: 'Personal Projects'
});

Delete Folder

Delete an empty folder.

folderId · string · required

ID of the folder to delete

Request

await api.invoke('delete_folder', {
  folderId: '660e8400-e29b-41d4-a716-446655440001'
});

Move Item

Move a project or folder to a different parent.

itemId · string · required

ID of the item to move

newParentId · string

ID of the new parent folder (null for root)

targetIndex · number

Target position in the new parent (optional)

Request

const item = await api.invoke('move_item', {
  itemId: '550e8400-e29b-41d4-a716-446655440000',
  newParentId: '660e8400-e29b-41d4-a716-446655440001',
  targetIndex: 0
});

Git Operations

Get Project Branches

List all branches in a project’s repository.

projectId · string · required

ID of the project

Request

const branches = await api.invoke('get_project_branches', {
  projectId: '550e8400-e29b-41d4-a716-446655440000'
});

Get Git Remotes

List all Git remotes for a repository.

repoPath · string · required

Absolute path to the repository

Request

const remotes = await api.invoke('get_git_remotes', {
  repoPath: '/Users/john/projects/my-app'
});

Get GitHub Remotes

List GitHub remotes only.

repoPath · string · required

Absolute path to the repository

Request

const githubRemotes = await api.invoke('get_github_remotes', {
  repoPath: '/Users/john/projects/my-app'
});

Avatar Management

Set Project Avatar

Set a custom avatar image for a project.

projectId · string · required

ID of the project

Request

const result = await api.invoke('set_project_avatar', {
  projectId: '550e8400-e29b-41d4-a716-446655440000'
});

Remove Project Avatar

projectId · string · required

ID of the project

Request

const result = await api.invoke('remove_project_avatar', {
  projectId: '550e8400-e29b-41d4-a716-446655440000'
});

Events

The following events are emitted for project changes:

project:added

Emitted when a project is added.

{
  "type": "event",
  "event": "project:added",
  "payload": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "my-app",
    ...
  }
}

project:updated

Emitted when a project is updated.

{
  "type": "event",
  "event": "project:updated",
  "payload": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "my-app",
    ...
  }
}

project:removed

Emitted when a project is removed.

{
  "type": "event",
  "event": "project:removed",
  "payload": {
    "project_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Error Codes

Error	Description
Project not found: {id}	The specified project ID does not exist
Path is not a git repository: {path}	The path does not contain a .git directory
Folder name already exists: {name}	A folder with this name already exists at this level
Cannot delete non-empty folder	The folder contains projects or subfolders
Would exceed max nesting depth	Moving would create more than 3 levels of nesting
Cannot move item into itself or descendant	Circular parent-child relationship

Next Steps

Worktrees API

Create and manage worktrees

Sessions API

Handle chat sessions