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.
Start a session
Section titled “Start a session”odette # start an agent in the current projectodette --prompt "fix the failing test" # start with a first promptodette -- --model opus # pass anything after -- to claudeodette --quiet # print only warnings and errorsodette --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.
Run agents in parallel
Section titled “Run agents in parallel”Several agents can work on one project at once. Give each its own git worktree so they don’t overwrite each other’s files:
odette -w # worktree named after the sessionodette --worktree=feature # worktree with a name you chooseThe 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 — exitNo answer within 30 seconds cancels the launch.
See and stop sessions
Section titled “See and stop sessions”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.
Continue a conversation
Section titled “Continue a conversation”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:
odette -- --continue # the most recent conversation in this projectodette -- --resume # pick one from a listodette -- --resume <session-uuid> # a specific oneA session under another profile (--profile) has a different home and does
not see them.
Give an agent extra folders
Section titled “Give an agent extra folders”odette --mount-ro ~/data/fixtures --mount-rw ~/scratchEach 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.
Open a dev server in your browser
Section titled “Open a dev server in your browser”odette shell --publish 4321 # http://127.0.0.1:4321 on your Macodette --publish 8080:4321 # host port 8080 -> container port 4321odette 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.
Use several Claude accounts (profiles)
Section titled “Use several Claude accounts (profiles)”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.
odette login --profile work # sign a new profile inodette profiles # list profiles with sign-in state and token expiryodette --profile work # start one session under itodette logout --profile work # forget its credentialsodette profiles rm work # list what goes, ask, then delete it with its keys and Claude homesNo 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. |
Per-profile Claude sign-in folder
Section titled “Per-profile Claude sign-in folder”odette login --profile work --claude-home ~/.claude-workodette 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.
Service API keys (Gemini)
Section titled “Service API keys (Gemini)”odette profiles key set gemini --profile work # paste the key at the prompt (hidden), or pipe it inodette profiles key list --profile work # which services have a keyodette profiles key rm gemini --profile work # forget itSessions 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.
Google Workspace
Section titled “Google Workspace”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.
The Claude home
Section titled “The Claude home”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:
resetdeletes 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:
rmdeletes 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 --orphansdeletes homes whose project folder is gone,prune --older-than 30dthose 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:
orphanedmeans the project folder is gone. A launch prints how many there are and how much space they use.incompatiblemeans the home was made by an odette whose home layout differs. A launch in that project stops and prints theodette sessions home resetcommand to run.
Keep Claude Code current
Section titled “Keep Claude Code current”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.