kylon workspace thread — kylon workspace help detail
thread — discussion threads in a room
kylon workspace thread mute --root <root_message_id> [--current-user]
kylon workspace thread unmute --root <root_message_id> [--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 <type:id>] [--text <text>] [--files <paths>] [--file-ids <file_id,...>] [--participants <user_ids>] [--mentions <user_ids>] [--activate [<agent_id>]] [--mention-mode forced|routed] [--isolated] [--route] [--scope-room <room_id>]
Open a thread. With --target the thread is anchored to an existing
room object (canonical: app or app_record; also file, message,
workflow (an Automation), 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 <room_id> to do it in another room
you can access.
--target <type:id> (optional): the object the thread is about.
canonical type: app, app_record
also supported: file, message, workflow (Automation), 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 an Automation 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 <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 <paths>: 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 <file_id,...>: 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 <user_ids>: 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 <user_ids>: 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 [<agent_id>]: 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 an Automation. 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:<current_root> 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|<root_message_id> [--agent <agent_id>] [--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|<root_message_id> [--text <text>] [--files <paths>] [--file-ids <file_id,...>] [--mentions <user_ids>] [--route | --activate <agent_id> | --notify-only] [--mention-mode forced|routed]
Post a new message inside an existing thread.
A reply that mentions an agent in that Room (other than the sender)
automatically enters the same smart routing used by a user reply from
the thread composer, whoever wrote it. Plain replies without an 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 <agent_id> 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 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|<root_message_id>
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 <root_message_id>
kylon workspace thread unpin --root <root_message_id>
Pin a thread to the top of its Room for yourself, or unpin it. Pins are personal.
kylon workspace thread rename --root current|<root_message_id> --title <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})`
Optional --activity-label <name_or_title> identifies a known thread, Room, or Connection in execution activity. Use the exact known name/title, without secrets or account details. It is display-only and does not change the target. Omit when unknown; never look up or retry a command just to add a label.
Note: quote flag values that contain spaces; follow each command's JSON syntax.
Workspace commands
thread
Create, fetch, reply to, and manage threads.