Developers

Working with the agent

How the agent behaves in a conversation, what it can read, the code it runs and the table rows it writes.

Conversation behaviors#

The agent understands natural language and can perform actions like searching the web, working with files, managing data and interacting with external services.

Key behaviors:

  • Responses stream in real time as the agent works
  • A message typed while a response streams is queued rather than lost. Queued messages show above the composer under a "Queued" caption and send together as one follow-up once the response finishes. A / command queues the same way and runs on its own when its turn comes
  • On Slack, a thread reply sent while the previous answer is still streaming waits instead of interrupting it, since Slack has no composer to hold it in. It runs once that answer finishes, merged with anything else sent in the meantime into one follow-up reply
  • Escape, or the Stop button, ends the response and returns anything queued to the composer. An errored response, or one that ends by asking a question, does the same and sends nothing
  • When a reply on the web ends by asking you something, such as a question or a choice, a fast model reads that final reply and puts the chat under waiting on you, marked with an amber dot in the sidebar and on the Chats page, until you send your next message there. A form or confirm card counts as waiting on its own. Slack has no such list, so a Slack reply is never labelled
  • The agent automatically uses the right tools based on your request
  • Long conversations are summarized to keep things fast while preserving important information. The earlier messages stay in the transcript - an "Earlier messages summarized" divider marks where the model's view was cut, and a spinner row shows while a compaction is running
  • The agent can search your past conversations to find relevant history, including the channels and direct messages you can read, and names the channel each match came from. Ask it about one channel by name to search that channel alone

Where a scheduled task's messages land#

A scheduled task speaks to its owner only when its instructions call for a message. On the web, all a run says that way arrives once the run ends, as one message from Ghostlyn in the task's own channel, which sits as one row in Chats titled with the task's name. The run's whole chat becomes that message's thread, so replying there continues the same run with its context and its projects, billed to the owner like any personal chat. Each run starts fresh in a new thread, so a long-running task never carries earlier runs into the next one. A push and an email follow each run unless the channel is muted. In Slack the message arrives as a direct message instead, and a reply in its thread continues the run the same way. A run with no task behind it, such as one a webhook starts, still opens a chat of its own for each message.

Background tasks#

Asking for long work in the background, such as research across several sites, starts a task that runs on its own while the conversation carries on. The tool call's card reads the task name followed by "background" and links to its page under Tasks. That page says "Waiting to start", then "Starting", then streams the run as it works.

The agent picks the result up and replies in the same chat once the task finishes, on the web and in Slack, with no need to ask what it found. A canceled task, or one that finishes while a card in that chat waits for an answer, is reported the next time the person writes there or answers the card. The agent offers another pass on the result rather than starting one itself.

Only one task runs at a time per person. A background task asked for while another task of theirs is running waits for that one to finish first. A background task cannot ask questions, start another background task or send a notification. Canceling it from its page reports it as canceled in the chat.

A background task sees nothing of the conversation, only the instructions it was handed. It gets the projects switched on in the chat that started it, or only the ones a skill names when it starts the task, so a skill can hand a check to a task that holds a single project. It can read files, so a skill passes a file's path rather than its text.

Reviewed writes#

When an organization's Tool approval is Review writes, a write that would otherwise show a confirm card goes to a fast model first. It sees what the member asked for in that chat, or for a scheduled task its instructions and the descriptions of its active skills, along with the calls made earlier in the turn and the pending call. It never sees the agent's own replies or what a tool returned, so text inside an email or a web page cannot talk it into anything.

A write that was asked for, or is a routine step toward it, runs with no card. A write nobody asked for, or one that reaches further, such as deleting, sharing outside the organization, changing access, writing many records at once or moving money, is held. In a chat a held write shows the usual confirm card with the review's reason as its first line. In a scheduled task it stops the run and tells the owner the reason. When the reviewer cannot be reached, the write falls back to the card in a chat and stops a scheduled run.

Sends are never reviewed, so under Review writes they go to a person. A webhook task, a background task the agent started and a request from an outside agent are not reviewed either, and stop at their first write as under Ask before writes. A tool set to Needs approval on its Tools page always goes to a person.

Reading images#

The agent can look at a jpeg, png, gif or webp file it reads out of a project, skill or app or one pasted into the chat, as long as the chat is running a model with vision. It sees the actual image and can answer questions about what it shows.

A model without vision, or a binary file outside those four types such as an svg, a font or an archive, gets a description instead: the file's path, its type and its size, plus the caption already stored for a pasted image when one is ready.

Running code#

The agent runs JavaScript and TypeScript in a sandbox through the run tool. Code arrives one of two ways. Inline code handles one-off work. A stored scripts/NAME.ts file in a project, skill or app is called by path.

Sandboxed code is not limited to computing on its own data. It reaches the agent's own tools through a tools global. One script can read files, search the web and plot a chart in one call. Tools of a loaded skill, app or connector appear there under <slug>__<tool>, with slug hyphens written as underscores. This is the pattern other vendors call code mode.

Some tools stay out of the sandbox by design:

  • MCP connector tools, which would otherwise reach a third-party server under the user's OAuth credentials
  • Tools an author marked as model-emitted, typically an outward-facing write like sending a message
  • The interactive tools ask and form, since a script returns one value and cannot wait on a dialog

The table tools query, save and remove reach a stored script's own bundle's tables. Inline code has no owner, so it names the bundle as the agent does and reaches the tables active in the chat, with the same access the member has. One save takes an array of up to 500 records and saves all of them or, when a row fails its check, none, naming the failing rows. That is how the agent imports a large file into a table: a script reads the file, up to 2 MB, and saves its rows in a few calls rather than the agent retyping them.

The sandbox supports a handful of Node built-ins for pure computation - buffers, text encoding, paths, URLs - but no npm packages and no direct network or filesystem access. Everything outward goes through the bridged tools.

Downloading and uploading files#

The agent downloads a file with curl and saves it into a volume in the same call, such as an image into home:photo.jpg. A PDF or Office file saved this way keeps its extracted text, so the agent can read it afterwards. The reply says what was saved, its size and its type, so a login page saved under an image name shows for what it is. Only a successful response is saved.

To upload, the agent points curl at a stored file or a chat attachment and sends it as the request body. It works only as the first outside call of a turn. Once the turn has read a web page or any other outside content, the upload is refused, and asking again in a fresh message works. A multi-step transfer, such as download then upload, belongs in a script, which has no such limit.

A script moves binary files too. Its fetch sends and receives bytes, up to 2 MB inside the sandbox, and a larger download goes through saveTo, up to 5 MB.

Deleting table records by a condition#

The agent's remove tool deletes either named rows or every row matching a condition, such as every topic whose status is done. It takes one form or the other, never both. The condition is required on that path and each clause names a field the table declares and one of the operators ==, !=, >, >=, < and <=. Anything else is refused before a row is touched, so a mistyped condition never deletes the whole table. There is no cap on how many rows one call removes, since every delete is recoverable.

Deleted table records#

When the agent's remove tool deletes rows from a table, they move to a recoverable trash rather than disappearing outright. A row stays there for 30 days before it is permanently purged. Click Revert on the tool call in the chat to bring the rows back within that window. A revert past the window, or of a call already reverted, fails with a message under the tool call instead of silently doing nothing.

Web channels#

Members of an organization talk to each other in channels on the web, from Channels in the sidebar. A message that mentions @Ghostlyn always gets an answer. A mention at the top level starts a thread under that message where it replies, and mentioning it in a thread people started brings it in with the earlier replies quoted, so it sees the question.

Without a mention the agent decides for itself. It reads a reply in a thread it already answered in, and a top-level message in a channel where it posted in the last 10 days, and answers only when someone states a need it can meet, briefly and in a thread. Thanks, chatter, announcements and a question for a named colleague get no answer. A channel manager turns this off with Respond automatically in the channel's … menu, after which only a mention gets an answer. Slack channels still answer only a mention.

The agent there runs as the organization's shared agent. It reaches built-in skills and the projects linked to the channel, never a member's own chats, files or connections. It knows whether the channel is private and what its description says, and it can look up who is in a channel, who manages it and which projects it links. A channel keeps no memory of its own, so a channel that wants the agent to keep notes links a project it can change, and the team reads and corrects those notes on that project's page. Each turn counts against the monthly limit of the person whose message it answers.

Slack integration#

Ghostlyn also works inside Slack. If your organization has set it up you can chat with the agent via direct messages in Slack. The agent supports threads for multi-turn conversations.

In a public channel, invite Ghostlyn with /invite @Ghostlyn, then mention it to start a thread at your message. It replies only to a message that mentions it, in a thread it joined too, and /remove @Ghostlyn takes it out of the channel. Mentioning it inside a thread quotes the messages since its own last reply there, or the whole thread when it never replied, so it sees the question. Private channels and channels shared with another workspace do not work. Each person's turn counts against their own monthly limit, and a person without a Ghostlyn seat is asked to get an invitation. The agent in a channel uses only the projects an organization admin attached to it on the Integrations page.

Being in a Slack workspace that installed Ghostlyn is not membership. An admin invites the email address from the organization's Members page, and only then does the first Slack message or Sign in with Slack create an account. The invitation also decides whether that member is an admin, so running the Slack workspace grants nothing in Ghostlyn. The person who installs the app into a Slack workspace with no members yet is the exception and becomes its first admin.

Everything works the same across Slack and the web - projects, skills, apps, connectors, data and scheduled tasks are all accessible from both places.

On Slack and CLI, widgets appear as a link after the reply. The link opens in a browser and requires sign-in. Slack users should choose Sign in with Slack.

A public shared chat page shows a widget's result, such as a chart a tool call drew, but allows no interaction that writes and offers no fullscreen view.