Sessions

A session is the unit of work in Chronos: an isolated space where an agent does one job and you review the result. This page covers the full lifecycle.

Creating a session

From the dashboard, type an instruction in the composer and press Enter. From the command line:

chronos session new "implement the password reset flow"
chronos session new --agent <name> "port the parser to the new API"
chronos session new --from-branch release/2.0 "backport the fix"

Each new session starts on its own branch, taken from your workspace’s base branch. The agent works only within that session — it cannot see your other sessions or your main working copy.

Watching it work

chronos session list           # all sessions and their status
chronos session attach <id>    # follow the agent's progress live

In the dashboard, selecting a session shows its full history followed by live progress.

Status

A session moves through a simple lifecycle — created, working, idle, and finally merged or discarded — shown as a colored dot. Sessions are saved, so you can close Chronos and pick up exactly where you left off.

Queuing more work

Send follow-up instructions; they are worked in order:

chronos session send <id> "now add tests for that"
chronos session send <id> "and update the changelog"

Working in parallel

Run as many sessions as you like — each one is isolated. Chronos manages how many agents run at once so your machine stays responsive; you simply create the sessions you need.

Inspecting a session

chronos session files   <id>   # all files in the session
chronos session changes <id>   # what changed (+/− per file) vs base
chronos session diff    <id>   # the full diff against base

See Reviewing changes for the review workflow.

Closing a session

chronos session rm <id>        # clean up the session and its branch

Closing a session removes its branch and working copy cleanly — nothing is left behind. Merging a session is the other way it ends; see Pull requests, approvals, and merge.

What is guaranteed

• A session never writes to your main branch — only to its own branch.
• Sessions never see each other’s files.
• Stopping a session stops its agent cleanly, with nothing left running.