---
url: https://clusto.app/docs/project-import.md
description: >-
  Import the project folders you already use with Claude Code or Codex as Clusto
  projects, from the app or the clusto CLI, on any node in the cluster.
---

# Importing projects from Claude Code and Codex

If you already work with Claude Code or Codex, the folders you use are recorded in
their settings. Clusto can read those settings on a node and turn the folders you pick
into Clusto projects, so you do not have to add each one by hand.

Project import is free on every plan.

## Where to start it

* **Locations** view, when you have no projects yet: **Import from Claude Code / Codex**
* **New Project** dialog: **Import from Claude Code / Codex** under the title
  (the same dialog can instead clone a repository with **Clone from URL**, see
  [GitHub](/github#clone-a-repository-as-a-project))
* **Settings > Daemon Setup**: the **Import projects** card
* The F1 command palette: **Import projects from Claude Code or Codex**

## Picking folders

The dialog asks the node for every folder its agent tools know and lists them, most
recently used first. Each row shows the suggested project name (the folder's last
part), the full path, a **Claude Code** and/or **Codex** badge for where it was found,
and when it was last used, if the tool records that.

* Tick the folders you want, or use **Select all**, then **Import**.
* In a cluster with more than one node, pick the node first. Each node is scanned for
  its own folders, and the projects are created on that node.
* Folders that are already a project on the node, or that no longer exist, are not
  offered. **Show folders already added or missing** lists them for reference.
* **Scan again** re-reads the settings, for example after you opened a new folder in
  Claude Code.

Each imported project uses the node's default session user and shell, like a project
created with **New Project**. Edit it afterwards to change the name, description,
run-as user or default shell.

## What is read

The node reads the settings of its session user: the account terminals and agents run
as on that node (the node's **Default session user**, else the run-as user of its
projects, else the daemon's own account).

| Tool | Source |
|------|--------|
| Claude Code | The `projects` entries of `~/.claude.json` |
| Claude Code | The working folder named in the transcripts under `~/.claude/projects/` |
| Codex | The `[projects."<path>"]` tables of `~/.codex/config.toml` |
| Codex | The working folder of the 2,000 newest session logs under `~/.codex/sessions/` |

`CLAUDE_CONFIG_DIR` and `CODEX_HOME` are honored when they are set in the daemon's
`[env]` configuration. Folders Clusto itself created for chats (the chat folder and the
chat workspaces folder) are left out.

The scan only reads. It never changes the Claude Code or Codex settings, and a file
that is a link pointing outside the user's home is not followed.

## Rules when importing

* Only absolute paths to folders that exist on the node are imported.
* A folder that a project on the node already uses is skipped, even when the path is
  written differently (a trailing slash, or on Windows a different case or separator).
* The result lists what was imported and what was skipped and why.

## From the CLI

```
clusto project import [--node <NODE_ID>]                 # list what the node knows
clusto project import --all [--node <NODE_ID>]           # import every new folder
clusto project import <PATH>... [--node <NODE_ID>]       # import the given folders
```

Without `--node` the connected node is used. The listing marks each folder `new`,
`project` (already a project) or `missing`.

## Protocol

Both requests go to the named node, which the connected node forwards to when it is a
peer. They need the admin token; session credentials are refused.

```json
{"type": "list_project_import_candidates", "node_id": "<uuid>"}
{"type": "import_projects", "node_id": "<uuid>", "paths": ["/home/me/app"]}
```

Replies are `project_import_candidates` (`candidates`: `path`, `name`, `sources`
of `claude` / `codex`, `exists`, optional `project_id` and `last_used`),
`projects_imported` (`created` projects and `skipped` entries with a `reason` of
`invalid_path`, `missing` or `already_project`) or `project_import_error`.
