@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.

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

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:

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:

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

pie models validate
pie models validate --path /abs/path/to/models.json

Generate a starter template:

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:

pie

Or pass an initial prompt:

pie chat "Summarize this repository"

Use Pie in one-shot mode:

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:

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:

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

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:

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 Search

Pie exposes a canonical web_search tool for public web research, current information, online documentation, and internet inspiration. Workspace search remains separate: use grep_text, find_files, and list_dir for local repository content.

web_search uses provider-native web search where supported. It does not scrape DuckDuckGo or fall back to bash with curl or Python HTTP scripts. If the current provider/model cannot perform native web search, the tool returns a clear unavailable result with provider/configuration details.

Use web_fetch after search 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.

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:

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:

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
• iTerm2
• Ghostty

Development

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 and npm run verify:unity:reliability before release candidates that claim real-provider or 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.

Publishing

Publish @cydm/pie from the monorepo root.

Set the npm token first:

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

Then publish:

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