Metadata-Version: 2.4
Name: ipman-cli
Version: 0.3.0
Summary: Intelligence Package Manager - Agent skill virtual environment manager
Project-URL: Homepage, https://github.com/twisker/ipman
Project-URL: Repository, https://github.com/twisker/ipman
Project-URL: Issues, https://github.com/twisker/ipman/issues
Project-URL: Documentation, https://twisker.github.io/ipman
Author: twisker
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,cli,package-manager,skill,virtual-environment
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Software Distribution
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

<p align="center">
  <img src="images/IpMan.jpg" alt="IpMan Banner" width="600" />
</p>

# IpMan - Intelligence Package Manager

*I can take on ten.*

> Project-level virtual environments for AI agent skills — like uv/conda, but for skills. One central store, per-skill symlinks, and a lockfile that reproduces your exact skill setup anywhere.

**[Documentation](https://twisker.github.io/ipman)** | **[中文文档](https://twisker.github.io/ipman/zh/)** | **[中文 README](README.zh-cn.md)**

---

## The problem: skill bloat

Your agent caps how much context skill listings may use. Install enough global skills and they compete for that budget: descriptions of the skills you actually need get truncated or dropped, irrelevant skills mis-fire, and project A's tooling leaks into project B. Power users already solve this by hand: a central folder of cloned skill repos, symlinked per-project, updated in one place.

IpMan turns that workflow into one command — and adds the piece the manual approach can't give you: **reproducibility**.

## How it works

```
ip.yaml ──resolve──> central store clone ──pin──> @<commit> worktree
                                                        │
ip.lock <──record── commit + tree hash                  └──symlink── .claude/skills/<name>
```

- **Project-scoped by default.** Skills live in the project that needs them. Your agent's context stays lean.
- **One source of truth.** Each skill repo is cloned once into `~/.ipman/store`. Projects link to it; nothing is copied around.
- **Pinned and reproducible.** `ip.lock` records the exact commit. Clone a repo on a new machine, run `ipman sync`, get the identical skill sources back — even if upstream moved on.
- **Contribute back.** `--live` mode links a skill's real working copy: fix a bug while you work, commit it, PR it upstream.

`ip.lock` guarantees *skill source* reproducibility (MCP servers, plugins and CLI dependencies are out of scope).

## Quick start

```bash
pip install ipman-cli        # or: uv tool install ipman-cli

cd your-project
ipman init                                                 # creates ip.yaml
ipman add https://github.com/owner/skills-repo#skills/foo  # pick a skill from a repo
ipman list                                                 # what this project uses
ipman doctor                                               # links, drift, health
```

Commit `ip.yaml` and `ip.lock`. Anyone (including future you, on another machine) restores the whole skill environment with:

```bash
uvx ipman-cli sync
```

More commands:

```bash
ipman add <path> --adopt      # register your existing ~/GitHub clone, no copying
ipman add <url>#dir --live    # link the live working copy (skill development)
ipman update [name]           # re-pin this project to the source's latest commit
ipman remove <name>           # unlink from this project (store is untouched)
ipman shell init              # optional shell integration
```

## Agent support

| Agent | Status |
|-------|--------|
| Claude Code (`.claude/skills/`) | Verified (macOS) |
| OpenClaw (`.openclaw/skills/`) | Path mapping, unverified |

Adding an agent is a one-line path mapping — the store and lockfile are agent-agnostic by design.

## Security note

Third-party skills can instruct your agent to run arbitrary commands. IpMan shows what it installs (source, commit, skill directory) and never installs silently — review before you use. A deeper risk-assessment engine exists in the codebase but is dormant while the core workflow matures.

## Status

Early and moving fast. The core loop (init/add/sync/list/remove/update/doctor) is tested on macOS with Claude Code. Windows has a fallback code path but is not yet a supported target. Feedback and issues welcome.

## License

Apache License 2.0 — see [LICENSE](LICENSE) for details.
