Appearance
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)
- 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 foldersWithout --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.