Skip to content

Sessions

A session is one agent: one container running Claude Code for one project. Each session gets a random name, such as swift-otter, unique on your machine. The container is removed when Claude Code exits. Conversation history and Claude settings live in the project’s Claude home, which every session of the same profile and project shares and which is kept until you delete it.

Terminal window
odette # start an agent in the current project
odette --prompt "fix the failing test" # start with a first prompt
odette -- --model opus # pass anything after -- to claude
odette --quiet # print only warnings and errors
odette --show-checks # explain every startup check (image freshness, Claude Code version)

Prompts go through --prompt. A bare word on the command line is an error; Claude Code’s own flags go after --.

odette shell opens a bash shell in the same kind of sandboxed container, without Claude Code. Use it to look around the environment an agent sees. A claude you start by hand in that shell runs like a launched one: plan mode, permission prompts off, and odette’s host tools available. Plan mode is skipped for claude -p and when you pass your own --permission-mode. odette shell -- make test runs one command in the new container instead of a shell and exits with the command’s own exit status. It needs a terminal, so you cannot pipe into it.

Several agents can work on one project at once. Give each its own git worktree so they don’t overwrite each other’s files:

Terminal window
odette -w # worktree named after the session
odette --worktree=feature # worktree with a name you choose

The name must be attached with =. Worktrees are created by Claude Code under .claude/worktrees/ in the project. If a bare -w finds a worktree of that name already there, the launch stops: remove the old worktree (git worktree remove <path>) or pick a name with --worktree=<name>.

If you start a plain odette while another agent is already working in the shared tree, odette asks:

[w] worktree — launch in a git worktree (isolated branch)
[o] overlap — share the working tree (both agents write the same files)
[c] cancel — exit

No answer within 30 seconds cancels the launch.

odette sessions lists every running session with its project, profile, worktree, pod and role, and whether it is working or idle (the last needs the daemon); odette sessions stop <name> stops one from any folder and keeps its Claude home. odette attach [name] [-- command...] opens a shell, or runs one command, inside a running session’s container, in the project root. Without a name it uses the session running for the current project. The dashboard’s Sessions zone shows the same sessions with more detail (Commands).

Use attach when the command has to share the agent’s container: a dev server that reloads when the agent edits files, started in a session you launched with --publish. Use shell -- command when you want a clean, separate container: check a tool’s version, or run a build or the tests without touching the running session.

Every session of a profile in a project shares one Claude home, so a new session sees the conversations of the earlier ones. Use Claude Code’s own flags:

Terminal window
odette -- --continue # the most recent conversation in this project
odette -- --resume # pick one from a list
odette -- --resume <session-uuid> # a specific one

A session under another profile (--profile) has a different home and does not see them.

Terminal window
odette --mount-ro ~/data/fixtures --mount-rw ~/scratch

Each path appears at the same absolute path inside the container. Both flags can be repeated. To set mounts once per project instead, use odette mount add <path> (Configuration).

A read-write mount lets the agent change or delete those files.

Terminal window
odette shell --publish 4321 # http://127.0.0.1:4321 on your Mac
odette --publish 8080:4321 # host port 8080 -> container port 4321
odette shell --publish 4321 --publish 3000

--publish makes a port in the session reachable from your own machine, and only from your own machine: it listens on 127.0.0.1, never on your network. PORT is the port the server uses inside the container; HOST:PORT picks a different one on your side. Repeat the flag for more ports. Only TCP is supported.

The server must listen on all addresses inside the container, not just its loopback: use astro dev --host 0.0.0.0 --port 4321 (or vite --host, or your tool’s equivalent). A server bound to 127.0.0.1 inside the container cannot be reached.

If the host port is taken, or the value is not a valid port, the launch stops before anything starts; odette never picks another port for you. Running sessions and their ports are listed by odette sessions, and in the dashboard’s session details.

--publish works with both Apple container and Docker.

The session itself cannot open ports: only the person launching it can.

Each Claude account you use is a profile. When no profile exists yet, the first sign-in (odette setup or odette login without --profile) names it default; the name carries no special meaning.

Terminal window
odette login --profile work # sign a new profile in
odette profiles # list profiles with sign-in state and token expiry
odette --profile work # start one session under it
odette logout --profile work # forget its credentials
odette profiles rm work # list what goes, ask, then delete it with its keys and Claude homes

No profile is preferred over another. With one signed-in profile, commands use it. With several, odette asks which on a terminal, and without a terminal fails with several profiles exist (a, b): pass --profile. --profile is accepted by the launch, odette shell, login, logout, profiles key and debug judge.

profiles rm is the exception. It takes the profile as an argument (odette profiles rm work), because the name is what it deletes, not which account a command runs as. It looks for sessions on the container backend you have configured. profiles rm refuses while a session uses one of the profile’s homes. It lists what it will delete and asks first; --yes skips the question, and a run with no terminal needs it.

Each profile has its own Claude home per project, so one profile’s Claude data never reaches another.

Ways to sign in (odette login):

Flag Use when
(none) Normal browser sign-in. On macOS with the claude CLI installed, odette runs its login and imports the result.
--paste No browser on this machine: open the printed URL elsewhere and paste the code back.
--from-claude-cli macOS only: import the account the claude CLI is already signed in to, without a new login.
--token Paste an API key. A pasted OAuth access token expires within hours and cannot be renewed; use a normal sign-in instead.
Terminal window
odette login --profile work --claude-home ~/.claude-work

odette remembers the folder for the profile. On macOS, signing work in then uses that Claude config folder’s own Keychain entry, so it does not sign your default claude CLI out. Sessions do not copy anything else from the folder: MCP servers come from plugins or the project’s .mcp.json.

Terminal window
odette profiles key set gemini --profile work # paste the key at the prompt (hidden), or pipe it in
odette profiles key list --profile work # which services have a key
odette profiles key rm gemini --profile work # forget it

Sessions under that profile can call the Gemini API (generativelanguage.googleapis.com). The key stays on your machine; odette adds it to each request. Inside the session, GEMINI_API_KEY holds a placeholder so Gemini tools start. A session launched before you set the key does not have it; start a new one. If a tool sends its own key instead of the placeholder, odette leaves it alone.

If you use the gws command-line tool on your machine, odette finds its profiles in ~/.config and lets sessions use them. Sessions get the list of profiles, never their credentials. odette adds a real Google access token to each request to googleapis.com. When it finds a profile, odette also allows the gws release downloads on github.com and release-assets.githubusercontent.com for every project so the in-container tooling can download the gws binary. The rest of github.com still asks.

Each profile has one Claude home per project, a folder on your machine at ~/.odette/home/<profile>/<project> (under ODETTE_DATA_DIR if set). <project> is the project folder’s name plus a short hash of its path. It holds what Claude Code keeps for itself: conversations, memory, /config changes, plugins you installed with /plugin install, and sign-ins to third-party MCP servers. Your Claude account’s real credentials are never in it. On macOS, homes are excluded from Time Machine and Spotlight each time a session starts.

The first session in a new home writes a few defaults, once: Claude Code’s onboarding and trust of the project, a .gitconfig with the git name and email you use in that project, and the status line. After that they are yours to change; odette never writes them again, except that the status line’s layout file is written again whenever it is missing.

The status line reads, left to right: project (and worktree), git branch and changes, model, context used, the plan’s 5-hour session limit, its weekly limit, and thinking effort, separated by |. Each limit shows as a whole percentage, for example 12%, or – when your plan has no such limit. Both come from Claude Code itself, and a session on an API key shows neither. The session holds only a placeholder, never your real credentials.

A home seeded by an older odette keeps the status line it was given. To get the current one, stop every session that uses the home, delete .config/ccstatusline/settings.json in it, and start a session; it writes the file again. Delete it while a session is still running and that session’s status line writes ccstatusline’s own default layout in its place, which then stays.

The home is mounted as the session’s home folder, so anything the image puts there is hidden. In .odette/Dockerfile, put shell setup in a file under /etc/profile.d/, or use ENV, never ~/.bashrc.

odette sessions home manages homes, and the dashboard’s Sessions zone does the same under Homes (Commands):

  • Something in a home is broken: reset deletes everything but conversations and memory, in the project’s home of every profile; the defaults are written again at the next launch.
  • A home is no longer wanted: rm deletes it, conversations, settings and MCP sign-ins included, for every profile. If a session uses the home of any profile, nothing is deleted and the error names the sessions to stop.
  • Disk is filling up: prune --orphans deletes homes whose project folder is gone, prune --older-than 30d those unused for a month.
  • You moved or renamed the project folder: mv <old-path> <new-path> keeps its homes.

rm, reset and prune list what they will change and ask before doing it; --yes skips the question, and a run with no terminal needs it.

None of them touches a home a running session uses.

odette never deletes a home on its own. A status of:

  • orphaned means the project folder is gone. A launch prints how many there are and how much space they use.
  • incompatible means the home was made by an odette whose home layout differs. A launch in that project stops and prints the odette sessions home reset command to run.

Claude Code is installed once per machine and shared by every project, so updating it needs no image rebuild. When a newer version is out, a launch installs it without asking; if the install fails, the launch warns and carries on with the current version. Older versions are removed, except the previous one and any a running session still uses. --skip-version-check skips the check. To pin a version, run odette build --claude-code-version <version>; a pinned version is never updated. There is no unpin command: delete ~/.odette/claude/pinned and launches update again.

Claude Code updates the files in a project’s home as it reads them, and an older version may not understand what a newer one wrote. If a launch runs an older Claude Code than one that already opened that project’s home, it warns: claude-code <old> is older than <new>, which already opened this project's home; the home may already have been migrated past <old>. The session still starts. If it misbehaves, run odette sessions home reset for that project, which keeps conversations and memory and clears the record, so the warning stops. A home opened before odette kept this record warns once when the version is pinned, since odette cannot tell what opened it. A pinned version that is not a plain MAJOR.MINOR.PATCH (a pre-release or a tag) is not checked.

Theme