#How sessions work

A session is the thread that holds a task together — its history, its running state, and its result — so you can follow work from start to finish, step away, and come back to exactly where you were.

#Overview

Everything you do in the Shell happens inside a session. A session is the container for a piece of work: it remembers what you have typed, keeps any running job alive, and holds the result you produced. Rather than a stream of disconnected commands, a session is one continuous thread you can follow from the first request to the finished outcome.

This is the foundation the rest of the Shell builds on. Because a session keeps its own history and running state, you can leave it and return without losing your place, run more than one at a time, and always trust that the work is still there when you come back. Once you understand sessions, the other Shell behaviors — watching output live, running long jobs in the background, durable receipts, waiting, closing, and re-attaching — all follow naturally.

#What a session gives you

  • A continuous history. A session keeps the record of what you asked and what ran, so the whole task reads as one coherent thread instead of isolated commands.
  • Live running state. A session holds whatever is currently running. A command in progress belongs to the session and keeps going as part of it.
  • A place that persists. You can leave a session and come back to it; its history and result are still there when you return.
  • Independence. You can have a session working on one thing while you do something else entirely, including starting other sessions.
  • A durable receipt. Every session keeps a durable record of what it did, so even if the window closes or your machine restarts, the history and result are not lost.
  • A chosen permission level. Each session runs at a permission level you set — Look only, Plan first, Ask before acting, Work in your workspace, or Act automatically — and you can change it at any time.
  • A workspace boundary. A session is confined to the project or folder you are working in, so its actions stay where you intend them.

#How to use it

  1. Open a session in the Shell. You start working inside a session as soon as you begin; this is where your history and running state will live.
  2. Set how the session should behave. Choose a permission level that fits the work — start cautious when you are exploring, give more freedom for long, well-understood tasks. Choose where the work runs: locally on your own machine, or in a secure, isolated environment kept separate from your system.
  3. Work the task through. Type requests or ordinary commands. The output streams back live, and each step joins the session's history so the task stays coherent from start to finish.
  4. Leave and come back freely. If you step away or move to something else, the session keeps its history and any running job. When you return, you pick up exactly where you were.
  5. Run more than one at a time. Start another session for a separate task and let both proceed independently — one can be working while you do other things.
  6. Review the session as you go. Use the built-in session commands to manage the session itself — for example, list the available commands, show recent context, or condense a long history so it stays manageable.
  7. Finish cleanly. When the task is done, close the session for a clean stop. Its durable receipt of what happened remains available afterward.
Note

Stopping always works immediately, whatever permission level a session is running at. You are never locked into a task in progress.

#Managing a session from inside it

A session understands a small set of built-in commands for managing itself while you work. The common ones:

text
help      list the available session commands
context   show recent context from the session
cost      show what the current session has used
compact   condense the session's history so a long session stays manageable
kill      stop the command that is currently running
close     end the current session cleanly
exit      leave the Shell

Use context to see what the session has been doing, compact to keep a long session manageable, and close when the work is finished. These manage the session itself and are always available while you work.

#Examples

What you ask:

text
Run the test suite for this project and let me know how it goes.

What you see: The session begins running the tests, and the output streams in live, line by line. The run becomes part of the session's history. You can move to another task while it continues, and the session is still there — with its result — when you come back.

What you ask:

text
Start a second piece of work here while the first one keeps going.

What you see: A separate session begins, independent of the first. Both proceed on their own — one can be working while the other waits or runs — and each keeps its own history, running state, and result.

What you ask:

text
context 40

What you see: The session shows you the recent forty lines of what it has been doing, so you can review the last few steps of the task without scrolling back through everything.

#Tips

  • Treat one session as one task. Keeping a session focused on a single piece of work makes its history easy to follow and its result easy to find later.
  • Lean on independence. When something will take a while, let its session run and start a fresh session for the next thing rather than waiting on the first.
  • Condense long sessions. Use compact to keep a long-running session manageable without losing the thread of the task.
  • Set the level before you start. Choosing the right permission level and run location up front keeps a session behaving the way you expect for the whole task.