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 companion», работающего полностью локально на моделях изображений с открытыми весами вместо API OpenAI.
Это отдельное приложение или навык Codex?Это навык агента Codex, вызываемый внутри Codex CLI/агента, а не отдельная программа с GUI; установщик в один клик поднимает изолированный рантайм, а навык сам прогоняет конвейер генерации.
Как установить его и создать питомца?Запустите INSTALLSKILL.bat, чтобы установить навык и создать изолированный рантайм, затем внутри Codex загрузите минимум две фотографии и попросите собрать вашего компаньона, чтобы он извлёк устойчивые черты личности через --identity-notes.
Нужен ли API-ключ OpenAI или конкретный GPU?API-ключ OpenAI не нужен; для полного нейросетевого конвейера требуется совместимый GPU NVIDIA, чтобы запускать модель по умолчанию FLUX.2 [klein] 4B или более тяжёлый бэкенд Qwen-Image-Edit-2511 — оба подтягиваются в обычный кэш Hugging Face.
Что будет, если мой GPU не потянет нейросетевые модели?Вместо запроса API-ключа PocketMen автоматически переключается на детерминированный движок v0.2, который может лишь искажать ваши пиксели и не способен придумать новые позы вроде помахивания или цикла бега.
Что происходит с загруженными фотографиями?Исходные референсные фото по умолчанию остаются локально и никогда не попадают в публичную историю 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