Skip to main content

How Sensei works

Every change in Sensei happens in a chat session. A session gets its own branch, sandbox and Preview. You talk to the agent in turns, try the result, and end the session with a pull request that you merge on GitHub.

Project (a GitHub repository)
 |
 |-- Deploy ............ main sandbox
 |
 '-- Chat session
      |-- branch ....... its own, cut from the start branch
      |-- sandbox ...... its own copy of your running app
      |-- Preview ...... your app as this branch runs it
      '-- turns ........ your message, the agent's work, its reply
           |
           v
      Open PR --> pull request on GitHub --> merge --> Completed

The project and its deploy​

A project is a GitHub repository your workspace imported. Importing it starts its first deploy, and no session can start before that deploy succeeds. You can add sessions to the Backlog meanwhile. A session you ask Sensei to start then starts by itself when the deploy lands. The deploy agent reads the repository and works out the services, commands, ports and environment variables your app needs. It saves that configuration and starts the app in the project's main sandbox. Every session's sandbox starts from the saved configuration. See Deploy your project.

A session and its turns​

Press New Session and describe the change. Starting the session creates its branch from the start branch and gives it a sandbox, so several sessions can run side by side.

Each exchange with the agent is a turn. You send a message, the agent works in the sandbox, and it replies. While it works, you can watch the Preview and read the diff in the Changes tab. A message you send mid-turn waits in Up next and starts the next turn. You can also steer your own waiting message into a turn you started. If the agent needs a decision, it asks and ends the turn. Your answer starts the next one. See Messages, Up next and steering.

In a Collaboration project, the agent commits and pushes its changes at the end of each turn. In a YOLO App project, Sensei runs typecheck and build, then saves the tree as the next Version.

A sandbox costs money while it is awake. It pauses when nobody uses it. Sending a message or pressing Start preview wakes it. See Preview and sandboxes.

Review and the pull request​

When the change is right, press Open PR. The agent commits any pending work, pushes the branch and opens a pull request against the project's Target Branch. The pull request opens ready for review unless you ask for a draft. A ready pull request moves the session to Under Review. Send a message to keep working: the agent turns the pull request back into a draft when it changes it. Press Resume to turn it back into a draft yourself.

With a GitHub Connection, your GitHub account authors the commits and opens the pull request. Without one, the Kosuke App does both. Merge the pull request on GitHub, and the session moves to Completed. See Open a pull request.

Session statuses​

Every session has one of five statuses. On the workspace Tasks page, Backlog reads Todo, Active and Under Review read In progress, Completed reads Done, and Archived stays Archived.

StatusWhat it meansHow a session gets there
BacklogA prompt waiting to start. It has no branch or sandbox yet.New Session with Backlog selected, or Sensei when you ask it to write a Backlog session. Moving a session back to Backlog deletes its work and chat history.
ActiveThe conversation is open and the agent takes messages. A pull request, if there is one, is a draft.Starting a new session, or starting a Backlog session. A message to an Under Review session, or Resume. A pull request turned back into a draft on GitHub.
Under ReviewThe pull request is ready for review. A member's message resumes it, and so does Resume.Open PR, or Ready for review on a draft. A pull request marked ready on GitHub.
CompletedThe work is done. The session has no sandbox and cannot move again.Merging the pull request on GitHub. A Todo task can also be marked done without code work, from its ⋯ menu.
ArchivedSet aside without a merge. Its pull request is closed and its sandbox removed.Archive in the session's menu, or closing the pull request on GitHub. Restore reopens the pull request as a draft and returns the session to Active. A session that never started returns to Backlog.

When you import a repository, its open pull requests arrive as sessions. A draft arrives Active, and a pull request that is ready for review arrives Under Review. See Chat sessions and tasks for the statuses and what moves a session between them.

Whose credentials run what​

Workspace tasks, their Delegated Runs, workspace Deploys and workspace Crons use workspace Credentials only. Assignment and the sender change nothing. Personal tasks, Sensei, personal-project Deploys and Personal Crons with or without repositories use the member's Subscriptions, or Sensei free while they hold none. Free works like a personal Subscription within its allowance and staff maximum Turn Level. Sensei picks one Source for each chat session, Sensei thread Turn, Deploy or Cron run. Delegated Runs use their parent Turn's Source. If a Source reaches its limit, is paused or is removed, Sensei moves the work automatically. Its model, Source and provider stay hidden. AI providers has the full rule.

Next steps​