session - Manage sessions, branches, history

Manage session branches and history. Sessions track the image state as you run commands, with support for branching and rollback.

Examples

# Show current session
contree session

# List all sessions
contree session list

# Show full history
contree session show

# Create and switch to a branch
contree session branch experiment
contree session checkout experiment

# Switch back
contree session checkout main

# Create a branch from another branch
contree session branch hotfix --from main

# List branches (* marks active)
contree session branch

# Undo last operation
contree session rollback

# Undo last 3 operations (`--` stops argparse from eating `-3` as a flag)
contree session rollback -- -3

# Forward one entry
contree session rollback +1

# Absolute jump to a specific history id (use `session show` first)
contree session rollback 42

# Import image from another session
contree session use other-session

# Delete a session
contree session delete my-old-session
contree session rm my-old-session -y

Help output

$ contree session --help usage: contree session [-h]                        {list,ls,use,branch,br,checkout,co,rollback,rb,show,wait,delete,rm,del} ... Manage session branches and history. Without a subcommand, shows the current session info (key, branch, image, last operation). Subcommands:   list (ls)       List all sessions   use KEY         Import another session's current image   branch (br)     List or create branches (--from to fork)   checkout (co)   Switch active branch   rollback (rb)   Navigate history: N=absolute, -N=back, +N=forward   show            Display the session history DAG positional arguments:   {list,ls,use,branch,br,checkout,co,rollback,rb,show,wait,delete,rm,del}     list (ls)           List all sessions     use                 Import another session's image     branch (br)         List, create, delete, or prune branches     checkout (co)       Switch active branch     rollback (rb)       Navigate history: N=absolute, -N=back, +N=forward     show                Show session history     wait                Drain detached ops in the current session     delete (rm, del)    Delete sessions by key options:   -h, --help            show this help message and exit for coding agents:   session (no subcommand) is read-only   branch/checkout/rollback/session use mutates local session pointers   `session show` defaults to last 20 history entries; pass -a/--all for full DAG   use `session show` to inspect history DAG before destructive navigation   `session wait [OPS...]` waits for active or specified operations agent note:   Before using this command in an automated workflow, read:     contree agent

Concepts

Each non-disposable contree run creates a new history entry and advances the branch pointer. Branches share the underlying history – creating a branch just adds a new pointer at the current position.

Rollback moves the branch pointer backwards. History entries are preserved and can be recovered by creating a new branch.

Subcommands

session list

contree session list (alias ls) prints every session known to the current profile, with the active session marked. The optional --filter flag narrows the list by substring match against the session key, which is handy when you keep many disposable sessions named after features or tickets.

$ contree session list --help usage: contree session list [-h] [--filter FILTER_TEXT] List locally known sessions and their current branch/image. options:   -h, --help            show this help message and exit   --filter FILTER_TEXT  Filter session keys containing this text for coding agents: read-only command

session use

contree session use KEY imports the current image of another session into the active session as a new history entry. The source session is not modified; this is a “fork the snapshot, keep working here” operation, distinct from the top-level contree use which starts or resumes a session against an image reference.

$ contree session use --help usage: contree session use [-h] session_name Set current session image to another session's tip image. Accepts exact key or key suffix. positional arguments:   session_name  Session key or suffix to match options:   -h, --help    show this help message and exit for coding agents: mutates current session history

session branch

contree session branch (alias br) lists branches with * marking the active one. Pass a name to create a new branch pointing at the current history position, or combine with --from BRANCH to fork off a different branch. The -U/--prune flag removes branches that no longer reference live history.

$ contree session branch --help usage: contree session branch [-h] [--from FROM_BRANCH] [-U] [--prune] [branch_name] List branches (no args). Create with NAME (optionally --from). Delete with --delete NAME. Prune disposable-/detached- branches with --prune. positional arguments:   branch_name         Branch name (create/delete target) options:   -h, --help          show this help message and exit   --from FROM_BRANCH  Source branch (default: active branch)   -U, --delete, --rm  Delete the specified branch (NAME required, must not be active)   --prune             Prune disposable-/detached- branches (non-active only) for coding agents: read-only when NAME/--delete/--prune omitted mutating when creating/deleting/pruning

session checkout

contree session checkout BRANCH (alias co) switches the active branch pointer. Working directory, pending files, and the current image are all reset to whatever the target branch currently points at, so it is the safe way to bounce between parallel experiments.

$ contree session checkout --help usage: contree session checkout [-h] checkout_branch Move current session to another existing branch tip. positional arguments:   checkout_branch  Branch to switch to options:   -h, --help       show this help message and exit for coding agents: mutates active branch pointer

session rollback

contree session rollback [TARGET] (alias rb) navigates the history of the current branch. With no argument it steps back one entry; a positive number jumps to that absolute history index, -N steps back N entries, and +N steps forward. History entries are preserved – rollback only moves the branch pointer.

$ contree session rollback --help usage: contree session rollback [-h] [target] Move branch pointer in session history. Supports absolute ID, relative backward (-N), and forward (+N). positional arguments:   target      History target: ID (absolute), -N (back), +N (forward) — use `-- -N` for negative               values options:   -h, --help  show this help message and exit for coding agents: mutates active branch history pointer

session show

contree session show prints the session history DAG with one row per entry, including operation IDs, image UUIDs, branch pointers, and relative timestamps. Use -a to include hidden entries, -k KIND to filter by entry kind (e.g. run, cd), and -l LAST to show only the last N rows.

$ contree session show --help usage: contree session show [-h] [-a] [-k KIND] [-l LAST] [--since SINCE] [--until UNTIL]                             [session_name] Print session history DAG entries and branch labels. By default shows last 20 entries; use -a/--all for full history. positional arguments:   session_name          Session key or suffix (default: current session) options:   -h, --help            show this help message and exit   -a, --all             Show full history (default: last 20 entries)   -k KIND, --kind KIND  Filter history entries by kind (e.g., run, use, cd)   -l LAST, --last LAST  Show last N entries after filtering   --since SINCE         Show entries since. Parse +/- intervals (bare seconds or smhdMy) or                         ISO/date to UTC datetime.   --until UNTIL         Show entries before. Parse +/- intervals (bare seconds or smhdMy) or                         ISO/date to UTC datetime. for coding agents: read-only command

session wait

contree session wait [OP_ID ...] blocks until the specified operations reach a terminal state (SUCCESS, FAILED, or CANCELLED). When no IDs are given it waits for every active operation in the session, which is the canonical way to drain background contree run -d jobs before moving on.

$ contree session wait --help usage: contree session wait [-h] [UUID_OR_REF ...] Drain detached operations in the current session. With no arguments, reads the session's pending- ops cache, polls each to a terminal status, and advances the active branch to each non-disposable result image (recording `disposable-<uuid>` branches for disposable runs). With explicit UUIDs, this command degrades to a plain polling loop: it prints completion rows but does NOT touch the active branch, because the pending metadata is not loaded for explicit UUIDs. positional arguments:   UUID_OR_REF  Operations to wait for (default: all active in this session). Accepts UUIDs and                session-history references (HEAD, HEAD~N, @, @N, @-N, @+N, :N, bare N). options:   -h, --help   show this help message and exit for coding agents: no-arg form mutates session history (advances active branch) UUID form is a pure polling observer if you need result images from explicit UUIDs, use `op show UUID | jq -r .image` and `contree use`

session delete

contree session delete KEY [KEY ...] (aliases rm, del) removes sessions and all their data – history, branches, pending files, shell history. The command prompts before deleting unless -y is passed. Use this to garbage-collect throwaway sessions; the disk savings on the SQLite database can be substantial when many short-lived sessions accumulate.

$ contree session delete --help usage: contree session delete [-h] [-y] KEY [KEY ...] positional arguments:   KEY          Session keys to delete options:   -h, --help   show this help message and exit   -y, --force  Do not ask for confirmation 
contree session delete KEY [KEY ...]
contree session rm KEY -y     # skip confirmation
contree session del KEY

See also