@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 requires Node.js 20.19 or 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
pie models validate --probe web_search

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.

Remote model catalogs

Pie can add centrally managed models without replacing local profiles or defaults. Add a catalog to ~/.pie/models.json and keep the virtual key in an environment variable:

{
  "remoteCatalogs": [
    {
      "id": "token-manager",
      "url": "https://token.magicshell.ai/v1/client-catalogs/pie.json",
      "apiKeyEnv": "TOKEN_MANAGER_API_KEY"
    }
  ]
}

Remote catalogs use a three-second timeout, reject redirects, and fall back to the last valid cached response. A local profile with the same id always wins. Remote catalogs never modify defaults.

Per-model overrides

Use top-level modelOverrides to patch descriptive fields of any loaded model (declared locally or provided by a remote catalog) without redeclaring the whole profile. Keys are "provider/modelId":

{
  "modelOverrides": {
    "cydream/gpt-5.6-terra": {
      "contextWindow": 256000,
      "maxTokens": 16384,
      "compat": { "streamRequiresDone": false }
    }
  }
}

Overridable fields: name, displayName, reasoning, input, cost, contextWindow, maxTokens, headers, compat, cacheCapability, webSearch, fileCapabilities. Nested objects deep-merge; arrays replace. Identity and routing fields (id, provider, api, baseUrl, apiKeyEnv, filePlatform, attachmentPlatform) cannot be overridden. Overrides apply after profiles and remote catalogs merge, and re-apply when a catalog refreshes; keys that match no loaded model are ignored.

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 (--json returns the structured safety model) | | pie capabilities [--json] | Report the command surface, flags, exit codes, and output schema for agents | | pie sessions list/read/rename/rewind/fork | Inspect and manage stored sessions non-interactively (each supports --json and --help) | | pie extensions list/enable/disable | Inspect and toggle extensions non-interactively | | /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 | | /settings/extensions | List extensions and toggle enable/disable | | /tools/subagent | Spawn a subagent for a task | | /tools/init | Create or update the project AGENTS.md (/init is a hidden direct alias) | | /settings/debugs/cache-test | Run provider cache diagnostics with a dedicated 2-request probe | | /settings/debugs/context | Append a context summary to ~/.pie/logs/pie-cli.log | | /settings/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 ~/.agents/skills (cross-tool standard) or ~/.pie/skills
• Project-local skills can live under .agents/skills (discovered from the project root down to the cwd, mirroring AGENTS.md discovery) or .pie/skills
• Override order on name collision (later wins): built-in < ~/.agents < ~/.pie < ancestor .agents (far to near) < ./.pie
• 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.

Extension Sources, Priority, And Toggles

Extensions are discovered from four sources in ascending priority (later sources shadow earlier ones by stable extension identity):

1. builtin — shipped with the CLI (ask-user, todo, plan-mode, subagent, init, changelog, attachment handlers)
2. global — ~/.pie/extensions/
3. project — ./.pie/extensions/
4. configured — repeated --extension-path <dir> flags

Every extension is enabled by default. Toggles are sparse overrides stored in settings and applied by extension identity across all sources:

• Interactive: choose Extensions in /settings, or use /settings/extensions, to open the user-default toggle menu. /settings/extensions --project edits project overrides; /settings/extensions/list|enable|disable ... remains available for command-driven use.
• Scripts and third-party UIs: pie extensions list [--json], pie extensions enable|disable <name> [--project|--user]
• Process flags: --no-builtin-extensions (skip built-ins) and --no-extensions (skip all discovered sources; --extension-path still loads)

Example override in ~/.pie/settings.json (or ./.pie/settings.json for project scope, which wins per identity):

{
  "extensions": {
    "plan-mode": { "enabled": false }
  }
}

The full contract (identity rules, schema, host integration) lives in docs/extensions-enablement.md.

Browser Tools

The built-in chrome-devtools-axi skill uses the chrome-devtools-axi CLI to drive a real Chrome browser over the Chrome DevTools Protocol. Its runtime dependencies ship with the CLI; do not run npm install inside the skill directory.

Resolve the skill resource and run browser commands:

node <resolvedPath for chrome-devtools-axi/chrome-devtools-axi-cli.js> open https://example.com
node <resolvedPath for chrome-devtools-axi/chrome-devtools-axi-cli.js> snapshot
node <resolvedPath for chrome-devtools-axi/chrome-devtools-axi-cli.js> screenshot /tmp/page.png
node <resolvedPath for chrome-devtools-axi/chrome-devtools-axi-cli.js> console
node <resolvedPath for chrome-devtools-axi/chrome-devtools-axi-cli.js> network

The CLI launches or attaches to a real Chrome/Edge browser; see --help for connection modes (headed mode, auto-connect, custom profile, remote browser URL) and CHROME_DEVTOOLS_AXI_SESSION for concurrent isolated sessions.

Run pie doctor to check whether chrome-devtools-axi and a Chrome browser are discoverable.

Terminal UI Automation

The built-in tui-use skill drives interactive terminal programs - REPLs, pdb/gdb debugger sessions, and full-screen TUI apps - through Pie's packaged PTY runtime. Run node <skill-baseDir>/tui-use-cli.js --help; no first-use dependency download or global CLI is required. Windows uses native PowerShell and ConPTY. State lives in ~/.pie/tui-use, or a dedicated PIE_TUI_USE_STATE_DIR. Always target sessions with --session <id>, confirm termination with wait --exit, and clean up only sessions and daemons you own. Use plain bash for non-interactive commands.

Desktop Control (computer-use)

The built-in computer-use extension (vendored from @injaneity/[email protected], frozen and self-maintained by Pie) controls real desktop applications on macOS, Windows, and Linux through a native accessibility helper. Desktop control is a last resort - prefer API, CLI, or web tools whenever they can accomplish the task.

Tools are tiered:

• Observe tier (default) - find_roots, observe_ui, search_ui, expand_ui, inspect_ui, read_text, wait_for read screen/UI state.
• Browser tier (default) - launch_browser, navigate_browser, evaluate_browser control a managed CDP context. Navigation and JavaScript evaluation can have side effects; these are not read-only tools.
• Act tier (first-use confirmation) - act_ui synthesizes real input (click, type, scroll, keypress, drag). The first act_ui call in each session asks for confirmation (class computer_use_act); YOLO mode bypasses it, and non-interactive hosts block it deterministically.

Platform notes:

• macOS (14+): the signed helper app installs to ~/.pie/computer-use/pie-computer-use.app on first use. Grant Accessibility and Screen Recording to pie-computer-use.app in System Settings → Privacy & Security; interactive sessions guide you through the prompts. Re-grant after helper updates (re-signing invalidates old grants).
• Windows: the helper installs to ~/.pie/helpers/computer-use/windows-bridge.exe and needs an interactive desktop session.
• Linux: the helper installs to ~/.pie/helpers/computer-use/linux-bridge and needs an AT-SPI2 bus (a running desktop session; headless servers are not supported).

Config: ~/.pie/extensions/computer-use.json (user) or .pie/computer-use.json (project) with browser_use, headless, cursor_overlay, managed_browser; env overrides PIE_COMPUTER_USE_BROWSER_USE / PIE_COMPUTER_USE_HEADLESS / PIE_COMPUTER_USE_CURSOR_OVERLAY / PIE_COMPUTER_USE_MANAGED_BROWSER. Run /computer-use (slash command) to inspect the loaded config, and pie doctor for helper install status. The extension can be toggled like any other (/settings/extensions, identity computer-use).

Web Research

Pie exposes one default model-visible web tool: web_research. Use it for public web research, current information, online documentation, and internet inspiration. Pass query for research, url to fetch a known page/PDF, or query with mode: "search" for low-level search results. Workspace search remains separate: use grep_text, find_files, and list_dir for local repository content.

web_search and web_fetch remain lower-level internal primitives for probes, diagnostics, and tests; they are not separate default model-visible tools. web_search 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, Pie returns a clear unavailable result with provider/configuration details. In the CLI, web_research can use chrome-devtools-axi for browser-rendered sources when a Chrome browser 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.

In interactive Plan mode (/tools/plan), workspace editing tools are unavailable. The bash guard accepts simple read commands and read-only pipelines such as rg 'TODO' . | head -20; it blocks redirects, command substitution, and write-capable subcommands. Use plan_scratch to write, read, or list temporary text drafts in a directory dedicated to the current session. Shell redirection to /tmp remains blocked in Plan mode. Leave Plan mode before changing workspace files.

Code Intelligence

code_intel provides read-only JS/TS diagnostics, definition, references, symbols, and hover. CLI uses an isolated TypeScript worker by default and falls back to bounded lightweight text analysis on worker startup/OOM/crash/timeout failures; aborts, permission errors, and path escapes do not fallback. 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, chrome-devtools-axi and Chrome 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

Machine-Readable Output (Agents And Hosts)

Every management command (sessions, doctor, models, extensions, permissions, capabilities) emits one compact JSON envelope when given --json:

{"v":1,"ok":true,"kind":"sessions.list","data":[...],"meta":{"count":10,"total":42,"nextCursor":"..."},"help":["..."]}

• v is a constant output-schema generation marker; kind identifies the command.
• meta carries pagination (nextCursor) and aggregates; help[] lists concrete next steps when they exist and never duplicates large payloads.
• Errors are structured on stdout: {"v":1,"ok":false,"kind":"...","error":{"code":"session_not_found","message":"...","hint":"..."}}.
• Exit codes: 0 success, 1 business failure, 2 usage error. Unknown flags fail loudly; every subcommand supports --help.
• sessions list --json defaults to the current project (--all lists every project). Rows are minimal (id, name, updatedAt, count) with --fields and --full opt-ins; sessions read truncates content by default with the same opt-ins.
• JSONL protocol mode (--json-events) identifies entries by entryId only (the legacy checkpointId alias is gone) and caps large tool results and turn summaries by default; pass --event-detail full for untruncated payloads. Truncation always carries truncated/fullLength markers.

Run pie capabilities --json to discover the full command surface, flags, and exit-code contract programmatically.

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 before release candidates that claim real-provider reliability. Unity checks in the default chain are offline tests and static package/bundle checks only. Real Editor, reload, Play Mode, and Player verification use the manual checklist in products/pie-unity/TESTING.md, not an automated Unity gate. Set PIE_REAL_BROWSER=1 when you want verify:browser to open a real browser session instead of only checking the chrome-devtools-axi 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:

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