aweshelf: AI Agents 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 · 简体中文 · Webioinfo

Install

Ask an AI agent

If you are working inside Claude Code, Codex, Cursor, or another coding agent, tell it:

Read https://github.com/Webioinfo01/aweshelf/blob/main/README.ai.md and follow it to install aweshelf for this agent.

The agent will first install the aweshelf CLI, then choose one of two skill management options:

1. Via aweskill — installs and manages the skill from GitHub with update, projection, and backup support. Requires Node.js.
2. Direct copy — downloads SKILL.md into the agent's skill directory. No extra dependencies beyond Python, but future updates require copying the file again manually.

pip

pip install aweshelf

Optional: aweswitch

aweshelf saves the active aweswitch profile when you bookmark a session. Install aweswitch to enable multi-profile management — without it, aweshelf works but profile restore on resume is skipped.

With aweswitch, you can resume a session using the original provider (e.g. Claude Code official API) or switch to another configured profile like cc-xiaomi, cc-glm, etc. — each with its own API endpoint, token, and model.

pip install aweswitch

Extensions

• aweshelf-extension/vscode — VS Code / Cursor extension for browsing, searching, and resuming bookmarks from the sidebar. Search aweshelf-ext in the extension marketplace, or open in Marketplace. Also available as .vsix.

Supported by

aweshelf is powered by two companion tools:

• aweskill — CLI-first skill package manager for AI agents. Handles skill installation, updates, and projection across 47+ coding agents.
• aweswitch — Agent profile switcher. Lets you launch sessions with different API endpoints, tokens, and models. aweshelf stores aweswitch profiles in bookmarks so sessions restore with the right config.

aweswitch manages how you launch sessions; aweshelf manages how you remember them. Use aweswitch -c to auto-bookmark at launch, and aweshelf resume to restore with the same profile later.

Usage

AI Agent

Install the aweshelf skill (see Install above), then just tell your agent what to do.

Example requests:

"Bookmark the current session."

"List my bookmarks in the backend category."

"Search for bookmarks related to auth."

The agent uses the SKILL.md to understand all available commands and workflows.

Tip: Resuming a session (aweshelf resume) launches a new agent process, which may conflict with the current one. For resuming, it's best to exit the agent first and use aweshelf browse or aweshelf resume directly in your terminal.

Human

The primary way to use aweshelf interactively is the TUI:

aweshelf browse

The browse view keeps bookmarks grouped by category, with the selected bookmark's details on the right.

Press e to edit the current cell in place. Title, category, and profile changes can be saved without leaving the TUI.

Press / to filter bookmarks by title, category, session, project, prompt, or profile.

aweshelf browse opens an interactive terminal UI with a sidebar table and detail pane. Browse, search, edit, and resume bookmarks without memorizing commands.

You can also use the VS Code / Cursor extension to browse, search, and resume bookmarks from the sidebar. Search aweshelf-ext in the extension marketplace, or open in Marketplace.

Auto-bookmark with aweswitch

If you use aweswitch to manage profiles, sessions can be bookmarked automatically at launch:

aweswitch -c                    # launch + auto-bookmark
aweswitch -c --profile cc-glm   # launch with profile + auto-bookmark

Later, restore with the same profile:

aweshelf resume aweshelf_0001   # restore with stored profile

aweshelf bookmarks sessions after the fact; aweswitch bridges this gap — the session is saved the moment you launch it. No manual aweshelf bookmark step needed.

You can also use aweshelf as a regular CLI:

aweshelf bookmark                    # bookmark the current session
aweshelf list                        # list all bookmarks
aweshelf resume aweshelf_0001        # resume a bookmark
aweshelf search "auth"               # search bookmarks

See Commands below for the full CLI reference.

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] [--no-interactive]
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 self-update [--check]
aweshelf help [COMMAND]

Self-Update

aweshelf checks PyPI for newer versions in the background on each run. If an update is available, a reminder is printed to stderr after the command finishes.

To update manually:

aweshelf self-update

To check without updating:

aweshelf self-update --check

To disable the background check:

export AWESHELF_NO_UPDATE_CHECK=1

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. Use --no-interactive to skip all prompts — for agents and scripting, bookmarks are created with defaults or passed values only.

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.

Support

If aweshelf saves you time, consider supporting it:

• ⭐ Star the repo — it helps others find it.
• ☕ Ko-fi — buy me a coffee.
• 💬 WeChat — scan the QR code below.

aweshelf is free and open source. Sponsors keep it maintained — thank you.

Development

See docs/CONTRIBUTING.md for setup, architecture, testing, and code style.

python -m pytest tests/

Known Risks

aweshelf bookmarks store a session_id reference — they do not copy session content. Resuming a bookmark requires the original session file to still exist on disk.

Mitigation: extend cleanupPeriodDays in ~/.claude/settings.json (e.g. 365), but verify it takes effect. For critical sessions, consider backing up the JSONL file manually.

These risks are tracked in docs/todo/session_retention_0529.md.