pcli

pcli is a modular terminal coding agent for Kimi-compatible models. It can connect to the hosted pcli gateway with invite-code registration, or to a local OpenAI-compatible proxy for development. The project is split into:

• pcli_kimi.py: main CLI/TUI entrypoint
• kimi_openai_proxy.py: local proxy that exposes /v1/chat/completions
• pcli/: reusable runtime modules for tools, UI, session handling, streaming, resilience, and API plumbing

The default CLI runtime uses the proxy at http://127.0.0.1:8765/v1.

What It Does

• Chat with Kimi from the terminal
• Run tools with confirmation for risky operations
• Read, edit, append, delete, and summarize files
• Search files and the web
• Attach local files, images, and PDFs
• Save and resume sessions
• Track tool loops, query chains, planner state, and reflection checks
• Use either the freebuff TUI or a classic terminal layout

Requirements

• Python 3.8+
• CLI dependencies from the base package
• Playwright Chromium only for the proxy runtime

End-user CLI install:

pip install "kimi-pcli[ui]"

or:

uv tool install "kimi-pcli[ui]"

Proxy install:

pip install "kimi-pcli[proxy]"
python3 -m playwright install chromium

Quick Start

1. Register or log in to the hosted gateway

pp-cli

Inside the CLI:

/register

Enter the gateway URL, email, password, and invite code from your administrator. The default gateway is:

https://pcli.tranlequybaotk12.workers.dev/v1

Existing users can reconnect with:

/login

2. Start the local proxy for development

Default fast IPv4 native mode:

python3 kimi_openai_proxy.py

This starts the proxy with native aiohttp, browser release after credential refresh, and IPv4-only upstream transport enabled by default.

Legacy browser-backed mode:

KIMI_PROXY_NATIVE_CLIENT=0 python3 kimi_openai_proxy.py

Native mode with dual-stack DNS if IPv4-only is not desired:

KIMI_PROXY_NATIVE_IPV4_ONLY=0 python3 kimi_openai_proxy.py

Useful proxy flags:

python3 kimi_openai_proxy.py --port 8765 --ws-port 8766

3. Start the CLI

pp-cli

If you run the CLI in a TTY with ui_style=freebuff, it starts the freebuff TUI automatically. Otherwise it falls back to the classic text UI.

Hosted gateway mode:

PCLI_BASE_URL="https://<gateway-domain>/v1" \
PCLI_API_KEY="<gateway-user-token>" \
pp-cli

Admin account-pool setup for hosted gateway lives in gateway-cf/README.md, including the scripts/kimi_account_export.py flow for exporting Kimi browser credentials into the dashboard Quick Add form.

Configuration and State

The CLI bootstrap creates and uses ~/.code_assistant/ by default:

• ~/.code_assistant/config.json
• ~/.code_assistant/sessions/
• ~/.code_assistant/backups/
• ~/.code_assistant/logs/

Session browser state for the proxy lives under .webchat_state/kimi/.

Common config keys live in pcli/config/settings.py. The important defaults are:

• model: kimi-k2.6-thinking
• base_url: http://127.0.0.1:8765/v1
• ui_style: freebuff
• auto_context_compact: true
• auto_save: true

Example config:

{
  "model": "kimi-k2.6-thinking",
  "base_url": "http://127.0.0.1:8765/v1",
  "ui_style": "freebuff",
  "auto_context_compact": true
}

CLI Usage

Use /help inside the CLI for the full command list. The common commands are:

• /help, /tools, /files
• /model, /ui, /set
• /clear, /save, /sessions, /load
• /backups, /restore
• /autoyes, /risk
• /context, /chain, /plan, /autoplan
• /plugins, /mcp, /mcp test <server>
• /reflect, /watchdog, /hooks, /warm
• /exit

The CLI supports:

• multiline input and bracket paste
• session save/resume
• file attachment parsing
• tool call rendering in both TUI and classic layouts
• auto-confirm for safe operations and guided confirmation for risky ones

MCP Servers

pcli can call local MCP stdio servers through one generic agent tool, mcp_tool, so MCP support does not bloat every request with many tool schemas. Servers are cold-started only when the agent calls mcp_tool or when you run /mcp test <server>.

Add servers to ~/.code_assistant/config.json:

{
  "mcp_enabled": true,
  "mcp_servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/tlqbao/Desktop"],
      "description": "Filesystem MCP scoped to Desktop",
      "tools": ["read_file", "list_directory"]
    }
  }
}

Inside pcli:

/mcp
/mcp test filesystem

The agent should first call:

mcp_tool(server="filesystem", action="list_tools")

Then call the exact MCP tool:

mcp_tool(server="filesystem", action="call_tool", tool="read_file", input={"path": "/home/tlqbao/Desktop/a.txt"})

Proxy API

The proxy is OpenAI-compatible and serves the CLI at /v1.

Common endpoints:

• GET /health
• GET /metrics
• GET /kimi/stats
• GET /kimi/native

If native mode is enabled, the proxy also exposes runtime controls for the native client path. See doc/PHASE3_DEPLOY_GUIDE.md for the full deployment and rollback flow.

For an internal alpha, put an access gateway in front of the hosted Fly proxy so each developer receives an individual token. See doc/ACCESS_GATEWAY_DESIGN.md and doc/PYPI_FLY_DEPLOY.md.

Environment Variables

CLI

• PCLI_KIMI_SESSION_ID: override the per-session proxy header value
• PCLI_BASE_URL: override base_url without editing config
• PCLI_API_KEY: override api_key without editing config
• PCLI_MODEL: override model without editing config
• PCLI_AGENT_DEBUG=1: enable agent/tool-loop debug logging

Proxy

• KIMI_PROXY_AUTH_TOKEN: require Authorization: Bearer <token> or X-API-Key
• KIMI_PROXY_NATIVE_CLIENT=1: enable the native aiohttp path
• KIMI_PROXY_NATIVE_IPV4_ONLY=1: force native upstream requests to IPv4
• KIMI_PROXY_NATIVE_MAX_INFLIGHT=2: cap concurrent native requests
• KIMI_PROXY_NATIVE_RELEASE_BROWSER=1: release Playwright resources after refresh
• KIMI_PROXY_DEBUG_PHASE3=1: verbose native routing logs

See doc/PHASE3_DEPLOY_GUIDE.md for the full native-mode environment matrix.

Testing

Run the test suite:

pytest -q

Useful focused checks:

python3 -m py_compile pcli_kimi.py kimi_openai_proxy.py
pytest tests/test_kimi_proxy.py -q

Compare Playwright vs native path on a running proxy:

python3 bench/native_vs_playwright.py --repeats 3

Benchmarks and Docs

• doc/USER_GUIDE.md
• doc/DEVELOPER_GUIDE.md
• doc/ARCHITECTURE.md
• doc/PYPI_FLY_DEPLOY.md
• doc/PHASE3_DEPLOY_GUIDE.md
• doc/PERFORMANCE_IMPROVEMENT_PLAN.md
• doc/CHANGELOG_PERF.md
• bench/run_bench.py
• bench/phase3_acceptance.py
• bench/fast_tool_accuracy.py
• bench/latency_probe.py

License

MIT