# @cydm/pie

`@cydm/pie` is a minimal, powerful, embeddable agent suite for game developers.

It gives you a terminal-first agent experience out of the box, while staying modular enough to embed into other runtimes and products. Pie is designed for teams that want a small surface area, strong defaults, persistent sessions, tool use, and a clean path from CLI usage to deeper integration.

Pie is developed by [cydream](https://cydream.tech).

## Why Pie

- Minimal interface, low ceremony
- Powerful coding-agent workflow in the terminal
- Embeddable architecture built on reusable `@pie/*` packages
- Persistent sessions, slash commands, and skill loading
- Works well as both a daily CLI and a building block for custom agent products

## Install

```bash
npm install -g @cydm/pie
```

Pie supports Node.js 20 and newer. Release builds are validated with npm's lockfile workflow (`npm ci`) so dependency resolution is reproducible.

## Quick Start

Set an API key for the provider you want to use:

```bash
export KIMI_API_KEY="your-kimi-api-key"
# or
export BIGMODEL_API_KEY="your-bigmodel-api-key"
```

You can also configure defaults in:

- `~/.pie/settings.json`
- `~/.pie/models.json`
- `~/.pie/config.json` for legacy-compatible defaults

Minimal `~/.pie/models.json`:

```json
{
  "profiles": {
    "cy-gpt": {
      "api": "openai-completions",
      "baseUrl": "https://token.magicshell.ai/v1",
      "apiKey": "YOUR_API_KEY",
      "models": [
        {
          "id": "gpt-5.4",
          "name": "GPT 5.4",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 128000,
          "maxTokens": 16384,
          "cost": {
            "input": 0,
            "output": 0,
            "cacheRead": 0,
            "cacheWrite": 0
          }
        }
      ]
    }
  },
  "defaults": {
    "provider": "cy-gpt",
    "modelId": "gpt-5.4"
  }
}
```

Required profile fields:

- `api`
- `baseUrl`
- `apiKey` or `apiKeyEnv`
- `models`

Required model fields:

- `id`
- `input`
- `cost`
- `contextWindow`
- `maxTokens`

Validate the file explicitly:

```bash
pie models validate
pie models validate --path /abs/path/to/models.json
pie models validate --probe web_search
```

Generate a starter template:

```bash
pie models init
pie models init --stdout
```

For editor auto-complete and validation, you can also point the optional `"$schema"` field in your local `models.json` at your installed `@cydm/pie/models.schema.json` file.

Start Pie in interactive mode:

```bash
pie
```

Or pass an initial prompt:

```bash
pie chat "Summarize this repository"
```

Use Pie in one-shot mode:

```bash
pie "List the files in the current directory"
pie chat "Write a quick Python script for merge sort"
```

## Core Ideas

Pie is not just a chat CLI. It is a compact agent suite with a terminal UI on top of a reusable runtime.

- The CLI is intentionally small and fast to learn
- The agent can work with files, shell commands, sessions, and skills
- The architecture is modular, so the same foundation can be embedded into other apps and environments

If you want an agent that feels lightweight but still has serious capability, that is the design target for Pie.

## Architecture Position

`@cydm/pie` is the CLI product layer in the repo architecture.

- `@pie/agent-core` provides runtime semantics and the agent loop
- `@pie/agent-framework` provides shared application infrastructure such as sessions, skills, and extension protocols
- `@pie/shared-headless-capabilities` provides shared headless capabilities used across hosts
- `products/cli` adds terminal bindings, CLI workflows, and host-specific capabilities such as shell execution

The CLI should consume shared capability and framework contracts; it should not redefine shared runtime or extension semantics locally.

## Interactive Experience

Run:

```bash
pie
# or
pie chat
```

Main key bindings:

- `Enter` submit message
- `Shift+Enter` insert a new line
- `\` + `Enter` insert a new line in terminals without modified-enter support
- `Ctrl+C` exit
- `Ctrl+D` exit
- `Ctrl+O` expand or collapse tool output
- `/` open the slash command menu

Direct shell mode:

```text
!!git status
!!npm test
```

Commands prefixed with `!!` run directly in the shell without going through the agent.

## Slash Commands

Pie uses a hierarchical slash-command menu. The current built-in commands include:

| Command | Description |
| --- | --- |
| `pie doctor [--json]` | Diagnose local config, model setup, writable paths, browser automation, and Unity bridge hints |
| `pie models init` | Create a starter `~/.pie/models.json` |
| `pie models validate` | Validate `~/.pie/models.json` |
| `pie permissions` | Explain tool and shell safety defaults |
| `/sessions/compact` | Summarize history and create a compact checkpoint |
| `/sessions/new` | Start a new session |
| `/sessions/resume` | Resume a different session |
| `/sessions/tree` | Navigate the session tree |
| `/sessions/info` | Show session information |
| `/sessions/fork` | Fork from an earlier message |
| `/settings` | Open the settings menu |
| `/settings/model` | Choose a model |
| `/settings/theme` | Change the theme |
| `/settings/thinking` | Set reasoning depth |
| `/settings/yolo` | Toggle less restricted filesystem mode |
| `/settings/hotkeys` | Show keyboard shortcuts |
| `/settings/quit` | Exit Pie |
| `/skills/list` | List available skills |
| `/skills/use` | Use a skill |
| `/skills/reload` | Reload skills from disk |
| `/tools/subagent` | Spawn a subagent for a task |
| `/debugs/cache-test` | Run provider cache diagnostics with a dedicated 2-request probe |
| `/debugs/context` | Append a context summary to `~/.pie/logs/pie-cli.log` |
| `/debugs/package` | Append a package summary to `~/.pie/logs/pie-cli.log` |

Pie can also load extension-provided commands at runtime.

## Sessions

Pie keeps persistent sessions so you can come back to earlier work.

- Sessions are stored in `~/.pie/sessions/`
- You can switch sessions from the command menu
- You can fork a session to branch off a previous line of work
- You can compact long sessions to keep context focused

This makes Pie useful for ongoing coding tasks, not just one-off prompts.

## Skills And Extensibility

Pie supports Markdown-based skills and built-in extensions.

- Built-in skills ship with the CLI
- User skills can live under `~/.pie/skills`
- Project-local skills can live under `.pie/skills`
- Extensions can register additional commands and workflows

That is part of what makes Pie embeddable: the CLI is only one interface on top of a broader agent toolkit.

## Browser Tools

The built-in `browser-tools` skill uses Microsoft's Playwright CLI for visible browser automation. Its runtime dependencies ship with the CLI; do not run `npm install` inside the skill directory.

Resolve the skill resource and run Playwright commands:

```bash
node <resolvedPath for browser-tools/playwright-cli.js> open https://example.com
node <resolvedPath for browser-tools/playwright-cli.js> snapshot
node <resolvedPath for browser-tools/playwright-cli.js> screenshot
node <resolvedPath for browser-tools/playwright-cli.js> console
node <resolvedPath for browser-tools/playwright-cli.js> network
```

If Playwright's Chromium browser is not installed, run:

```bash
node <resolvedPath for browser-tools/playwright-cli.js> install-browser chromium
```

Run `pie doctor` to check whether Playwright CLI and its browser runtime are discoverable.

## Web Research

Pie exposes a canonical `web_research` tool for public web research, current information, online documentation, and internet inspiration. It plans search variants, uses provider-native search, fetches credible sources, and returns citations. Workspace search remains separate: use `grep_text`, `find_files`, and `list_dir` for local repository content.

`web_search` remains available as the lower-level provider-native search tool. It does not scrape DuckDuckGo or fall back to `bash` with `curl` or Python HTTP scripts. If the configured provider/model cannot perform native web search, the tool returns a clear unavailable result with provider/configuration details.

Use `web_fetch` directly when the agent needs to read a specific URL, documentation page, changelog, issue, or PDF. `web_fetch` follows redirects, extracts readable text/markdown, returns citation anchors and extraction diagnostics, and reports `requires_browser` for JavaScript-heavy pages instead of pretending the content was read. In the CLI, `web_research` can use browser-tools for browser-rendered sources when the Playwright runtime is available; Unity reports those pages as `requires_browser`.

`web_research` records route health and latency in Pie's state directory so later runs can prefer providers with better source quality, fewer timeouts, and lower rate-limit pressure. `pie doctor --json` reports the recorded provider health, and `verify:web` writes web metrics including p50/p95 latency, failure categories, and citation quality artifacts.

## Permissions

Pie's default tools operate from the current workspace. File tools are workspace-scoped, `~/.pie` is allowlisted for Pie configuration/session support, and shell commands return structured timeout/truncation/error details. The canonical shell tool is still named `bash` for compatibility; on Windows `shell:auto` uses PowerShell, and callers can explicitly request `bash`, `powershell`, or `cmd`. High-risk shell commands require confirmation outside YOLO mode. `/settings/yolo` relaxes filesystem sandbox directory restrictions and should only be used in trusted workspaces. `pie permissions` prints the current policy-derived safety summary.

## Code Intelligence

`code_intel` provides read-only JS/TS diagnostics, definition, references, symbols, and hover. CLI uses the TypeScript language service by default and falls back to lightweight text analysis only when the TypeScript service cannot start. Unity uses a Node sidecar contract for TypeScript intelligence so the PuerTS bundle does not import Node-only parser dependencies.

## Diagnostics

Use:

```bash
pie doctor
pie doctor --json
```

Doctor checks Node/npm, model configuration, API key availability, writable Pie data paths, Playwright browser readiness, Unity bridge hints, and runtime log location. User-facing errors stay concise; detailed debugging goes to `~/.pie/logs/pie-cli.log` and session trace artifacts.

## Output Modes

For non-interactive usage, Pie supports structured output options:

```bash
pie "summarize this file" --raw-output
pie "summarize this file" --json-output
pie "continue previous task" --session-id my-session
```

## Terminal Notes

For the best multiline editing experience, use a terminal with good modified-key support, such as:

- [Kitty](https://sw.kovidgoyal.net/kitty/)
- [iTerm2](https://iterm2.com/)
- [Ghostty](https://ghostty.org/)

## Development

```bash
npm ci
npm run verify:quality
npm run verify:release
npm run verify:browser
npm run verify:terminal:matrix
```

Use `npm run verify:agent` when model credentials are available and you want the real daily agent gate.
Use `npm run verify:agent:nightly` before release candidates that claim real-provider reliability.
Use `UNITY_EDITOR="/path/to/Unity" npm run verify:unity:reliability` before Unity release candidates. For live Unity Dev RPC coverage, run `PIE_UNITY_REAL_RPC=1 UNITY_EDITOR="/path/to/Unity" npm run verify:unity:reliability`.
Set `PIE_REAL_BROWSER=1` when you want `verify:browser` to open a real browser session instead of only checking the Playwright CLI contract.
Set `PIE_REAL_WEB=1` when you want `verify:web` to run real provider web research smoke with fetched or browser-read citations.

## Publishing

Publish `@cydm/pie` from the monorepo root.

Set the npm token first:

```bash
npm config set //registry.npmjs.org/:_authToken <YOUR_TOKEN>
```

Then publish:

```bash
npm run verify:release
npm publish --workspace products/cli --access public
```

If the package version already exists on npm, bump `products/cli/package.json` first.

## License

MIT
