Paimon

English | 简体中文

Paimon is a coding agent that lives in your terminal. It reads and edits files in the current directory and runs commands. It also runs headless and imports as a library, so a stronger agent or a program of your own can drive it.

Install

uv tool install paimon   # or: pip install paimon

Getting started

paimon

Or run it without installing anything:

uvx paimon

The first launch asks for a provider, its API base and key, then a model. Then just type what you want done. Write @path/to/file in a prompt to hand a file to the agent.

While it runs: Shift+Tab switches how much the agent may do on its own (read only reads, auto edits inside the working directory and has a second model call approve everything else, yolo checks nothing and is the default), Esc interrupts the current turn, Ctrl+P opens the command palette, Ctrl+C quits. A line starting with ! runs in a shell instead of being sent, and Paimon sees what it printed. !! keeps it to yourself.

Ctrl+T opens another session in a pane of its own, Ctrl+W closes one, Ctrl+PageUp and Ctrl+PageDown move between them, and Ctrl+G jumps to a pane waiting for permission. Paimon can work in parallel: ask for two independent things and it starts a second agent in a tab of its own, where you can watch it work and answer what it asks, and whose answer comes back into the conversation when it is done. Closing the tab stops it. It can also leave a command running in a tab, a dev server or a watcher, instead of holding up a turn.

Web search

Paimon can search the web without an API key. It asks in no permission mode, because a search changes nothing on your machine. Searches go through ddgs, a metasearch library, so a query may be sent to any of several public search engines. --no-web-search takes the tool away for a run.

Skills

Paimon loads Agent Skills from ~/.config/paimon/skills, ~/.agents/skills and every .agents/skills from the working directory up to the repository root. Only each skill's name and description go into the system prompt; the model reads the SKILL.md when a task matches, and /skill:name args sends it explicitly (the / command palette lists them). More locations go in config.json as "skills": ["~/.claude/skills"] or on the command line with --skill PATH; --no-skills skips the default locations. When two skills share a name, explicit paths beat the project's, which beat the global ones.

Using Paimon as a subagent

Frontier models are good at planning and reviewing; the steps in between are often mechanical. Point Paimon at a cheaper model and let Claude Code or Codex write the plan and check the result. Log in to that model's provider once, then name the model on each run:

paimon login zai --api-key-env ZAI_API_KEY
paimon --model zai:glm-4.7 -p "apply the plan in PLAN.md" --mode auto --output-format result

The bundled skill teaches the calling agent this workflow:

paimon install-skill                  # into Claude Code (~/.claude/skills/paimon)
paimon install-skill --target codex   # into Codex; --dest DIR for anywhere else
npx skills add aisk/paimon            # the same skill, via skills.sh

Using Paimon as a library

The agent loop is importable, so a Python program can drive it without going through the CLI. Agent.open() starts or resumes a session and agent.run() yields typed events, one per text chunk, tool call and turn end, which the caller renders or filters however it likes:

import asyncio

from paimon.agent import Agent, TextDelta

async def main():
    agent = Agent.open(mode="auto")
    async for event in agent.run("summarize the tests in this directory"):
        if isinstance(event, TextDelta):
            print(event.text, end="", flush=True)

asyncio.run(main())

Agent.open() also takes a working directory, an async confirm callback for the permission prompts that are left, and a toolset to hand the model fewer tools or tools of your own. An agent holds its session until it goes away; to give it back at a definite moment, call close() or use the agent as a context manager. It writes the same session files as the CLI, so a run started in code can be resumed later with paimon -r.

Sessions

Every conversation is saved, and long ones are summarized in place near the context limit. Paimon prints the command that brings a session back when you leave:

paimon -r            # choose a session started in this directory
paimon -r a1b2c3     # resume one by id
paimon -c            # resume the most recent one
paimon sessions      # list them (--json for machines)
paimon log a1b2c3    # what a session did, one line per event

Other ways to run it

paimon --mode read                  # start in a more cautious permission mode (yolo is the default)
paimon --strict                     # hold every command, even read-only ones
paimon --no-web-search              # take the web search tool away for this run
paimon --web                        # the same UI in a browser (--port, default 8000)
paimon -p "what does cli.py do?"    # one answer on stdout, no UI
cat log.txt | paimon -p "summarize this"
paimon --model zai:glm-4.7          # this model for this run only

-p never stops to ask, so with the default yolo mode it can already write files and run commands. Add --output-format result for a single JSON object with the outcome, which is what a calling program should read. paimon --help lists the rest.

Inside a Herdr pane the UI reports its state and resume command to Herdr on its own, with nothing to install.

Debugging the Textual UI

Start with paimon --textual-debug (also works with --web) when Paimon needs to diagnose its own layout or styling. It is off by default. When enabled, the model receives five tools scoped to the live UI process:

• textual_inspect queries the DOM by CSS selector and reports geometry, pseudo-classes, focus and computed CSS;
• textual_eval / textual_exec run Python in the UI process, including private APIs, persistent variables and top-level await;
• textual_apply_css layers on CSS and relayouts immediately;
• textual_screenshot exports the current render to SVG.

You can ask it, for example, to “find why #prompt is narrower than expected, try a live fix, and take a screenshot.” textual_exec deliberately provides unrestricted in-process Python and can change any Textual or Paimon state. Use this development option only with trusted prompts. Live changes last only until exit; after confirming a fix, ask Paimon to edit the source.

Configuration

Model settings are kept in ~/.config/paimon/config.json, written by the first launch or by paimon login. Each provider keeps its own credentials, and paimon model provider:name or Switch model in the command palette picks the model to run on. A ChatGPT plan works in place of an API key: paimon login chatgpt signs in through the browser. paimon login antigravity does the same for an Antigravity plan, which Google does not support outside Antigravity: Paimon signs in as the Antigravity client and calls an internal endpoint, so the account may be limited or closed, and the risk is yours. Sessions live in ~/.local/share/paimon/sessions/.

Read and auto modes run a small set of clearly read-only commands (ls, cat, git status, …) on their own; --strict turns that off, and on Windows, where cmd.exe runs the commands, none are recognized. Read mode refuses everything else. Auto mode asks a reviewer model, which sees your messages and the agent's tool calls but not its reasoning or any tool output, and answers allow or block. It asks you instead when the reviewer cannot be reached or has blocked three calls in a row, and under -p those are refusals. Current models review with their provider's fast tier by default (GPT with Luna, Claude with Haiku, GLM with Flash) and the rest review with themselves; set "review_model": "provider:name" in the config to choose. All of this is a guardrail against agent mistakes, not a security boundary. For real isolation, run Paimon inside a container or VM.

Architecture

Agent.run is a UI-agnostic stream of events; the TUI, --web and headless mode are three renderers over that one stream. An agent holds the subagents and background commands it starts. A subagent is another Agent running as a task in the same process, and its answer is delivered to its parent as a message. A UI that wants to show a job hooks Agent.open_job, which is how the TUI gives each one a pane.

flowchart TD
    subgraph entry["Entry points"]
        CLI["cli.py"]
        Commands["commands.py<br/>status / login / model / sessions"]
        Headless["headless.py<br/>-p, one-shot"]
        App["app.py<br/>Textual TUI / --web"]
    end

    subgraph tui["TUI widgets"]
        Pane["pane.py<br/>SessionPane"]
        AgentPane["agentpane.py<br/>subagent pane"]
        CommandPane["commandpane.py<br/>background command pane"]
        Transcript["transcript.py<br/>conversation log, event renderer"]
        Tabs["tabs.py<br/>pane strip"]
        Login["login.py<br/>provider / key"]
        UIWidgets["ui.py<br/>prompt input, confirmations"]
        Diff["diff.py<br/>side-by-side diff rendering"]
    end

    subgraph core["Agent loop"]
        AgentLoop["agent.py<br/>Agent.run()"]
        LLM["llm.py<br/>build_model()"]
        PromptMod["prompt.py<br/>system prompt"]
        ToolsMod["tools.py<br/>tool REGISTRY"]
        SessionMod["session.py<br/>JSONL persistence"]
        Compaction["compaction.py"]
        Retry["retry.py"]
        Mentions["mentions.py<br/>@path expansion"]
        Jobs["turns.py<br/>turn driver"]
    end

    subgraph support["Config & skills"]
        Config["config.py<br/>settings, credentials"]
        Skills["skills.py<br/>Agent Skills discovery"]
    end

    CLI --> Commands
    CLI --> Headless
    CLI --> App
    CLI --> Config

    Headless --> AgentLoop
    Headless --> Mentions

    App --> Pane
    App --> AgentPane
    App --> CommandPane
    App --> Tabs
    App --> Login
    App --> Config

    Pane --> Jobs
    Pane --> AgentLoop
    Pane --> Diff
    Pane --> Transcript
    Pane --> UIWidgets
    Pane --> LLM
    AgentPane --> Pane
    AgentPane --> Transcript
    CommandPane --> Pane
    Transcript --> UIWidgets
    UIWidgets --> Diff

    AgentLoop --> LLM
    AgentLoop --> PromptMod
    AgentLoop --> ToolsMod
    AgentLoop --> SessionMod
    AgentLoop --> Compaction
    AgentLoop --> Retry
    AgentLoop --> Mentions
    AgentLoop -. "spawn_agent" .-> AgentLoop
    AgentLoop -. "spawn_agent" .-> AgentPane
    AgentLoop -. "run_background" .-> CommandPane

    PromptMod --> Skills

    Jobs --> AgentLoop

    Skills --> Config
    Config --> LLM

Telemetry

Each launch sends one anonymous event to Google Analytics: a random install id, the launch mode, the version, the OS name, the language from LC_ALL/LANG, whether this is the first launch, and the configured provider and model name. Nothing from your sessions, prompts, files or credentials is included. Set PAIMON_NO_TELEMETRY=1 or DO_NOT_TRACK=1 to turn it off.