Agent: Project

Retrieve metadata for the active project that Hoody Agent is working with, and update project properties such as its display name, icon, and startup commands. Use these endpoints when a workspace needs to discover which project is currently loaded, or when you want to change presentation or behavior settings without touching branches or worktrees.

---

Get current project

GET /api/v1/workspaces/{workspaceID}/project/current

Retrieve the currently active project that Hoody Agent is working with.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	The workspace identifier.

This endpoint takes no request body.

Response

200

{
  "id": "5f4dcc3b5aa765d61d8327deb882cf99",
  "worktree": "/home/user/projects/my-app",
  "vcs": "git",
  "name": "My Application",
  "icon": {
    "url": "https://cdn.hoody.io/projects/my-app/icon.png",
    "override": "🚀",
    "color": "#FF5733"
  },
  "commands": {
    "start": "npm install && npm run dev"
  },
  "time": {
    "created": 1700000000000,
    "updated": 1705000000000,
    "initialized": 1700000050000
  },
  "branches": [
    {
      "id": "branch_01",
      "path": "/home/user/projects/my-app/.worktrees/feature-x",
      "branch": "feature-x",
      "name": "Feature X",
      "status": "ready",
      "base_branch": "main",
      "base_commit": "abc123",
      "created_at": 1700000000000,
      "updated_at": 1705000000000
    }
  ]
}

SDK usage

const project = await client.agent.project.getCurrent({
  workspaceID: "5f4dcc3b5aa765d61d8327deb882cf99"
});

---

Update project

PATCH /api/v1/workspaces/{workspaceID}/project/{projectID}

Update project properties such as name, icon, and commands.

Parameters

Name	In	Type	Required	Description
projectID	path	string	Yes	The project identifier.
workspaceID	path	string	Yes	The workspace identifier.

Request Body

Field	Type	Required	Description
name	string	No	Display name for the project.
icon	object	No	Icon configuration for the project.
icon.url	string	No	URL of the project icon.
icon.override	string	No	Text or emoji override displayed in place of the icon.
icon.color	string	No	Color applied to the project icon.
commands	object	No	Command overrides for the project.
commands.start	string	No	Startup script to run when creating a new workspace (worktree).

{
  "name": "My Application (Renamed)",
  "icon": {
    "url": "https://cdn.hoody.io/projects/my-app/icon-v2.png",
    "override": "🛠️",
    "color": "#1E90FF"
  },
  "commands": {
    "start": "pnpm install && pnpm dev"
  }
}

Response

200

{
  "id": "5f4dcc3b5aa765d61d8327deb882cf99",
  "worktree": "/home/user/projects/my-app",
  "vcs": "git",
  "name": "My Application (Renamed)",
  "icon": {
    "url": "https://cdn.hoody.io/projects/my-app/icon-v2.png",
    "override": "🛠️",
    "color": "#1E90FF"
  },
  "commands": {
    "start": "pnpm install && pnpm dev"
  },
  "time": {
    "created": 1700000000000,
    "updated": 1705000000000,
    "initialized": 1700000050000
  },
  "branches": []
}

400

{
  "data": {},
  "errors": [
    {
      "propertyNames": ["name"]
    }
  ],
  "success": false
}

404

{
  "name": "NotFoundError",
  "data": {
    "message": "Project not found"
  }
}

SDK usage

const updated = await client.agent.project.update({
  workspaceID: "5f4dcc3b5aa765d61d8327deb882cf99",
  projectID: "5f4dcc3b5aa765d61d8327deb882cf99",
  data: {
    name: "My Application (Renamed)",
    icon: {
      url: "https://cdn.hoody.io/projects/my-app/icon-v2.png",
      override: "🛠️",
      color: "#1E90FF"
    },
    commands: {
      start: "pnpm install && pnpm dev"
    }
  }
});