# Agent: Project

**Page:** api/agent/project

[Download Raw Markdown](./api/agent/project.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## 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



```json
{
  "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

```ts
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). |

```json
{
  "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



```json
{
  "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": []
}
```


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


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



### SDK usage

```ts
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"
    }
  }
});
```