> ## Documentation Index
> Fetch the complete documentation index at: https://witness.nu/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> Start an agent on a card from the Mac app: the card is its task, its work comes back to the card in your name, and what needs you comes to you.

A session is an agent working on a card, run from [witness for Mac](/docs/mac) with your own Claude Code or Codex and your own logins. Witness never runs an agent of its own. Sessions are in beta.

## The card is the task

Open a card and press **Start a session**. The session is sent the project's prompt for the card's status, so it starts from the card and the project's rules rather than from a briefing you retype. A closed card has no prompt, so there is nothing to start on it. [Prompts →](/docs/concepts/projects#what-else-a-project-holds)

It works on a branch of its own, in its own copy of each repository, so two sessions don't get in each other's way. You can also describe a task on the **Sessions** page without a card.

The first time you start a session in a project, witness asks where its sessions work: **In their own copy**, as above, or **Right in your checkout**, on the branch you have checked out. Your checkout is the project's one repository, or the working folder when your repositories were cloned there. You can change the answer under Settings, in **This Mac**. Sessions in your checkout share your folder, so starting one while another is working asks how to go on: **Start now**, **Start when … is done**, or **Use its own copy**.

A server a session runs in its folder, a dev server for instance, is listed under **Running** beside the conversation, with its address. One running there that the session did not start says so, so you know which copy you are testing.

## Its work comes back to the card

A session writes to the cards through your agent's own sign-in, under the same rules as anything else your agent writes. What it finds, what it changed and where the card stands land on the card, where your whole team reads them. [Whose name goes on a write →](/docs/concepts/access#whose-name-goes-on-a-write)

The session itself runs on your Mac. Your team sees what it writes to the card; its conversation, its questions and any changes not yet pushed stay with you.

## What waits on you

Each session is in one of these states:

| | |
| - | - |
| **Waiting for you** | It asked something, or wants permission to use a tool or run a command. |
| **Ready for review** | Its turn ended, with an answer or a failure, and you haven't opened it since. |
| **Working** | It is working. You can still send it a message. |
| **Idle** | Nothing runs and nothing waits on you: you saw its last turn, or you stopped it. Write to it and it goes on. |

When a session asks something, finishes or fails while you are elsewhere in the app, a row for it appears in the tray at the foot of the page. You can answer from there or from the Sessions list, without opening the session. For a permission request, press **Review**, and the Mac asks you to allow or deny it.

By default, when the work is done the agent moves the card to **Needs verification**, and a person takes it from there. [Statuses →](/docs/concepts/statuses)

## Archiving

When you are done with a session, archive it: press the archive button in the session, then **Archive?** to confirm. It waits while the session is working on your message. An archived session can't be brought back. Its copies of your repositories are removed straight away if everything in them is committed and pushed. Otherwise they are kept, and removed the first time the app starts after they are.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.