> Source: Onevium official documentation > Article: Organize multi-session work with Teams > Original URL: https://onevium.com/docs/teams > Language: English > Updated: 2026-09-09 > Applies to: 1.1.23+ --- # Organize multi-session work with Teams Start with an @Team proposal, verify the Skill and session tools, create bounded member conversations, and inspect cockpit progress and reports. ## When a Team is useful A **Team** has one lead conversation and real member conversations. The lead divides the work and maintains a common contract; members execute independently and report back. You can open a member's conversation to inspect or continue its work. | Approach | Best fit | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | An ordinary subagent / Agent tool | Short parallel investigation or review within the current turn, returning to the parent conversation | | Onevium Team | Separate, clearly bounded tasks needing independent conversations over time | | Team / bot grouping in Channels | Organizing Feishu, DingTalk, or other platform bots in a channel workspace; see [Channels](https://onevium.com/docs/team-channels) | | Claude CLI Agent Teams | An upstream experimental runtime feature, distinct from this Onevium session team | ## Check the entry, Skill, and tools In an ordinary project conversation, type **@** and choose **Team** under extensions. The entry describes assembling collaborating sessions for a shared task. Selecting the tag still requires you to add a request and send it. | Requirement | How to check | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Team entry | Confirm Team appears in the @ menu | | `team` Skill | Inspect its source and project/user scope in Skills, then confirm this conversation can actually load `team` | | Sessions tool group | **Settings → Tools → Sessions**; it is enabled by default but your saved setting takes precedence. After enabling it, send the next message and check that its tools are available | | Model and project | Verify ordinary chat and required file tools; choose a small project and identify existing changes and allowed writes | The @Team entry does not prove that the `team` Skill is installed. Existing user, project, or plugin configuration may supply it. If missing, inspect installed [Skills](https://onevium.com/docs/skills) and [plugins](https://onevium.com/docs/plugins), then obtain matching official content from a verified source or your team administrator before continuing. If you cannot establish a matching source, continue with ordinary Agents before starting a Team. **Claude CLI → Agent Teams is not the master switch for this workflow.** That setting controls upstream experimental functionality. The session creation, communication, and reporting used here belong to Onevium's Sessions tool group. Enabling the CLI flag cannot supply a missing Skill or missing session tools. ## First task: two members prepare demo documentation Select @Team, then send a bounded request: ```text First confirm that this conversation can load the team Skill and use child-session creation and team-reporting tools. Create a two-member team to prepare documentation from the existing README: Member 1 writes only team-demo/quickstart.md, using documented startup steps. Member 2 writes only team-demo/faq.md, covering missing prerequisites and questions. Both may read README, but neither may edit it or the other member's file. If a command is unsupported by the source, write "not documented" instead of guessing. You may create the team plan, briefs, and reports. Do not install dependencies, commit, push, or deploy. Present ownership, shared format, acceptance checks, models, and usage estimate first. Wait for my confirmation before starting members. If either demo file already exists, report it instead of overwriting it. ``` The current Team protocol presents a proposal before starting. Review concrete members, owned files, deliverables, and the estimate. If the proposal fits, reply: ```text Start with that plan. Create and start the two real child sessions sequentially. Keep the agreed file ownership. Report diffs and acceptance results when finished. ``` The lead records the plan and briefs before creating members one at a time. Session creation and delivery of the first task are separate results. If initial delivery fails, investigate that delivery rather than creating a duplicate member. ## Where the shared task and ownership live The team stores its working contract in `.claude/sdd/team-/`: | File | Purpose | | -------------------- | ------------------------------------------------------------------------------------- | | `team.md` | Lead session, roster, phase, file ownership, shared contract, and acceptance criteria | | `member-N-brief.md` | Member N's complete assignment | | `member-N-report.md` | Expected structured-report location; verify that the file actually exists | Split work by context boundary. Give each file one writer per phase; shared files have one owner while others read them. Separate frontend/backend implementation only when the interface contract is precise and writes do not overlap, rather than dividing one feature by job titles alone. The shared task is managed through the common objective, briefs, and acceptance checklist. The cockpit displays member state; it has no self-assignment controls. File ownership is included in member instructions and lead review; **it is not filesystem isolation**. Inspect the resulting changes. ## How members communicate and report The current protocol routes coordination through the lead. Members report useful information to it, and the lead organizes the next steps; the workflow does not call for unrestricted sibling conversation. Onevium uses session tools such as `send_to_session`. An idle target can start a turn; a busy target receives an attempted steer, falling back to queued delivery when insertion is unavailable. Inspect the actual delivery result and avoid repeated acknowledgement messages. Upstream `SendMessage` does not replace this Onevium cross-session channel. Members should finish with `report_team_result` containing: | Field | Content | | ------------------ | ----------------------------------------------- | | `outcome` | `succeeded`, `failed`, or `needs_input` | | `summary` | Work performed and supporting evidence | | `files_modified` | Actual changed paths | | `unmet_acceptance` | Remaining acceptance criteria | | `followups` | Work the lead should arrange next | | `error` | Optional details for failure or requested input | Reporting attempts to write a file and send a summary. The lead still checks the report, diffs, and unfinished criteria before marking the member `verified`. A tool's “reported” response alone does not prove file persistence, message processing, or acceptance. If a delegated task ends without a structured report, its automatic report can help recover the result. Treat it as reported but unverified until reviewed. ## Read the Team cockpit After members are created, a Team card appears beside creation activity in the lead conversation. It combines real child-session state with `team.md` to show roles, owned files, models, and verification progress. Click an existing member row to open its conversation. Pending or deleted sessions cannot be opened. | Observation | Meaning | | -------------------------------------- | ---------------------------------------------------------------------- | | Member running | Its conversation is executing | | Needs input/permission | Open the member conversation to handle the actual question or approval | | Session idle | The turn ended; lead verification may still be pending | | `reported` | A report exists, but needs review | | `verified` / increasing verified count | The lead recorded a verification verdict in the team manifest | | Error, failed, or deleted | Inspect the report and remaining work; do not count it as a pass | Any displayed cost information comes from the plan's estimate, not live billing. Phase indicators represent phases reached, not proof that future work has executed. ## Open a member and continue the work Open a member from the cockpit or session tree, read tool activity, and provide input as in an ordinary conversation. Tell the lead when you change scope so the brief and actual work remain aligned. A normal user message sent directly to a member does not guarantee an automatic report of that new turn to the lead. Ask for a structured report when needed, or bring the relevant result back to the lead yourself. To continue from the lead conversation: ```text Continue this team without creating duplicate members. Check team.md, the actual child sessions, and member reports first. List verified work, requests for input, and unfinished criteria, then propose the next step. ``` The current protocol summarizes a phase and waits for confirmation before advancing. Closing the lead conversation, a quiet card, or idle members does not establish that all background work has ended. ## Verify completion For the demo, check that both files exist, follow README, and do not include edits to another member's files. Spot-check a report's findings. The lead reviews each diff, records its verdict, and summarizes the overall result. “2/2 verified” describes the team record's verification progress. Actual application testing, commits, and deployment remain separate outcomes supported by their own records. Keep reports and unfinished items after completion or termination. ## Current boundaries - One parent session supports at most **eight non-deleted child sessions**, with one level of hierarchy. Multiple teams under that parent share the limit. - New members default to the creator's model, provider, permission profile, and effort. An explicit model and equal/lower permission can be selected; higher permission is rejected. Creation does not automatically choose a cheaper model. - The current `team` Skill organizes work around small rosters, at most three phases, and lead-centered coordination. This workflow agreement is distinct from the parent-session quota and does not provide filesystem isolation. - Each real member runs model work, and cross-session messages can start more turns. Usage depends on member count, models, and turns; ordinary Agents are usually a better fit for short tasks. - Start in an ordinary desktop project conversation and keep the app running. Use the demo to check actual member conversations, files, and reports before expanding to business work. ## Troubleshoot a team | Symptom | Next action | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Team is visible but its Skill is missing | Check current project/user sources and scope; obtain the matching content before starting | | Creation/report tool unavailable | Check Sessions and start a new conversation; changing the CLI Agent Teams flag alone is insufficient | | Member created but not running | Inspect initial-message delivery and the member conversation; do not duplicate it | | Member idle but verified count unchanged | Have the lead check its report, diff, and manifest verdict | | Missing member or persistent pending row | Check the actual child session and its manifest association; correct the existing record first | | Need to end the whole task | Stop further dispatch through the lead and inspect each active member's stop state; the cockpit has no stop-all button | ## Next steps Choose a workflow with the [extension overview](https://onevium.com/docs/skills-and-agents), learn ordinary [Agents](https://onevium.com/docs/agents), or verify [Skills](https://onevium.com/docs/skills) installation and loading first.