Projects

Projects

Project isolation system for CortexPrism, providing directory-scoped configurations with isolated tool sets, agent assignments, and per-project memory databases.

Architecture

Single file in src/projects/:

File	Purpose
manager.ts	Project CRUD, directory management, cortex-project.json handling

Project Model

Each project is represented by a cortex-project.json file stored within the project's data directory:

{
  "name": "my-webapp",
  "path": "/home/user/.cortex/data/projects/my-webapp",
  "agentId": "backend-specialist",
  "memoryDb": "my-webapp.db",
  "description": "Backend API refactoring project",
  "tools": ["file_read", "file_write", "file_edit", "shell", "git"],
  "created": "2026-06-19T08:48:04.000Z"
}

ProjectConfig Fields

Field	Type	Description
name	string	Project identifier (used as directory name)
path	string	Absolute path to project directory under dataDir/projects/
agentId	string?	Default agent for this project
memoryDb	string?	Dedicated memory database filename
description	string?	Human-readable project description
tools	string[]	Whitelist of available tools
created	string	ISO 8601 creation timestamp

GitHub Import (v0.45.2)

GitHub repositories can be imported directly into CortexPrism projects:

Method	Path	Description
POST	/api/projects/import-github	Clone a GitHub repository into workspace and create a project
GET	/api/projects	List all projects (local + imported)

The import endpoint accepts:

• repoUrl — GitHub repository URL to clone
• agentId — optional agent to assign; clones into <agentId>/<projectName> under the workspace directory

After cloning, the repository is best-effort indexed into Codegraph for code intelligence. The Projects page has an Import from GitHub modal and inline picker with agent selection via dropdown.

The imported project persists the actual cloned workspace path in cortex-project.json, ensuring Codegraph loads the real repository on subsequent sessions. Non-Codegraph-project directories are auto-detected and offered for first-load indexing.

Directory Structure

~/.cortex/data/projects/
├── my-webapp/
│   └── cortex-project.json
├── data-pipeline/
│   └── cortex-project.json
└── cli-tool/
    └── cortex-project.json

Projects are stored under PATHS.dataDir/projects/<projectName>/. Each project directory contains a single cortex-project.json file.

CRUD Operations

Function	Description
createProject(name, opts?)	Create directory, write cortex-project.json, register in memory
loadProject(name)	Read and parse cortex-project.json from disk
listProjects()	Scan project directories, load each config
deleteProject(name)	Remove directory recursively, unregister from memory
getActiveProject()	Find project whose path matches current working directory

createProject()

createProject(name: string, opts?: {
  agentId?: string;
  description?: string;
  tools?: string[];
}): Promise<ProjectConfig>

1. Creates directory at dataDir/projects/<name>
2. Writes cortex-project.json
3. Registers in in-memory map
4. Returns the config

listProjects()

Scans all subdirectories of dataDir/projects/, loads each cortex-project.json, and returns valid configs. If the projects directory doesn't exist, it's created and an empty array is returned.

getActiveProject()

Returns the project whose path matches Deno.cwd(). This enables context-sensitive behavior where the current working directory determines the active project.

CLI

cortex project create <name>              # Create a new project
cortex project create <name> --agent <id> # With specific agent
cortex project create <name> --tools t1,t2# With tool whitelist
cortex project list                       # List all projects
cortex project show <name>                # Show project details
cortex project delete <name>              # Delete project

See Also

• Update System — Version management across projects
• Workflow Engine — Workflows scoped to projects
• Triggers — Event-driven automation per project