Projects API

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

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.

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)

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

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

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

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)

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

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

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)

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

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

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

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

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

Remove Project Avatar

projectId

string

required

ID of the project

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

Overview

Endpoints

Projects API

Overview

Data Structures

Project

Commands

List Projects

Add Project

Remove Project

Update Project Settings

Reorder Projects

Folder Management

Create Folder

Rename Folder

Delete Folder

Move Item

Git Operations

Get Project Branches

Get Git Remotes

Get GitHub Remotes

Avatar Management

Set Project Avatar

Remove Project Avatar

Events

project:added

project:updated

project:removed

Error Codes

Next Steps

Worktrees API

Sessions API

Build docs developers (and LLMs) love

Overview

Endpoints

​Overview

​Data Structures

​Project

​Commands

​List Projects

​Add Project

​Remove Project

​Update Project Settings

​Reorder Projects

​Folder Management

​Create Folder

​Rename Folder

​Delete Folder

​Move Item

​Git Operations

​Get Project Branches

​Get Git Remotes

​Get GitHub Remotes

​Avatar Management

​Set Project Avatar

​Remove Project Avatar

​Events

​project:added

​project:updated

​project:removed

​Error Codes

​Next Steps

Worktrees API

Sessions API

Build docs developers (and LLMs) love

Overview

Data Structures

Project

Commands

List Projects

Add Project

Remove Project

Update Project Settings

Reorder Projects

Folder Management

Create Folder

Rename Folder

Delete Folder

Move Item

Git Operations

Get Project Branches

Get Git Remotes

Get GitHub Remotes

Avatar Management

Set Project Avatar

Remove Project Avatar

Events

project:added

project:updated

project:removed

Error Codes

Next Steps