Metadata-Version: 2.1
Name: kimi-pcli
Version: 0.1.0a17
Summary: pcli terminal coding agent with hosted gateway registration
Author: pcli maintainers
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: openai>=1.0.0
Requires-Dist: httpx>=0.25.0
Provides-Extra: ui
Requires-Dist: rich>=13.7.0; extra == "ui"
Requires-Dist: textual>=0.58.0; extra == "ui"
Requires-Dist: colorama>=0.4.6; extra == "ui"
Requires-Dist: pypdf>=4.0.0; extra == "ui"
Requires-Dist: Pillow>=10.0.0; extra == "ui"
Provides-Extra: proxy
Requires-Dist: aiohttp>=3.9.0; extra == "proxy"
Requires-Dist: playwright>=1.40.0; extra == "proxy"
Provides-Extra: alpha
Requires-Dist: aiohttp>=3.9.0; extra == "alpha"
Requires-Dist: playwright>=1.40.0; extra == "alpha"
Requires-Dist: rich>=13.7.0; extra == "alpha"
Requires-Dist: textual>=0.58.0; extra == "alpha"
Requires-Dist: colorama>=0.4.6; extra == "alpha"
Requires-Dist: pypdf>=4.0.0; extra == "alpha"
Requires-Dist: Pillow>=10.0.0; extra == "alpha"

# 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:

```bash
pip install "kimi-pcli[ui]"
```

or:

```bash
uv tool install "kimi-pcli[ui]"
```

Proxy install:

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

## Quick Start

### 1. Register or log in to the hosted gateway

```bash
pp-cli
```

Inside the CLI:

```text
/register
```

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

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

Existing users can reconnect with:

```text
/login
```

### 2. Start the local proxy for development

Default fast IPv4 native mode:

```bash
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:

```bash
KIMI_PROXY_NATIVE_CLIENT=0 python3 kimi_openai_proxy.py
```

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

```bash
KIMI_PROXY_NATIVE_IPV4_ONLY=0 python3 kimi_openai_proxy.py
```

Useful proxy flags:

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

### 3. Start the CLI

```bash
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:

```bash
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:

```json
{
  "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`:

```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:

```text
/mcp
/mcp test filesystem
```

The agent should first call:

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

Then call the exact MCP tool:

```text
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`](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`](doc/ACCESS_GATEWAY_DESIGN.md) and
[`doc/PYPI_FLY_DEPLOY.md`](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`](doc/PHASE3_DEPLOY_GUIDE.md) for the full native-mode environment matrix.

## Testing

Run the test suite:

```bash
pytest -q
```

Useful focused checks:

```bash
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:

```bash
python3 bench/native_vs_playwright.py --repeats 3
```

## Benchmarks and Docs

- [`doc/USER_GUIDE.md`](doc/USER_GUIDE.md)
- [`doc/DEVELOPER_GUIDE.md`](doc/DEVELOPER_GUIDE.md)
- [`doc/ARCHITECTURE.md`](doc/ARCHITECTURE.md)
- [`doc/PYPI_FLY_DEPLOY.md`](doc/PYPI_FLY_DEPLOY.md)
- [`doc/PHASE3_DEPLOY_GUIDE.md`](doc/PHASE3_DEPLOY_GUIDE.md)
- [`doc/PERFORMANCE_IMPROVEMENT_PLAN.md`](doc/PERFORMANCE_IMPROVEMENT_PLAN.md)
- [`doc/CHANGELOG_PERF.md`](doc/CHANGELOG_PERF.md)
- `bench/run_bench.py`
- `bench/phase3_acceptance.py`
- `bench/fast_tool_accuracy.py`
- `bench/latency_probe.py`

## License

MIT
