Projects

Overview

Projects sit between workspaces and Work items in Zero's hierarchy:

Workspace → Project → Work item → Session

A project maps to a local path on disk — typically a git repository root. Zero reads its branch, dirty state, and file tree at registration time and keeps them updated as sessions run.

Create a project

Before creating, validate the path. Zero checks that the directory is readable, has a recognised project structure, and does not contain path traversal.

POST /projects/validate-root
Body: { "path": "/Users/you/repos/myapp" }

Response:
{
  "path": "/Users/you/repos/myapp",
  "status": "ok",
  "suggested_name": "myapp",
  "markers": ["package.json", ".git"],
  "warnings": [],
  "hard_errors": [],
  "git": {
    "branch": "main",
    "remote_url": "https://github.com/you/myapp",
    "is_dirty": false
  }
}

Once validated, create the project:

POST /projects
Body: {
  "name": "myapp",
  "local_path": "/Users/you/repos/myapp"
}

Response: { "id": "proj_abc", "name": "myapp", ... }

Git status

Retrieve the current git state for a project — branch, dirty flag, recent commit:

GET /projects/:id/git

Response:
{
  "branch": "main",
  "last_commit_hash": "a1b2c3",
  "last_commit_message": "fix: auth token expiry",
  "is_dirty": true,
  "remote_url": "https://github.com/you/myapp"
}

Staged/unstaged status is available at GET /projects/:id/git/status. Per-file diffs are at GET /projects/:id/git/diff.

You can stage, unstage, and commit from the same surface:

Files

Browse and edit project files directly:

GET /projects/:id/files?path=src/auth

Response: [
  { "name": "jwt.rs", "path": "src/auth/jwt.rs", "is_dir": false, "size": 4200 },
  { "name": "middleware", "path": "src/auth/middleware", "is_dir": true, "size": 0 }
]

Read, write, rename, create, and delete files:

Stats

Aggregate statistics for a project — total Work items, session count, proof rate, recent activity:

GET /projects/:id/stats

Response:
{
  "case_count": 14,
  "session_count": 47,
  "proof_rate": 0.71,
  "last_activity_at": "2026-04-30T18:22:00Z"
}

API reference