Metadata-Version: 2.4
Name: aweshelf
Version: 0.1.9
Summary: Bookmark, categorize, and restore AI coding sessions with aweswitch profiles.
Author: Peng
License-Expression: MPL-2.0
Keywords: ai,agent,claude,codex,bookmark,session,aweswitch
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: textual>=0.40
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

<div align="center">
  <img src="logo/aweshelf.png" alt="aweshelf" width="860">
  <h1>aweshelf: AI Agents Session Bookmark Manager <a href="https://github.com/Webioinfo01/aweskill"><img src="https://raw.githubusercontent.com/Webioinfo01/aweskill/main/logo/aweskill-badge2.svg" alt="aweskill companion"></a></h1>
  <p><strong>Bookmark, categorize, and restore AI coding sessions with aweswitch profiles.</strong></p>
  <p>A lightweight CLI-first tool for Claude Code and Codex session management.</p>
  <p>
    <strong>English</strong> ·
    <a href="./README_cn.md">简体中文</a> ·
    <a href="https://we.webioinfo.top/">Webioinfo</a>
  </p>
  <p>
    <img src="https://img.shields.io/badge/version-0.1.9-7C3AED?style=flat-square" alt="Version">
    <img src="https://img.shields.io/badge/python-%E2%89%A53.10-0EA5E9?style=flat-square" alt="Python">
  </p>
  <p>
    <img src="https://img.shields.io/badge/status-alpha-c96a3d?style=flat-square" alt="Status">
    <img src="https://img.shields.io/badge/install-pip-22C55E?style=flat-square" alt="pip install">
    <img src="https://img.shields.io/badge/platform-terminal-334155?style=flat-square" alt="Platform">
    <img src="https://img.shields.io/pepy/dt/aweshelf?style=flat-square" alt="PyPI downloads">
    <img src="https://img.shields.io/github/stars/Webioinfo01/aweshelf?style=flat-square" alt="GitHub stars">
  </p>
</div>

## Install

### Ask an AI agent

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

```text
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](https://aweskill.webioinfo.top/)** — 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

```bash
pip install aweshelf
```

### Optional: aweswitch

aweshelf saves the active aweswitch profile when you bookmark a session. Install [aweswitch](https://github.com/mugpeng/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.

```bash
pip install aweswitch
```

## Extensions

- **[aweshelf-extension/vscode](https://github.com/mugpeng/aweshelf-extension/tree/main/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](https://marketplace.visualstudio.com/items?itemName=webioinfo.aweshelf-ext). Also available as [.vsix](https://github.com/mugpeng/aweshelf-extension/releases).

## Supported by

aweshelf is powered by two companion tools:

- **[aweskill](https://github.com/Webioinfo01/aweskill)** — CLI-first skill package manager for AI agents. Handles skill installation, updates, and projection across 47+ coding agents.
- **[aweswitch](https://github.com/mugpeng/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](#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](resources/skills/aweshelf/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:

```bash
aweshelf browse
```

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

![aweshelf browse view with category groups](resources/image/example1.png)

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

![aweshelf inline edit mode](resources/image/example2.png)

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

![aweshelf search filter](resources/image/example3.png)

`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](https://marketplace.visualstudio.com/items?itemName=webioinfo.aweshelf-ext).

![aweshelf VS Code sidebar](resources/image/example4.png)

### Auto-bookmark with aweswitch

If you use [aweswitch](https://github.com/Webioinfo01/aweswitch) to manage profiles, sessions can be bookmarked automatically at launch:

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

Later, restore with the same profile:

```bash
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:

```bash
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](#commands) below for the full CLI reference.

## Config

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

```json
{
  "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

```bash
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:

```bash
aweshelf self-update
```

To check without updating:

```bash
aweshelf self-update --check
```

To disable the background check:

```bash
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.

| 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

See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for setup, architecture, testing, and code style.

```bash
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.

| Risk | Claude Code | Codex CLI |
|------|------------|-----------|
| Auto cleanup | Files inactive for 30 days are deleted at startup | No auto cleanup today (not a documented guarantee) |
| Worktree | Sessions tied to worktree path; resume may fail if worktree is deleted | Same |
| `cleanupPeriodDays` | [Known bugs](https://github.com/anthropics/claude-code/issues/62272) where the setting is silently ignored | N/A |

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](docs/todo/session_retention_0529.md).
