---
title: Subteams in Venom Tasks
description: Nest teams under a parent team, see a parent's work with its subteams' issues, choose what a subteam takes from its parent, and change a team's settings from the sidebar's team menu.
section: cloud
order: 83
audience: [user, operator, agent]
sources: [services/nodejs-cloud/lib/tasks/org-teams.ts, services/nodejs-cloud/lib/org/teams.ts, services/nodejs-cloud/components/tasks/team-menu.ts, services/nodejs-cloud/components/tasks/TeamMenu.tsx, services/nodejs-cloud/components/tasks/team-tree.ts, services/nodejs-cloud/migrations/0312_org_teams_subteams.sql]
features: [cloud.page-tasks, cloud.tasks]
---

A team in Venom Tasks can sit under another team. **Engineering** can hold **Mobile**, and **Mobile** can hold
**iOS**. Teams are the organisation's ([Teams, subteams and roles](/docs/cloud/teams)), so the tree is the same in
every product.

## Make and move subteams {#manage}

- **New subteam:** open a team's menu in the sidebar (the **…** button) and pick **New subteam…**, or use **New
  subteam** in the team's settings under **Parent and subteams**. The team's admins and org owners and admins can.
- **Move a team:** **Move under another team…** in the menu, or **Parent team** under **Parent and subteams**. Pick
  **No parent (top level)** to make it a top-level team again. You need to manage the team and the new parent; moving
  to the top needs an org owner or admin.
- **Limits:** teams nest up to 8 levels (a top-level team is level 1). A team can't move under itself or one of its
  own subteams. Both rules are checked by the database, so no client or API can break them.
- **Archive:** a team that still has subteams that aren't archived can't be archived. Archive or move the subteams
  first. A subteam of an archived team can't be brought back until its parent is.
- **Delete:** a Tasks team with subteams can't be deleted (move them first). If an org team is deleted outright, its
  subteams move up to its parent. Subteams are never deleted with their parent.

Issue identifiers keep their own team's prefix. Moving **iOS** under **Engineering** doesn't renumber `IOS-12`.

## What a parent team shows {#lists}

A parent team's **Issues**, **Active** and **Backlog** lists and boards include the issues of its subteams, to any
depth. Turn **Include subteams** off under **Display** (`Shift+V`) to see the team's own issues only; a saved view
keeps that choice. **Triage** and the **current cycle** are always the team's own.

To see which subteam an issue belongs to, group by **Team** (each group is named by its path, such as
`Engineering › Mobile`) or read the issue's prefix. A board that mixes teams with different statuses groups them by
name and type: statuses with the same name and type share a column, and dropping a card there sets that status in the
card's own team.

The same rule holds everywhere a team is named: the issue list API and search (`team=ENG` covers its subteams;
`subteams=0` turns that off), saved views, insights and the MCP tools.

## Who sees what {#access}

- A member of a team is a member of every subteam under it, with the same role (ADR 0077).
- A member of a subteam also sees the teams above it, even private ones.
- A **private** subteam's issues are seen by its members, members of the teams above it, and org owners and admins.
  Everyone else never sees them, in the parent's lists, search, insights or anywhere else. A private subteam stays
  hidden from members of another subteam beside it.

## What a subteam takes from its parent {#inherit}

| Setting | Subteam |
|---|---|
| Estimates | Follows the parent's scale while **Use the parent team's estimates** is on (the default for a new subteam). Picking a scale or changing an estimate switch turns it off. It takes the scale and the extended scale, zero estimates and count unestimated switches. |
| Cycle schedule | Follows the parent's schedule (on or off, length, cooldown, start day) while **Use the parent team's cycle schedule** is on (the default). Each team keeps its own cycles and the issues in them. |
| Labels | A subteam's issues can use the labels of every team above it, as well as its own and the workspace's. Moving an issue between a parent and its subteam keeps those labels. |
| Statuses | The subteam's own. |
| Templates | The subteam's own. |
| Triage and triage rules | The subteam's own. |
| SLAs, recurring issues, automations, GitHub | The subteam's own. |

When the parent's estimates or cycle schedule change, every subteam that follows them changes too, at any depth.

## The team menu in the sidebar {#menu}

Every team in the sidebar has a **…** button. Right-click the team, or focus it and press the menu key or
`Shift+F10`, for the same menu. `F2` on a focused team renames it. You only see what you're allowed to do.

| Item | What it does |
|---|---|
| Quick settings… | Name, key, colour, icon and parent team in a dialog, with a link to all settings |
| Team settings, Go to … | The settings page, or one of its sections: Parent and subteams, Workflow, Triage rules (when triage is on), Labels, Estimates, Cycles, Members, SLAs, Recurring issues, Templates, Archive |
| Rename | Edit the name in the sidebar (Enter saves, Esc cancels) |
| Colour and icon… | Quick settings with the colour picked first. An icon (an emoji) replaces the coloured letter |
| Copy link | The team's issues page |
| Add to favorites | Or remove it |
| New subteam… | A new team under this one |
| Move under another team… | Quick settings, to pick the parent |
| Join team, Leave team | Join a team you manage but aren't in, or leave a team you're a member of directly |
| Archive team | After a confirmation; not offered while the team has subteams |

Folding a team hides its links and its subteams. Which teams are folded is saved with your Tasks preferences
(`foldedTeams`), so it's the same in every browser you use.

`g` then `Shift+T` opens the settings of the team you're looking at (an issue's team on its page). It is also in the
command menu (`⌘K`) as **Open team settings**.

## Agents and the API {#agents}

- `tasks_team_list` shows each team's parent and path (`IOS · iOS · sub-team of MOB (Engineering › Mobile › iOS)`).
- `tasks_team_create` takes `parentId` (a team's id or key) to make a subteam. `tasks_team_update` takes `parentId`
  (or `null` for the top), `inheritEstimates` and `inheritCycles`.
- `tasks_issue_search` covers a team's subteams; pass `subteams: false` for the team's own issues.
- Insights have a **Subteam** slice and segment: issues roll up one level below the view's team (its own issues are
  one group, each subteam's another), or to top-level teams when no single team is in view. See
  [Insights](/docs/cloud/tasks-insights).
- REST: `PATCH /tasks/api/teams/{id}` takes `parentId`, `inheritEstimates` and `inheritCycles`; refusals are
  `409 team_cycle`, `409 team_too_deep`, `409 team_has_subteams` and `409 parent_archived`. A team has
  `inheritEstimates`, `inheritCycles` and `direct` (you're a member of the team itself).

## How this differs from Linear {#linear}

This follows Linear's subteams ([linear.app/docs/sub-teams](https://linear.app/docs/sub-teams)) where Venom's model
allows, with these differences:

- **Membership flows down as well as up.** In Linear a subteam's members must be members of the parent. In Venom a
  member of a team is also a member of its subteams (the organisation-wide team model), and a subteam's members can
  see the teams above it. So a parent's members see its private subteams, like Linear's "restricted" subteams.
- **Statuses and templates aren't inherited.** Linear can share a parent's statuses with a subteam. Venom keeps each
  team's statuses, and templates carry a status of their own team, so both stay per team. Boards that mix teams group
  statuses by name and type instead.
- **Cycles:** a subteam can follow the parent's schedule, but it keeps its own cycles rather than sharing the
  parent's.
- **Depth:** 8 levels on every plan (Linear allows 5 on Enterprise).
