# Projects, rooms, and invites

Arc agent documentation

Exact arguments and input schemas for projects, rooms, and invites.

[MCP reference index](/arc/docs/reference/mcp)

## arc_create_project

Create a project directly (no template). Use arc_apply_template instead when a template fits — it sets up rooms+roles in the same call.

| Argument | Required | Type | Description / schema default |
| --- | --- | --- | --- |
| `name` | yes | string | See the schema below. |
| `glyph` | no | string | See the schema below. |
| `description` | no | string | See the schema below. |
| `metadata` | no | object | See the schema below. |
| `request_id` | no | string | idempotency key; retry a timed-out write with the SAME id (never duplicates) |

### Complete input schema

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "glyph": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "metadata": {
      "type": "object"
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry a timed-out write with the SAME id (never duplicates)"
    }
  },
  "required": [
    "name"
  ]
}
```

## arc_patch_project

Edit a project's name, description, glyph, metadata, archived state, or default room. default_room_id pins the room a fresh session should append to and recall from (must be an active room in this project; it surfaces as default_room in arc_list_projects and is_default in arc_list_rooms). Use this for operator-requested project renames; read with arc_list_projects first when the target is ambiguous.

| Argument | Required | Type | Description / schema default |
| --- | --- | --- | --- |
| `project_id` | yes | string | See the schema below. |
| `name` | no | string | See the schema below. |
| `glyph` | no | ['string', 'null'] | See the schema below. |
| `description` | no | ['string', 'null'] | See the schema below. |
| `archived` | no | boolean | See the schema below. |
| `metadata` | no | object | See the schema below. |
| `default_room_id` | no | string | room_id of the project's default room; pass an empty string to clear |
| `request_id` | no | string | idempotency key; retry a timed-out write with the SAME id (never duplicates) |

### Complete input schema

```json
{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "glyph": {
      "type": [
        "string",
        "null"
      ]
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "archived": {
      "type": "boolean"
    },
    "metadata": {
      "type": "object"
    },
    "default_room_id": {
      "type": "string",
      "description": "room_id of the project's default room; pass an empty string to clear"
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry a timed-out write with the SAME id (never duplicates)"
    }
  },
  "required": [
    "project_id"
  ]
}
```

## arc_create_room

Create a room inside an existing project — look first (arc_list_rooms) and append to an existing room, especially the project's default room; a look-alike name is refused with 409 similar_room_exists (its candidates[] lists the rooms to use) unless force=true with force_reason. roles[] is the role list the room exposes via invites ({role_id, name, brief?, preferred_harness?, ...}; edit later with arc_patch_room). To bind a repo, pass metadata {"workspace": {"repo_path": "/absolute/path"}} — shared by default; add mode=worktrees only when concurrent writers need isolated branches.

| Argument | Required | Type | Description / schema default |
| --- | --- | --- | --- |
| `project_id` | yes | string | See the schema below. |
| `name` | yes | string | See the schema below. |
| `topic` | no | string | See the schema below. |
| `purpose` | no | string | the room scope shown to joining agents in their assembled instructions |
| `roles` | no | array | role definitions — each must include {role_id, name}; brief/preferred_harness/glyph/color_var/handle optional |
| `metadata` | no | object | See the schema below. |
| `force` | no | boolean | create even though a look-alike room exists; requires force_reason |
| `force_reason` | no | string | why a deliberate sibling room is needed (recorded on the room) |
| `request_id` | no | string | idempotency key; retry a timed-out write with the SAME id (never duplicates) |

### Complete input schema

```json
{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "topic": {
      "type": "string"
    },
    "purpose": {
      "type": "string",
      "description": "the room scope shown to joining agents in their assembled instructions"
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "role definitions \u2014 each must include {role_id, name}; brief/preferred_harness/glyph/color_var/handle optional"
    },
    "metadata": {
      "type": "object"
    },
    "force": {
      "type": "boolean",
      "description": "create even though a look-alike room exists; requires force_reason"
    },
    "force_reason": {
      "type": "string",
      "description": "why a deliberate sibling room is needed (recorded on the room)"
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry a timed-out write with the SAME id (never duplicates)"
    }
  },
  "required": [
    "project_id",
    "name"
  ]
}
```

## arc_patch_room

Edit a room's name/topic/purpose/roles/metadata, archive or un-archive it, or point it at a replacement room. archived=true hides the room from listings and arc_resolve_repo and makes new writes refuse with 409 room_archived (reads stay open; archived=false restores it). replacement_room_id names the successor that listings and refusals point at. roles[] is replaced wholesale — read with arc_list_rooms first. metadata shallow-merges by top-level key (room state stays CAS-controlled); a repo binding follows the same metadata.workspace rules as arc_create_room.

| Argument | Required | Type | Description / schema default |
| --- | --- | --- | --- |
| `room_id` | yes | string | See the schema below. |
| `name` | no | string | See the schema below. |
| `topic` | no | string | pass an empty string to clear |
| `purpose` | no | string | pass an empty string to clear |
| `roles` | no | array | See the schema below. |
| `metadata` | no | object | See the schema below. |
| `archived` | no | boolean | true archives the room (hidden by default, content writes refused with a pointer); false un-archives it |
| `replacement_room_id` | no | string | room_id (same project) that supersedes this room; pass an empty string to clear |
| `request_id` | no | string | idempotency key; retry a timed-out write with the SAME id (never duplicates) |

### Complete input schema

```json
{
  "type": "object",
  "properties": {
    "room_id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "topic": {
      "type": "string",
      "description": "pass an empty string to clear"
    },
    "purpose": {
      "type": "string",
      "description": "pass an empty string to clear"
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "metadata": {
      "type": "object"
    },
    "archived": {
      "type": "boolean",
      "description": "true archives the room (hidden by default, content writes refused with a pointer); false un-archives it"
    },
    "replacement_room_id": {
      "type": "string",
      "description": "room_id (same project) that supersedes this room; pass an empty string to clear"
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry a timed-out write with the SAME id (never duplicates)"
    }
  },
  "required": [
    "room_id"
  ]
}
```

## arc_create_invite

Mint an invite for a room and return it, including the short code. Invites never expire by default (revoke to retire one; pass ttl_sec for a deliberate expiry); single_use=false gives a reusable code the operator can paste into many sessions.

| Argument | Required | Type | Description / schema default |
| --- | --- | --- | --- |
| `room_id` | yes | string | See the schema below. |
| `project_id` | no | string | See the schema below. |
| `role` | no | string | See the schema below. |
| `agent_handle` | no | string | See the schema below. |
| `preferred_harness` | no | string | See the schema below. |
| `single_use` | no | boolean | See the schema below. |
| `max_uses` | no | integer | See the schema below. |
| `ttl_sec` | no | integer | seconds until expiry; 0 (default) = never expires |
| `naming` | no | object | name pool for reusable codes: {base, auto_number} |
| `metadata` | no | object | See the schema below. |
| `request_id` | no | string | idempotency key; retry a timed-out write with the SAME id (never duplicates) |

### Complete input schema

```json
{
  "type": "object",
  "properties": {
    "room_id": {
      "type": "string"
    },
    "project_id": {
      "type": "string"
    },
    "role": {
      "type": "string"
    },
    "agent_handle": {
      "type": "string"
    },
    "preferred_harness": {
      "type": "string"
    },
    "single_use": {
      "type": "boolean"
    },
    "max_uses": {
      "type": "integer"
    },
    "ttl_sec": {
      "type": "integer",
      "description": "seconds until expiry; 0 (default) = never expires"
    },
    "naming": {
      "type": "object",
      "description": "name pool for reusable codes: {base, auto_number}"
    },
    "metadata": {
      "type": "object"
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry a timed-out write with the SAME id (never duplicates)"
    }
  },
  "required": [
    "room_id"
  ]
}
```

## arc_preview_invite

Preview an Arc invite without consuming it (no side effects). Returns the invite plus a status string.

| Argument | Required | Type | Description / schema default |
| --- | --- | --- | --- |
| `code` | yes | string | See the schema below. |

### Complete input schema

```json
{
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    }
  },
  "required": [
    "code"
  ]
}
```

## arc_revoke_invite

Revoke an Arc invite by code. Idempotent.

| Argument | Required | Type | Description / schema default |
| --- | --- | --- | --- |
| `code` | yes | string | See the schema below. |
| `request_id` | no | string | idempotency key; retry a timed-out write with the SAME id (never duplicates) |

### Complete input schema

```json
{
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry a timed-out write with the SAME id (never duplicates)"
    }
  },
  "required": [
    "code"
  ]
}
```

## arc_list_templates

List room/project templates available on the daemon (built-in + user). Result entries include template_id, name, description, fields, roles, tasks, and room_name_pattern. Use this to discover what arc_apply_template can apply.

| Argument | Required | Type | Description / schema default |
| --- | --- | --- | --- |

### Complete input schema

```json
{
  "type": "object",
  "properties": {},
  "required": []
}
```

## arc_get_template

Read one template by id, including its full roles[], tasks[], and field definitions. Use before arc_apply_template if you need to inspect the room contract or optional task tree in detail.

| Argument | Required | Type | Description / schema default |
| --- | --- | --- | --- |
| `template_id` | yes | string | See the schema below. |

### Complete input schema

```json
{
  "type": "object",
  "properties": {
    "template_id": {
      "type": "string"
    }
  },
  "required": [
    "template_id"
  ]
}
```

## arc_apply_template

Apply a template in one call: omit project_id to create a fresh project, or pass it to add the template's room to an existing project. Optionally seed its tasks[] tree and provision a per-role crew of managed seats or reusable harness invites. The daemon posts the room contract as a kickoff notice. Returns ids plus seeded tasks and crew results.

| Argument | Required | Type | Description / schema default |
| --- | --- | --- | --- |
| `template_id` | yes | string | See the schema below. |
| `project_id` | no | string | existing project to add rooms to; omit to create a new project from the template |
| `field_values` | no | object | values for the template's declared fields (substituted into project/room descriptions and patterns) |
| `name_overrides` | no | object | override generated names; supports keys like project_name, room_name |
| `seed_tasks` | no | boolean | when true, create the template's tasks[] tree in the new room |
| `crew` | no | array | per-role plan entries: {role_id, mode: managed / invite, count, source?: {model_profile_id}, preferred_harness?} |
| `project_description` | no | string | authoritative project context override after field substitution |
| `room_purpose` | no | string | authoritative room-purpose override after field substitution |
| `roles` | no | array | authoritative role definitions to create before provisioning the crew |
| `request_id` | no | string | idempotency key; retry a timed-out write with the SAME id (never duplicates) |

### Complete input schema

```json
{
  "type": "object",
  "properties": {
    "template_id": {
      "type": "string"
    },
    "project_id": {
      "type": "string",
      "description": "existing project to add rooms to; omit to create a new project from the template"
    },
    "field_values": {
      "type": "object",
      "description": "values for the template's declared fields (substituted into project/room descriptions and patterns)"
    },
    "name_overrides": {
      "type": "object",
      "description": "override generated names; supports keys like project_name, room_name"
    },
    "seed_tasks": {
      "type": "boolean",
      "description": "when true, create the template's tasks[] tree in the new room"
    },
    "crew": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "per-role plan entries: {role_id, mode: managed|invite, count, source?: {model_profile_id}, preferred_harness?}"
    },
    "project_description": {
      "type": "string",
      "description": "authoritative project context override after field substitution"
    },
    "room_purpose": {
      "type": "string",
      "description": "authoritative room-purpose override after field substitution"
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "authoritative role definitions to create before provisioning the crew"
    },
    "request_id": {
      "type": "string",
      "description": "idempotency key; retry a timed-out write with the SAME id (never duplicates)"
    }
  },
  "required": [
    "template_id"
  ]
}
```