Skip to content

Agent Integration

IpMan is a housekeeper for the skills your agent already has — but it also runs from inside the agent. This page covers the pieces that connect the two: the companion skills, the update flow, the status bar, and the protocol the agent follows when it drives ipman on your behalf.

Companion skills

skill-sync installs two skills into an agent so it can operate ipman for you:

ipman skill-sync --scope claude-code-user
# Installed companion skills (ipman, ipman-update) -> ~/.claude/skills
  • ipman — the housekeeper skill. The agent runs ipman ... --json and renders panels in chat; it never launches the bare TUI.
  • ipman-update — keeps the CLI and skills current (see below).

Two rules make this safe and predictable:

Targets are always explicit

IpMan never auto-installs its skill anywhere. You name the scope (--scope claude-code-user, or a project scope id), and only then is that skills directory registered as an update target. Nothing is probed or sprayed across your machine.

The skill files are generated from a template that ships inside the CLI package, so the CLI is the single source of truth: skills stay version-locked to the installed CLI. A version mismatch after upgrading the CLI is expected and resolved by regenerating the skills.

ipman skill-sync              # update every registered target to the CLI version
ipman skill-sync --check      # report CLI vs PyPI vs installed-skill versions
ipman skill-sync --self DIR   # regenerate one skill directory in place

Updating: /ipman-update

The ipman-update skill upgrades IpMan itself. It does not touch your managed skills, the store, or any scope. The flow:

  1. Check. ipman skill-sync --check --json reports three things: cli_outdated (a newer CLI exists on PyPI), skill_stale (installed skill files lag the CLI), and pypi_latest (null when offline). If both flags are false, you're current and it stops.

  2. Detect + upgrade the CLI. It inspects the ipman path to detect the install method and upgrades with the matching tool — only on your consent, never silently:

    Method Upgrade command
    pipx pipx upgrade ipman-cli
    uv uv tool upgrade ipman-cli
    pip python -m pip install --upgrade ipman-cli

  3. Regenerate skills. ipman skill-sync rewrites ipman and ipman-update (and any other registered targets) from the freshly installed CLI, bringing them back into lockstep.

If ipman isn't installed at all, the skill tells you to install it (pipx install ipman-cli or uv tool install ipman-cli) and stops.

Status bar

ipman statusline prints one compact line — fast (<50ms, no deep scan) so it can run on every prompt:

ipman statusline
# 📦 user⚑12 | proj✓3 | !1断链

Each scope shows its label, a custody flag (⚑ taken over, ✓ native), and its active-skill count; a trailing !N断链 appears when any links are broken. Wire it into Claude Code's status line in settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "ipman statusline"
  }
}

The interaction protocol

When the agent drives ipman from inside a session, the ipman skill follows a three-step protocol built around one hard rule: read first, confirm every write.

  1. Render the panel. The agent runs ipman status --json (or ipman scan --json for deep results including duplicate groups and cleanable findings) and renders a compact, numbered markdown panel — never the TUI.
  2. Confirm before any write. Any write action — absorb, dedup --apply, clean --apply, takeover, release, enable, disable, pack create — needs one explicit confirmation, with the dry-run output shown first wherever one exists.
  3. Execute and report. The agent runs the command, then re-renders the affected part of the panel so you see the before/after.

Why no TUI here

The bare ipman TUI is for a human at a terminal. Inside an agent there's no interactive terminal to drive it, so the companion skill uses the --json surface and renders panels in chat instead.