Metadata-Version: 2.4
Name: kimi-calls
Version: 0.1.0
Summary: CLIs that delegate bulk reading, boilerplate generation, and chat-log extraction to Kimi K2.5 — saving tokens inside coding agents.
Project-URL: Homepage, https://github.com/rejkpp/kimi-calls
Project-URL: Repository, https://github.com/rejkpp/kimi-calls
Project-URL: Documentation, https://github.com/rejkpp/kimi-calls#readme
Project-URL: Issues, https://github.com/rejkpp/kimi-calls/issues
Author: Ramiro
License: MIT
License-File: LICENSE
Keywords: claude-code,cli,codex,kimi,llm,moonshot,tokens
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Requires-Dist: openai<2.0,>=1.50
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# kimi-calls

Three CLIs that delegate the bulky parts of a coding-agent session to **Kimi K2.5** via the Moonshot platform API. The reasoning stays in your main agent (Claude Code, Codex, Cursor, …); the bulk reading, boilerplate generation, and chat-log extraction get offloaded — saving tokens, latency, and money.

| Tool           | Replaces                          | Use when                                                  |
|----------------|-----------------------------------|-----------------------------------------------------------|
| `ask-kimi`     | reading 3+ files into context     | "what does this codebase do across these N files?"        |
| `kimi-write`   | generating boilerplate from scratch | tests, configs, docstrings, repetitive scaffolding       |
| `extract-chat` | parsing session JSONL by hand     | turn a Claude Code or Codex session into plain dialogue   |

## Install

Requires Python 3.10+.

```bash
pip install kimi-calls
# or
uv tool install kimi-calls
```

### Get a Moonshot API key

1. Sign in at <https://platform.moonshot.ai> (the *international* platform — not `moonshot.cn`, which is China-only).
2. Add credit under **Billing** (pay-as-you-go; a few dollars goes a long way).
3. Create a key under **API Keys** → it'll start with `sk-`.

### Make the key available to the CLIs

The tools read `MOONSHOT_API_KEY` from the environment. Pick one:

**Persist for every shell (recommended).** Append to `~/.zshrc` (macOS default) or `~/.bashrc`:

```bash
echo 'export MOONSHOT_API_KEY=sk-...' >> ~/.zshrc
source ~/.zshrc
```

**Per-project via `.env`.** If you use `direnv` or a similar loader:

```bash
echo 'MOONSHOT_API_KEY=sk-...' >> .env
```

**One-off in the current shell:**

```bash
export MOONSHOT_API_KEY=sk-...
```

Verify it's set:

```bash
echo $MOONSHOT_API_KEY    # should print sk-...
```

Optional: pin a model with `KIMI_MODEL` (default `kimi-k2.5`).

## Usage

### `ask-kimi` — bulk reading

```bash
ask-kimi --paths src/api.py src/db.py src/auth.py \
         --question "Where do we handle session expiry?"
```

Files are concatenated **before** the question, so repeat calls on the same `--paths` list hit Moonshot's prefix cache. Keep the order stable across calls.

### `kimi-write` — boilerplate generation

```bash
kimi-write --spec  "pytest suite covering build_corpus" \
           --context src/kimi_calls/_client.py tests/test_extract.py \
           --target  tests/test_corpus.py
```

Then `Edit` only what needs fixing. Saves the round-trips you'd otherwise spend writing scaffolding token by token.

`kimi-write` refuses to overwrite an existing target unless you pass `--force`.

### `extract-chat` — session text for documentation

```bash
extract-chat ~/.claude/projects/.../session.jsonl -o /tmp/chat.txt
# or for Codex:
extract-chat ~/.codex/sessions/.../rollout.jsonl -o /tmp/chat.txt
```

When writing to `-o/--output`, `extract-chat` refuses to overwrite an existing file unless you pass `--force`.

Strips tool calls, system prompts, and binary blocks. Auto-detects Claude Code (`{"type": "user", "message": {...}}`) vs Codex (`{"role": "user", "content": ...}`) format. Pipe the result into `ask-kimi` for documentation work:

```bash
extract-chat session.jsonl -o /tmp/chat.txt
ask-kimi --paths /tmp/chat.txt docs/architecture.md \
         --question "What architecture decisions from this session belong in the doc?"
```

## Wire it into your agent

See `examples/` for ready-to-drop snippets:

- **Claude Code** — `examples/claude-code/settings.json` (permission allowlist) and `CLAUDE.md` (delegation rules).
- **Codex** — `examples/codex/AGENTS.md`.
- **Cursor** — `examples/cursor/.cursor/rules/kimi-delegation.mdc` (always-on project rule).

The full delegation policy lives in [`docs/delegation-policy.md`](docs/delegation-policy.md) — agent-agnostic guidance on when to delegate and when not to.

## Development

```bash
uv pip install -e ".[dev]"
pytest
```

Tests are pure parsing — no API calls, no key required.

## License

MIT.
