Skip to main content

isesh

isesh is the session configuration CLI for creating sessions with profiles, workspace, and managing state/prompts.

Starting Sessions​

start​

Start a session with profile and workspace options.

isesh start <name> [options]

Options:

  • -p, --profile <name> - Profile to use (mwd, tda-manager, tda-worker, etc.)
  • -w, --workspace <path> - Working directory for the session
  • -d, --detach - Start in background
  • --cli <type> - CLI type: claude, cursor, codex, gemini

Examples:

# Start with MWD profile
isesh start my-task -p mwd

# Start with profile and workspace
isesh start my-project -p mwd -w ~/projects/my-app

# Start Manager session
isesh start project-mgr -p tda-manager -w ~/projects/my-app

# Start Worker session
isesh start worker1 -p tda-worker -w ~/projects/my-app

# Start with different CLI
isesh start my-task -p mwd --cli cursor
tip

tda-manager and tda-worker sessions can also be created and managed as a team with itda (e.g. itda list, itda tree, itda stop).

list​

List all sessions with their configurations.

isesh list [options]

Options:

  • --json, -j - Output as JSON

show​

Show session configuration.

isesh show <name>

archive​

Archive a session.

isesh archive <name>

rename​

Rename a session. All session artifacts are renamed: session config (~/.ist/sesh/configs/{name}.json), session state (~/.ist/state/sessions/{name}.json), session prompts (~/.ist/prompts/sessions/{name}/), session logs (~/.ist/logs/{name}/), the active session file (~/.ist/sessions/{name}.json), the logs metadata (name field), and the tmux session (ist--{name}).

isesh rename <old-name> <new-name>

Example:

isesh rename old-session new-session

Profile Management​

profile list​

List available profiles.

isesh profile list

profile show​

Show profile details.

isesh profile show <name>

Example:

isesh profile show mwd
isesh profile show tda-manager

profile create​

Create a new profile.

isesh profile create <name> [options]

Options:

  • --system-prompt, -s <prompt> - System prompt

Prompt Management​

prompt list​

List available prompts.

isesh prompt list

prompt show​

Display a prompt's content.

isesh prompt show <name>

Example:

isesh prompt show worker-management

prompt add​

Add a new prompt (pipe content via stdin).

echo "Your prompt content" | isesh prompt add <name>

prompt delete​

Delete a prompt.

isesh prompt delete <name>

State Management​

Session state persists data across restarts.

state list​

List all state keys.

isesh state list

state get​

Get a state value.

isesh state get <key>

Example:

isesh state get current-task

state set​

Set a state value.

isesh state set <key> <value>

Example:

isesh state set current-task "Implement user authentication"

state delete​

Delete a state value.

isesh state delete <key>

state chain​

Show the profile inheritance chain and the merged state.

isesh state chain [options]

Options:

  • --profile, -p <name> - Profile name (or IST_PROFILE env var)
  • --verbose, -v - Show state per profile in chain

state gc​

Garbage-collect state (archive first, then delete past retention).

  • Stage 1: expired non-durable keys are moved to ~/.ist/state/archive/<scope>/ (kept, not deleted).
  • Stage 2: archived entries older than 30 days are hard-deleted (--purge deletes them now).
  • Durable keys are never touched. By default all scopes are scanned.
isesh state gc [options]

Options:

  • --scope <scope> - Restrict to one scope: session, profile, global (default: all)
  • --session, -s <name> - Session ID (with --scope session)
  • --profile, -p <name> - Profile ID (with --scope profile)
  • --mine - Only collect entries authored by the current session
  • --dry-run - Report the plan only; change nothing
  • --purge - Hard-delete archived entries immediately (skip the 30-day retention)
  • --migrate - Print a migration plan for legacy keys only (never mutates)

Example:

isesh state gc --dry-run             # Preview what would be archived/deleted
isesh state gc --mine                # Only collect keys authored by this session
isesh state gc --scope global        # Restrict to the global scope
isesh state gc --migrate --dry-run   # Print a migration plan only (no changes)

Authentication​

auth login​

Log in with the IST auth CLI.

isesh auth login

auth logout​

Log out with the IST auth CLI.

isesh auth logout

auth whoami​

Show the current authenticated user.

isesh auth whoami [options]

Options:

  • --json - Output in JSON format

auth status​

Check authentication status.

isesh auth status

Session Control​

These commands are passed through to ilogsession:

isesh attach <name>   # Attach to session
isesh stop <name>     # Stop session
isesh kill <name>     # Kill session

Configuration​

Profiles are stored in ~/.ist/profiles/.

State is stored in ~/.ist/state/.

Prompts are stored in scope subdirectories of ~/.ist/prompts/: global/ (all sessions), profiles/<profile>/ (sessions using that profile), and sessions/<session>/ (one session). See skit.