Paimon

Paimon, the Traveler’s best friend, is a deliberately minimal coding agent written in Python. It can be used directly in a terminal or invoked non-interactively by another coding agent.

It has an interactive interface for normal use and a headless interface with stable, machine-readable output. Conversations are persisted, so a calling process can inspect a run and continue the same session when another pass is needed.

uvx paimon

Skill and subagent use

Paimon includes a skill that teaches coding agents such as Codex and Claude Code how to use it as a worker. Install it with skills.sh:

npx skills add aisk/paimon

The calling agent can give Paimon a bounded task, read its result, review the changes, and resume the same session with follow-up instructions. A typical delegation is not limited to one call:

Example: a calling agent delegates an implementation and follows up

coedx ~/project

› Fix the flaky retry test. Use Paimon for the implementation.

coedx I’ll delegate the focused change, then review the diff and tests.

paimon

paimon --profile worker -p "fix the flaky retry test; run the focused tests" --mode edit --output-format result

✓ session 7fd2c1e8 · updated retry.py · 8 tests passed

coedx The test passes, but cancellation is still uncovered. I’ll continue the same session.

paimon resume 7fd2c1e8

paimon --profile worker -r 7fd2c1e8 -p "add coverage for cancellation and fix any issue it exposes" --mode edit --output-format result

✓ session 7fd2c1e8 · added regression coverage · 11 tests passed

coedx Reviewed the final diff. The retry and cancellation paths are both covered.

Models and providers

Paimon is not tied to one model vendor. It supports OpenAI, Anthropic, DeepSeek, Moonshot, Z.AI, Cerebras, and other compatible providers. A custom API base can be used for self-hosted or OpenAI-compatible endpoints.

Provider and model are configured separately, and model names are free-form. New or unlisted models can therefore be used without waiting for them to be added to Paimon's model picker.

Install and run

The recommended way to run the current release:

uvx paimon

To run the latest code from the master branch:

uvx git+https://github.com/aisk/paimon@master

For a persistent installation, choose one:

with uv

uv tool install paimon

with pip

pip install paimon

Then run paimon. The first run asks for the provider, model, API base, and API key.

More commands and configuration options are in the README.

ehe?

uvx paimon --ehe