Adding Projects & Roles

One API call creates everything needed for a project to appear in the SpAIglass dropdown. No manual file creation, no config editing, no service restart.

Register Endpoint

POST http://127.0.0.1:8080/api/projects/register

This runs on the VM's local backend (port 8080), not the relay.

Request Body (JSON)

Field	Type	Required	Description
`name`	string	yes	Project directory name. Alphanumeric, hyphens, underscores, dots. Example: `BHMarketing`
`role`	string	yes	Role filename (without .md). Example: `developer`
`roleContent`	string	no	Markdown content for the role file. If omitted, a default template is written.

What It Does

Creates ~/projects/{name}/
Creates ~/projects/{name}/.claude/agents/{role}.md
Registers the project in ~/.claude.json
Creates ~/.claude/projects/{encoded-name}/

The project appears in the dropdown immediately — no restart needed.

Examples

Minimal — default role template:

curl -s -X POST http://127.0.0.1:8080/api/projects/register \
  -H 'Content-Type: application/json' \
  -d '{"name": "BHMarketing", "role": "developer"}'

With custom role content:

curl -s -X POST http://127.0.0.1:8080/api/projects/register \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "BHMarketing",
  "role": "developer",
  "roleContent": "You are the developer for BHMarketing.\n\n## Project Location\n~/projects/BHMarketing/\n\n## Tech Stack\n- Node.js / TypeScript\n- PostgreSQL"
}'

Add a second role to the same project:

curl -s -X POST http://127.0.0.1:8080/api/projects/register \
  -H 'Content-Type: application/json' \
  -d '{"name": "BHMarketing", "role": "qa-lead"}'

Response

{
  "ok": true,
  "project": "BHMarketing",
  "role": "developer",
  "roleFile": "/home/readystack/projects/BHMarketing/.claude/agents/developer.md",
  "projectDir": "/home/readystack/projects/BHMarketing"
}

Idempotent. Calling again with the same name/role overwrites the role file but doesn't break anything else. Safe to retry.

For a richer role file

The default template is bare-minimum. For a real role file, use the role template as a starting point, or see the full setup guide for the frontmatter schema, checklist, and examples.

← Back to full setup guide