Multi-Project Management

Craft Easy Agentic can serve multiple projects from a single running instance. Each project has its own state, file watcher, runner, and API routes — but they all share one URL and one web UI.

Project registry

Projects are stored in ~/.config/craft-easy-agentic/projects.toml:

[[projects]]
slug = "petanque-life"
name = "Petanque Life"
repo_root = "/home/patrik/esi/petanque-life"
color = "#1A6B5A"

[[projects]]
slug = "airpark"
name = "Airpark"
repo_root = "/home/patrik/esi/airpark-ecosystem"
color = "#F39C12"

---

CLI subcommands

project add

craft-easy-agentic project add <slug> \
  --repo <path>          # absolute or relative path to the project root
  --name "Display Name"  # shown in the dashboard (defaults to slug)
  --color "#1A6B5A"      # accent color in the UI (any CSS hex color)

project list

craft-easy-agentic project list

petanque-life   Petanque Life    /home/patrik/esi/petanque-life
airpark         Airpark          /home/patrik/esi/airpark-ecosystem

project remove

craft-easy-agentic project remove airpark

Removes the entry from projects.toml. Does not touch the project's files.

project sync

Syncs canonical framework files from this repository into a registered project:

craft-easy-agentic project sync petanque-life       # one project
craft-easy-agentic project sync --all               # all projects
craft-easy-agentic project sync petanque-life --dry-run  # preview
craft-easy-agentic project sync petanque-life --force    # overwrite runner-config.yml

See Framework Hub for what sync copies and how projects can opt out.

---

Runtime behavior

When started in web mode with a populated registry:

• A separate file watcher thread is started per project (watches tasks/.tasks-state/ and tasks/).
• Each project gets its own API scope at /api/projects/{slug}/....
• The WS endpoint at /api/projects/{slug}/events emits state updates only for that project.
• The legacy single-project routes (/api/snapshot, /api/runner/start, ...) proxy to the first-alphabetical project for backward compatibility.

Resolution order

When the server starts, it determines which projects to serve:

1. --repo-root <path> flag → ad-hoc single-project (backward-compat mode)
2. ~/.config/craft-easy-agentic/projects.toml exists and has entries → multi-project from registry
3. Auto-discovery: if the current working directory contains tasks/BACKLOG.md → single-project
4. Neither → error with help message

---

Project switcher

The topbar contains a horizontal chip-row of project names. Clicking a chip switches the main view to that project. The active chip is highlighted with the project's accent color.

Clicking Översikt switches to the overview grid — all projects at once, each with full runner controls.

The active project is persisted in localStorage so the dashboard opens to the same project on reload.

---

Per-project API routes

Every dashboard action is scoped per project. The transport layer in the frontend uses the slug from the URL or active selection to build the correct path:

Action	Route
Get state	GET /api/projects/{slug}/snapshot
Start runner	POST /api/projects/{slug}/runner/start
Stop runner	POST /api/projects/{slug}/runner/stop
Force-stop	POST /api/projects/{slug}/runner/force-stop
Pause	POST /api/projects/{slug}/runner/pause
Resume	POST /api/projects/{slug}/runner/resume
Cleanup	POST /api/projects/{slug}/runner/cleanup
Cancel stop	POST /api/projects/{slug}/runner/cancel-stop
List tasks	GET /api/projects/{slug}/tasks
Task detail	GET /api/projects/{slug}/tasks/{id}
File tree	GET /api/projects/{slug}/tree?path=...
File preview	GET /api/projects/{slug}/file?path=...
Chat WebSocket	WS /api/projects/{slug}/chat
Event stream	WS /api/projects/{slug}/events