#Your workspace

A Shell session is bound to one workspace — the project or folder you are working in — so every action lands exactly where you intend and nothing reaches outside it.

#Overview

A workspace is the boundary around a Shell session. When you start a session, it is confined to the project or folder you are working in, and everything the session does — every command, every file it touches, every build it runs — stays inside that boundary. The work happens where you mean it to happen, and not anywhere else.

This confinement is what lets you hand a session real freedom without worrying about reach. The same goal that makes the Shell powerful — running commands, building, testing, operating tools — also means a session is doing real work on real things. The workspace keeps that work contained: a session acts within your project and stops at its edge. You get the power of hands-on execution with the safety of a clear, intended scope.

#What a workspace gives you

  • A clear boundary. A session is confined to one workspace, so its actions stay where you put them and do not spill into the rest of your system.
  • Contained work. Commands, builds, tests, and the files a session creates or changes all happen inside the workspace and nowhere else.
  • Safety by scope. Because the session cannot reach outside its workspace, you can give it more freedom for the task at hand without that freedom extending past the project.
  • Intent you can trust. The workspace makes "where" unambiguous. You decide the folder; the session lives there.
  • A pairing with permissions. The workspace controls where a session can act; the permission level controls how much it can do. Together they give you precise control over a session's reach.
Note

The workspace and the "Work in your workspace" permission level are related but not the same thing. The workspace is the boundary every session is confined to. "Work in your workspace" is one of the permission levels, where the session acts freely inside that boundary and nothing outside it. You can run a session at any permission level — the workspace boundary holds at all of them.

#How to use it

  1. Choose the project or folder you want to work in. This becomes the session's workspace — the boundary it is confined to for everything it does.
  2. Start your session there. From the first command on, the session's actions are scoped to that workspace.
  3. Set a permission level that fits the task. Pair the workspace boundary with how much freedom you want: keep yourself in the loop with Look only, Plan first, or Ask before acting; let the work flow with Work in your workspace or Act automatically.
  4. Work inside the boundary. Run your commands, build, and test. Everything you do stays in the workspace, with output streaming back live.
  5. Use one workspace per project. When you move to a different project, start a session in that project's folder so each body of work stays cleanly separated.
Tip

If a task should be kept entirely away from your own files, run the session in a secure, isolated environment instead of locally on your machine. The workspace boundary still applies; you are simply choosing where that boundary sits. See Where commands run.

#Examples

What you ask:

text
Set this folder as the workspace and run the test suite here.

What you see: The session opens scoped to that folder. The test suite runs inside it, output streaming back live, and the run touches nothing outside the project.

What you ask:

text
Build the project in this workspace and report any errors.

What you see: The session builds inside the workspace, shows you the build output as it runs, and reports the result. Every file it produces or changes stays within the project boundary.

What you ask:

text
Work freely inside this project to wire up the new feature, but stay inside it.

What you see: With the permission level set to work in your workspace, the session carries the task through on its own — inside the project boundary the whole time, and never reaching past it.

#Tips

  • Pick the workspace deliberately at the start. The folder you choose is the boundary for everything that follows, so set it to exactly the project you mean.
  • One workspace per project. Keeping each project in its own session keeps bodies of work cleanly separated and easy to return to.
  • Lean on the boundary when granting freedom. Because a session cannot reach outside its workspace, you can comfortably raise the permission level for long, well-understood tasks within that project.
  • Match the boundary to the risk. For work you want kept off your own system entirely, place the workspace in a secure, isolated environment rather than locally.