PocketMen-with-you README

The project's README from github.com/six-nut/PocketMen-with-you. As one markdown file: README.md.

PocketMen with You companion capsule logo

PocketMen with You

Turn 2+ photos into a high-fidelity Codex companion — locally.

v0.3: Neural Local Studio. No hatch-pet. No OpenAI API key. Open-weight multi-reference editing when your GPU can run it.

GitHub stars GitHub issues Release

Try now · ⭐ Star · Share example

简体中文

Why v0.3 exists

The deterministic v0.2 engine was reliable and private, but it could only warp supplied pixels. It could not genuinely invent a new waving hand, a natural running stride, a faithful kitten pose, or a polished 3D chibi redesign.

v0.3 adds a real local generative engine. When supported hardware is present, PocketMen uses an open-weight multi-reference image editor to create a canonical master and state-specific animation key poses, then applies deterministic micro-motion, atlas assembly and QA. The result is far closer to a modern hosted image editor while remaining independent from OpenAI ImageGen.

Engine stack

2+ reference images
        ↓
Codex visual identity lock
        ↓
PocketMen hardware doctor
        ↓
┌─────────────────────────────────────┐
│ Neural Local Studio                 │
│ default: FLUX.2 [klein] 4B          │
│ optional: Qwen-Image-Edit-2511      │
│ multi-reference identity editing    │
└─────────────────────────────────────┘
        ↓
canonical master + semantic key pose per state
        ↓
flat chroma extraction / alpha cleanup
        ↓
deterministic micro-animation
        ↓
8 × 9 transparent Codex atlas
        ↓
validation + contact sheet + GIF previews
        ↓
pet.json + spritesheet.webp
        ↓
Codex local install

If the neural runtime or compatible GPU is unavailable, PocketMen falls back to the deterministic v0.2 engine instead of asking for OPENAI_API_KEY.

Local neural backends

FLUX.2 [klein] 4B — default

Qwen-Image-Edit-2511 — Identity-Max

PocketMen intentionally does not make FLUX.2 [dev] the default because its model license is non-commercial.

Quality profiles

Quick start in Codex

Upload at least two images and ask:

Use $pocketmen-with-you to create and install a companion from these references.
Use Neural Local Studio when my hardware supports it.
Style: hero-chibi.
Subject type: person.
Quality: max.
Preserve identity strictly and do not use hatch-pet or any OpenAI API key.

The skill should visually summarize stable identity traits from the references and pass them through --identity-notes.

CLI

Hardware check:

pocketmen doctor

Create with automatic engine selection:

pocketmen create \
  --reference photo-1.jpg \
  --reference photo-2.jpg \
  --name "Mochi" \
  --subject-type animal \
  --style soft-real \
  --engine auto \
  --quality balanced \
  --output ./pocketmen-output \
  --install

Force the default neural model:

pocketmen create ... --engine neural --backend flux2-klein-4b --quality max

Use the heavier identity backend:

pocketmen create ... --engine neural --backend qwen-image-edit-2511 --quality max

One-click setup

INSTALL_SKILL.bat installs the skill and creates an isolated runtime. On Windows, the installer checks NVIDIA VRAM; a compatible machine automatically receives the neural dependency profile.

To explicitly prepare and cache the default local neural model:

PREPARE_NEURAL_ENGINE.bat

For Qwen Identity-Max:

PREPARE_IDENTITY_MAX.bat

Model weights are downloaded from their original model hosts into the normal Hugging Face cache; they are not committed to this repository.

Codex pet contract

PocketMen emits an 8-column × 9-row atlas, 192×208 per cell, 1536×1872 overall. States are:

idle, running-right, running-left, waving, jumping, failed, waiting, running (Codex working, not physical running), and review.

What “ImageGen-like” means here

PocketMen narrows the quality gap specifically for reference-driven Codex companion creation by combining strong open-weight image editing, multi-reference identity anchors, structured prompts, dedicated state generation, deterministic alpha extraction and strict atlas QA.

It does not claim bit-for-bit or general-purpose parity with a proprietary frontier model. Broad world knowledge, typography, complex scene reasoning and difficult multi-object composition can still differ. For the narrow “2+ photos → consistent animated companion” workflow, however, v0.3 is designed to use the strongest local path available before falling back to simple warps.

Privacy

Raw personal references remain local by default and are never copied into public Git commits/releases. The final install package contains only pet.json and spritesheet.webp.

Community & maintenance playbook

For operation cadence (24h follow-ups, community sync templates, and weekly reports), use:

License

PocketMen code: MIT.

Optional model weights retain their own licenses. The default FLUX.2 [klein] 4B and Qwen-Image-Edit-2511 backends are referenced, not redistributed.

PocketMen with You is not affiliated with Nintendo, The Pokémon Company, Game Freak, OpenAI, Black Forest Labs, Alibaba/Qwen, Hugging Face, or GitHub.

PocketMen-with-you (six-nut/PocketMen-with-you)

Searching Database…

311 ·GitHub
PocketMen-with-you
这是什么？PocketMen with You 把你的 2 张以上照片变成高保真、可动起来的“Codex 伙伴”宠物，完全在本地运行，使用开放权重的图像模型而不是 OpenAI 的 API。
这是独立应用还是 Codex 技能？它是在 Codex CLI/智能体内调用的 Codex 智能体技能，不是独立的图形界面程序；一键安装器会配置好隔离运行时，技能则替你运行生成流水线。
怎么安装并创建我的宠物？运行 INSTALLSKILL.bat 安装技能并创建隔离运行时，然后在 Codex 中上传至少两张照片，请它构建你的伙伴，这样它就能通过 --identity-notes 提取稳定的外貌特征。
我需要 OpenAI API 密钥或特定 GPU 吗？不需要 OpenAI API 密钥；要运行完整的神经网络流水线，你需要一块兼容的 NVIDIA GPU 来运行默认的 FLUX.2 [klein] 4B 模型或更重的 Qwen-Image-Edit-2511 后端，两者都会下载到常规的 Hugging Face 缓存中。
如果我的 GPU 跑不动神经网络模型会怎样？PocketMen 会自动回退到确定性的 v0.2 引擎，而不是索要 API 密钥；该引擎只能对你提供的像素做变形，无法生成挥手或跑步循环这样的新姿势。
我上传的照片会怎么样？你的原始参考照片默认留在本地，绝不会提交到公开的 Git 历史或发布中；只有最终的 pet.json 和 spritesheet.webp 会离开你的电脑。
模型权重可以免费商用吗？PocketMen 自身的代码采用 MIT，但权重许可证各不相同：默认的 FLUX.2 [klein] 4B 和 Qwen-Image-Edit-2511 后端是 Apache-2.0，而 FLUX.2 [dev] 因其权重不可商用而被刻意默认关闭。
我可以选哪些质量配置？Draft 生成一张神经规范主图加确定性的九状态动画；balanced 为每个状态增加神经关键姿势（部分通过镜像复用）；max 则为每个状态独立生成神经关键姿势。
最终输出是什么样的？PocketMen 生成一张 8 列乘 9 行的精灵图集（每格 192x208，整体 1536x1872），涵盖 idle、running、waving、jumping、failed、waiting 和 review 等状态。
为什么不直接用 OpenAI 的图像生成？PocketMen 通过本地开放权重编辑、多参考身份锚点和严格质检，缩小了“照片转动画伙伴”这一特定任务上的质量差距，让你无需 API 密钥、无需花费、也无需把照片发给云服务，就能得到相似的结果。
What are similar projects?WanGP, qwen21-nsfw-pose-skill, sprite-gen, dsh-image-gen, xxg-portrait-rebuild-light, Open-LLM-VTuber, stable-diffusion-webui, no-negative-echo
Which topics is it in?spritesheet, qwen-image, desktop-pet, openai-codex, neural-rendering, local-ai, image-editing, codex-skill, offline-first, agent-skill, multimodal, image-generation
Creator
six-nut
Size
0.2 MB
Stars
311
Updated
CommitOct 01Releasev0.3.0Aug 17
Age
2mo
Commits · 90 Days