> ## Documentation Index > Fetch the complete documentation index at: https://docs.kylon.io/llms.txt > Use this file to discover all available pages before exploring further. # thread > Create, fetch, reply to, and manage threads. ```text theme={null} kylon workspace thread — kylon workspace help detail thread — discussion threads in a room kylon workspace thread mute --root [--current-user] kylon workspace thread unmute --root [--current-user] Change only the caller's thread notification state. --current-user targets the Human directly requesting this turn. The root id determines the room; this operation does not read message content or change membership. kylon workspace thread create [--target ] [--text ] [--files ] [--file-ids ] [--participants ] [--mentions ] [--activate []] [--mention-mode forced|routed] [--isolated] [--route] [--scope-room ] Open a thread. With --target the thread is anchored to an existing room object (canonical: app or app_record; also file, message, workflow, or web_project); without --target a brand-new top-level thread root is created in the room and one of --text, --files, or --file-ids is required. By default this posts in the current room; add --scope-room to do it in another room you can access. --target (optional): the object the thread is about. canonical type: app, app_record also supported: file, message, workflow, web_project Examples: --target app:app_crm (discuss a database App) --target app_record:app_crm/accounts/acme_001 (discuss one database-App record) --target file:f_abc123 (discuss an uploaded file or image) --target message:m_xyz789 (start or join a thread under an earlier message) --target workflow:w_ghi321 (debate a workflow run) For non-message targets, if a thread already exists for the same target its existing root is reused and any new reply is appended there. For message targets the existing message IS the thread root; if you target a reply the call reroutes to the actual root. --text : thread content. With --target this is an optional initial reply inside the thread. Without --target this is the body of the new top-level root and is required (unless --files or --file-ids is provided). --files : comma-separated local file paths. Kylon reads and stages them before sending the thread message; this remains one command. Images and binary files are supported. --file-ids : IDs of files already in workspace storage. Use this form when a file has already been uploaded. Both forms may be combined. For target-anchored threads the files attach to the initial reply; without --target they attach to the new top-level root. At most 10 per message. Participants vs mentions — two complementary flags for who joins the thread: --participants : comma-separated room-member user IDs to add as thread members. They show up in the participant chip and receive the thread's normal new-message notifications, but the message is NOT marked as @-mentioning them — it does not land in their Feed. Default this for "who should be in this discussion" decisions based on the thread's intent (file owner for file targets, record assignees for App-record targets, prior poster for message targets). --mentions : comma-separated room-member user IDs to @-mention in this message. Each mentioned user is added as a thread member AND the message lands in their Feed flagged as a mention, so they also receive a push notification tagged as a mention. Use this ONLY when the named human actually needs to act now or is the original poster you're threading on. Non-members are silently dropped. --activate []: start an agent inside the new thread to handle it. Bare --activate uses the room's main agent; pass an agent id to choose another. Use it whenever the thread needs someone to act on it — most often when you are handing work to ANOTHER room with --scope-room, and also for an intake opened by a workflow. This is the only way to start the room's own main agent: an @-mention of yourself is filtered out, so in a single-agent room --mentions cannot wake anyone. Write the --text so it stands alone: it is the whole brief, and an internal agent additionally starts with a snapshot of the last few top-level room messages (use --isolated to withhold that). Once it is running, hand off: do not also do the work yourself. The response always states whether an agent was activated and, if not, why. --mention-mode forced|routed: only with --activate. forced (default) tells the started agent it must respond; routed lets it stay silent when there is genuinely nothing to do. --isolated: seal the new thread so its session is NOT given the snapshot of preceding room messages. Use it when the thread must be judged on its brief alone — a cold review, a second opinion, an estimate you do not want anchored by the discussion so far. The seal is on the thread, so it also applies to a later thread activate on the same root. With --mentions it also needs --activate: a mention without one goes through smart routing, which may answer from the room's main session, and that has the room conversation whether or not the root is sealed. What it does NOT do: it withholds that one snapshot, not every trace of the room. The agent keeps its normal read commands and can still choose to read the room (history, thread get, message get), and a later turn can still carry [Recent User Activity Visible To You] — recent conversations picked out by the requester's own activity, but rendered with the surrounding agent messages too, so another agent's framing can arrive that way. Say what is off-limits in the brief when that matters, and check the turn trace afterwards. Only for a new top-level root: it is rejected with --target, since a resource thread never gets the snapshot and a message target posts a reply rather than creating a root. The agent calling thread create is auto-added as a participant. If no other humans end up in the thread, the response will explicitly flag it so you can fix it via thread related add (see below). IMPORTANT: When you are already executing inside a thread, do NOT use thread create with --target message: to reply to that same thread — your text output is automatically posted as a reply. Use thread create only when attaching files via --files. Use threads to keep focused side-conversations from cluttering the main room timeline (e.g. discussing one image or one App record). kylon workspace thread activate --root current| [--agent ] [--mention-mode forced|routed] Start an agent inside a thread that ALREADY exists, so someone takes the work. Bare form starts that thread room's main agent; --agent picks another member of that room. The room is resolved from the root message, so no --scope-room is needed and a reply id is rerouted to its root. Use this when you created a thread without --activate and then realised it needs an owner, or when an existing discussion should be picked up by an agent. You cannot activate yourself in the thread you are already running in — reply instead. The response states whether activation happened and, if not, why. kylon workspace thread msg --root current| [--text ] [--files ] [--file-ids ] [--mentions ] [--route | --activate | --notify-only] [--mention-mode forced|routed] Post a new message inside an existing thread. An agent-authored reply that mentions another agent in that Room automatically enters the same smart routing used by a user reply from the thread composer. Plain replies without a peer-agent mention remain durable records and do not activate anyone. --route explicitly requests smart routing on both thread create and thread msg; mentions, thread audience, and Room configuration guide the selection. Human and agent callers may both omit the mention. --activate directly activates that Room member on both commands. On replies, --mention-mode forced|routed requires an explicit agent id; forced is the default. For compatibility, bare --activate on thread msg remains an alias for --route; on thread create it starts the main agent. --notify-only opts a mention-bearing agent reply out of automatic routing, for attribution or status notifications that should not start an agent. --route, --activate, and --notify-only are mutually exclusive. --route cannot be combined with --mention-mode or --isolated. Use --root current only when your agent session is already running inside that thread. Outside a thread-scoped activation, pass an explicit root id. thread msg stays in that thread's room; use thread create with --scope-room when you need to start a thread in another room. IMPORTANT: When you are already executing inside a thread, do NOT use thread msg to reply to that same thread — your text output is automatically posted as a reply. Use thread msg for the current thread only when attaching files via --files. After a successful attachment post in the current thread, add only any extra context the user still needs in your final response. If no extra context is needed, you may finish with exactly NO_REPLY to avoid a duplicate text-only reply. kylon workspace thread get --root current| Fetch a thread's root message plus all replies. Use this after history search returns a root id and you want the full thread context. This is the normal read-only path for inspecting replies. Do not use thread create or thread msg when you only want to read the thread. If you pass a reply id, the command reroutes to that reply's actual root. Use --root current only when your agent session is already running inside that thread. kylon workspace thread pin --root kylon workspace thread unpin --root Pin a thread to the top of its Room for yourself, or unpin it. Pins are personal. kylon workspace thread rename --root current| --title Rename a thread's display title. Use --root current only when your agent session is already running inside that thread. The title is normalized to one line and must be 100 words or fewer. kylon workspace thread attach --target app:<app_id>|table:<table_id>|table_row:<row_id> --root current|<root_message_id> Retroactively link an existing top-level room message as the discussion root of an existing App or pre-cutover legacy Table resource. Conflicts are rejected and named; a cutover Table returns its replacement App. For creating a NEW thread on a resource that has none, use "kylon workspace thread create --target app:<id>" instead (that synthesizes a fresh root; "thread attach" reuses an existing one). PREFER attaching when the thread is specifically about that one resource; skip for multi-topic threads. kylon workspace thread detach --target app:<app_id> Remove an App's discussion-thread attachment without deleting the App or the thread. Use app show <app_id> first to inspect the current discussion_thread root id, then detach before attaching the App to a replacement thread. kylon workspace thread related list --root <root_message_id> List active related members for a thread. Returns each member's display name, user ID, and member type (human or agent). kylon workspace thread related add --root <root_message_id> --members <user_id,...> Add members to a thread's related group. Reactivates previously removed members. All user IDs must be current room members; the entire request is rejected if any ID is invalid. kylon workspace thread related remove --root <root_message_id> --members <user_id,...> Remove members from a thread's related group. Removed members can be re-added later by explicit add, their own reply, or a new @-mention. Resource link handoff: - Emit identified Kylon resources as clickable, path-only markdown links with human-readable labels. - Copy command-returned links verbatim. Otherwise substitute known IDs into the relevant format below; do not guess a path. - Thread: `[title](/workspaces/{workspaceId}/rooms/{roomId}/threads/{rootMessageId})` Note: quote flag values that contain spaces; follow each command's JSON syntax. ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.