Metadata-Version: 2.4
Name: claudepacks
Version: 0.2.0
Summary: Project-scoped skill & agent manager for Claude Code. Interactive TUI for picking which skills and agents load per project.
Author-email: Zhenming Pan <zhenming.pan2@gmail.com>
License: MIT
Keywords: claude-code,anthropic,skills,skill-management,tui,ai-agents,context-engineering
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Software Distribution
Classifier: Topic :: Utilities
Classifier: Environment :: Console :: Curses
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# claudepacks

[![CI](https://github.com/Rion/claudepacks/actions/workflows/ci.yml/badge.svg)](https://github.com/Rion/claudepacks/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/claudepacks.svg)](https://pypi.org/project/claudepacks/)
[![Python 3.9+](https://img.shields.io/pypi/pyversions/claudepacks.svg)](https://pypi.org/project/claudepacks/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**Cut your Claude Code session overhead from ~7,000 to ~200 tokens.** One command per project — pick exactly which skills and agents load, instead of all of them.

[简体中文](https://github.com/Rion/claudepacks/blob/main/README.zh-CN.md) · [Changelog](https://github.com/Rion/claudepacks/blob/main/CHANGELOG.md) · [Troubleshooting](https://github.com/Rion/claudepacks/blob/main/docs/troubleshooting.md) · [Recipes](https://github.com/Rion/claudepacks/blob/main/docs/recipes.md) · [Architecture](https://github.com/Rion/claudepacks/blob/main/docs/architecture.md) · [Contributing](https://github.com/Rion/claudepacks/blob/main/CONTRIBUTING.md) · [Releasing](https://github.com/Rion/claudepacks/blob/main/RELEASING.md)

---

## Why

Claude Code injects metadata for every skill in `~/.claude/skills/` **and** every agent in `~/.claude/agents/` into the session preamble. With 50+ skills and a handful of agents installed globally — common once you accumulate tooling across multiple projects — that's **~7k tokens of overhead before you type a single character**, in every conversation, in every project.

But most projects only need a handful of them. A backend API project doesn't need front-end design helpers. A data project doesn't need Docker deployment tools.

**claudepacks** moves your global skills and agents into a stash at `~/.claude/packs/`, and each project's `.claude/skills/` and `.claude/agents/` hold symlinks to **only what that project needs**. You pick them with an interactive selector.

## Before / after

```text
~/.claude/skills/    (50 entries, ~6800 tokens loaded in every session)
~/.claude/agents/    (5  entries, ~600  tokens loaded in every session)
```

After `claudepacks`:

```text
~/.claude/packs/                              (the stash — single source of truth)
├── skills/
│   ├── code-review/SKILL.md                  ← plain skill
│   ├── sql-helper/SKILL.md
│   └── devtools -> ~/.claude/skills/devtools ← source pack, symlinked in place
└── agents/
    ├── reviewer.md
    └── migrator.md

my-backend-project/.claude/skills/            (only what this project needs)
├── code-review  → ~/.claude/packs/skills/code-review/
└── sql-helper   → ~/.claude/packs/skills/sql-helper/

my-backend-project/.claude/agents/
└── reviewer.md  → ~/.claude/packs/agents/reviewer.md
```

**Result**: ~7000 tokens → a few hundred per conversation. Tokens you can spend on actual code.

## Demo

![claudepacks in action — picking which skills and agents this project loads](https://raw.githubusercontent.com/Rion/claudepacks/main/docs/demo.gif)


## Install

```bash
pip install claudepacks
```

Requires Python 3.9+. macOS / Linux only (curses TUI is not supported on Windows). The only runtime dependency is PyYAML.

## First run — automatic migration

The first time you run `claudepacks` in any project, it offers to migrate your existing global skills and agents into the stash:

```text
First-time setup: migrating to ~/.claude/packs/

Backups (full copy, originals preserved):
  ~/.claude/skills  →  ~/.claude/skills.bak-20260513-120000
  ~/.claude/agents  →  ~/.claude/agents.bak-20260513-120000

Target: ~/.claude/packs/
  skills/  (3 plain skill(s) → move)
    + code-review
    + sql-helper
    + debugger
  skills/  (1 source pack(s) → symlink in place)
    ⟶ devtools -> ~/.claude/skills/devtools
  agents/  (2 agent(s) → move)
    + reviewer.md
    + migrator.md

Proceed? [y/N]:
```

`y` runs it; `N` aborts with zero side effects. The whole pre-existing `~/.claude/skills/` and `~/.claude/agents/` are first **copied** to timestamped backups before any move — your data is recoverable.

You can also invoke it explicitly: `claudepacks init`.

### Source pack handling

A skill directory with a top-level `SKILL.md` **and** nested sub-skills (each sub-dir holding its own `SKILL.md`) is recognized as a **source pack**. Migration **symlinks** these in place rather than moving them — wrappers and tooling that reference absolute paths inside the pack keep working.

## Use

```bash
cd <your-project>
claudepacks
```

Opens an interactive selector grouped into **🤖 agent** and **📦 skill**.

| Key | Action |
| --- | --- |
| `↑ ↓` / `j k` | navigate |
| `space` | toggle current artifact on / off |
| `A` | enable all visible |
| `N` | disable all visible |
| `a` | smart toggle all visible (invert majority) |
| `/` | filter (type to search; `esc` to clear) |
| `↵` | apply changes and exit |
| `esc` | quit without saving |
| `g` / `G` / `PgUp` / `PgDn` | jump |

State badges: `✓ on` (green) / `· off` (dim). Pending changes are marked `✱` in yellow.

After applying, **restart Claude Code** to pick up the new project artifact set. The next `/context` should show a dramatically smaller Skills / Custom Agents footprint.

## Layout

```text
claudepacks/
├── LICENSE                  MIT
├── README.md                This file
├── README.zh-CN.md          Chinese
├── CHANGELOG.md             Release notes
├── CONTRIBUTING.md          Dev workflow + branch strategy
├── RELEASING.md             Release flow + SemVer policy + checklist
├── CLAUDE.md                Guidance for Claude Code in this repo
├── TODOS.md                 Deferred work, prioritized
├── pyproject.toml
├── docs/
│   ├── architecture.md      Design rationale + diagrams
│   ├── troubleshooting.md   Common issues + fixes (incl. zh-CN)
│   ├── recipes.md           Real-world workflows (incl. zh-CN)
│   └── demo.{gif,cast}      Demo assets
├── claudepacks/
│   ├── __init__.py
│   ├── __main__.py
│   ├── cli.py               Entry point — opens TUI / runs init
│   ├── core.py              Paths, artifact discovery, frontmatter
│   ├── migrate.py           First-time setup (~/.claude/{skills,agents} → packs/)
│   └── tui.py               Curses-based selector
└── tests/
    └── smoke.sh             End-to-end smoke tests
```

## Status

`v0.2.0`. See [CHANGELOG](https://github.com/Rion/claudepacks/blob/main/CHANGELOG.md).

## License

MIT — see [LICENSE](https://github.com/Rion/claudepacks/blob/main/LICENSE).
