aweshelf 0.1.3

Bookmark, categorize, and restore AI coding sessions with aweswitch profiles.

aweshelf: Session Bookmark Manager

Bookmark, categorize, and restore AI coding sessions with aweswitch profiles.

A lightweight CLI-first tool for Claude Code and Codex session management.

English · 简体中文

Bookmark, categorize, and restore AI coding sessions with aweswitch profiles.

aweshelf lets you save your favorite Claude Code and Codex sessions, tag them with categories, and restore them instantly — including the aweswitch profile (API endpoint, model, token) that was active when you bookmarked.

Install

pip install aweshelf

Quick Start

# Bookmark the current project's most recent session
aweshelf bookmark

# List all bookmarks
aweshelf list

# Resume a bookmark
aweshelf resume aweshelf_0001

# Browse interactively
aweshelf browse

Config

Bookmarks are stored at ~/.config/aweshelf/bookmarks.json. Override with AWESHELF_CONFIG env var.

{
  "version": 1,
  "bookmarks": [
    {
      "id": "aweshelf_0001",
      "provider": "claude",
      "session_id": "550e8400-...",
      "title": "Fix auth middleware bug",
      "category": "backend",
      "project_path": "/Users/peng/Desktop/Project/my-app",
      "aweswitch_profile": "cc-glm",
      "bookmarked_at": "2026-05-20T14:00:00Z"
    }
  ]
}

Commands

aweshelf bookmark [SESSION_ID] [-t TITLE] [-c CATEGORY] [--profile PROFILE] [--current] [--verbose]
aweshelf list [-c CATEGORY] [-p PROVIDER]
aweshelf search QUERY              # search title, category, session, project, prompt, profile
aweshelf recent [-n COUNT]
aweshelf show BOOKMARK_ID [--json]
aweshelf edit BOOKMARK_ID [-t TITLE] [-c CATEGORY] [--profile PROFILE]
aweshelf rm BOOKMARK_ID [--force]
aweshelf resume BOOKMARK_ID [--profile PROFILE] [--raw] [--dry-run]
aweshelf browse
aweshelf help [COMMAND]

Browse (TUI)

aweshelf browse opens an interactive TUI with a sidebar table and detail pane. aweshelf bookmark marks already-bookmarked sessions and can update them after confirmation. Use aweshelf bookmark --current to confirm and save the most recent session in the current project without opening the session picker. Interactive bookmarking prompts for title, category, and Claude aweswitch profile; profile selection is skipped when aweswitch is not configured.

Key	Action
Enter	Resume selected session (with confirmation)
e	Inline-edit the current cell (title, category, profile)
r	Remove selected bookmark (with confirmation)
y / n	Confirm / cancel action
c	Toggle between Category-grouped and All view
s	Cycle sort order (category+id / id)
/	Filter bookmarks
Esc	Clear filter / cancel
[ / ]	Shrink / grow sidebar
?	Show keyboard shortcuts
q	Quit

In edit mode: type to edit the active cell, Delete to clear it, Tab/Right to next field, Shift+Tab/Left to previous, Up/Down to move rows, Enter to save, Esc to exit.

Development

python -m pytest tests/