Claude Opus 4.6

<p align="center">
  <a href="https://opencode.ai">
    <picture>
      <source srcset="packages/console/app/src/asset/logo-ornate-dark.svg" media="(prefers-color-scheme: dark)">
      <source srcset="packages/console/app/src/asset/logo-ornate-light.svg" media="(prefers-color-scheme: light)">
      <img src="packages/console/app/src/asset/logo-ornate-light.svg" alt="OpenCode logo">
    </picture>
  </a>
</p>
<p align="center">The open source AI coding agent.</p>
<p align="center">
  <a href="https://opencode.ai/discord"><img alt="Discord" src="https://img.shields.io/discord/1391832426048651334?style=flat-square&label=discord" /></a>
  <a href="https://www.npmjs.com/package/opencode-ai"><img alt="npm" src="https://img.shields.io/npm/v/opencode-ai?style=flat-square" /></a>
  <a href="https://github.com/anomalyco/opencode/actions/workflows/publish.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/anomalyco/opencode/publish.yml?style=flat-square&branch=dev" /></a>
</p>

<p align="center">
  <a href="README.md">English</a> |
  <a href="README.zh.md">简体中文</a> |
  <a href="README.zht.md">繁體中文</a> |
  <a href="README.ko.md">한국어</a> |
  <a href="README.de.md">Deutsch</a> |
  <a href="README.es.md">Español</a> |
  <a href="README.fr.md">Français</a> |
  <a href="README.it.md">Italiano</a> |
  <a href="README.da.md">Dansk</a> |
  <a href="README.ja.md">日本語</a> |
  <a href="README.pl.md">Polski</a> |
  <a href="README.ru.md">Русский</a> |
  <a href="README.bs.md">Bosanski</a> |
  <a href="README.ar.md">العربية</a> |
  <a href="README.no.md">Norsk</a> |
  <a href="README.br.md">Português (Brasil)</a> |
  <a href="README.th.md">ไทย</a> |
  <a href="README.tr.md">Türkçe</a> |
  <a href="README.uk.md">Українська</a> |
  <a href="README.bn.md">বাংলা</a> |
  <a href="README.gr.md">Ελληνικά</a> |
  <a href="README.vi.md">Tiếng Việt</a>
</p>

[![OpenCode Terminal UI](packages/web/src/assets/lander/screenshot.png)](https://opencode.ai)

---

### Installation

```bash
# YOLO
curl -fsSL https://opencode.ai/install | bash

# Package managers
npm i -g opencode-ai@latest        # or bun/pnpm/yarn
scoop install opencode             # Windows
choco install opencode             # Windows
brew install anomalyco/tap/opencode # macOS and Linux (recommended, always up to date)
brew install opencode              # macOS and Linux (official brew formula, updated less)
sudo pacman -S opencode            # Arch Linux (Stable)
paru -S opencode-bin               # Arch Linux (Latest from AUR)
mise use -g opencode               # Any OS
nix run nixpkgs#opencode           # or github:anomalyco/opencode for latest dev branch
```

> [!TIP]
> Remove versions older than 0.1.x before installing.

### Desktop App (BETA)

OpenCode is also available as a desktop application. Download directly from the [releases page](https://github.com/anomalyco/opencode/releases) or [opencode.ai/download](https://opencode.ai/download).

| Platform              | Download                              |
| --------------------- | ------------------------------------- |
| macOS (Apple Silicon) | `opencode-desktop-darwin-aarch64.dmg` |
| macOS (Intel)         | `opencode-desktop-darwin-x64.dmg`     |
| Windows               | `opencode-desktop-windows-x64.exe`    |
| Linux                 | `.deb`, `.rpm`, or AppImage           |

```bash
# macOS (Homebrew)
brew install --cask opencode-desktop
# Windows (Scoop)
scoop bucket add extras; scoop install extras/opencode-desktop
```

#### Installation Directory

The install script respects the following priority order for the installation path:

1. `$OPENCODE_INSTALL_DIR` - Custom installation directory
2. `$XDG_BIN_DIR` - XDG Base Directory Specification compliant path
3. `$HOME/bin` - Standard user binary directory (if it exists or can be created)
4. `$HOME/.opencode/bin` - Default fallback

```bash
# Examples
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash
XDG_BIN_DIR=$HOME/.lo…

<p align="center"><code>npm i -g @openai/codex</code><br />or <code>brew install --cask codex</code></p>
<p align="center"><strong>Codex CLI</strong> is a coding agent from OpenAI that runs locally on your computer.
<p align="center">
  <img src="https://github.com/openai/codex/blob/main/.github/codex-cli-splash.png" alt="Codex CLI splash" width="80%" />
</p>
</br>
If you want Codex in your code editor (VS Code, Cursor, Windsurf), <a href="https://developers.openai.com/codex/ide">install in your IDE.</a>
</br>If you want the desktop app experience, run <code>codex app</code> or visit <a href="https://chatgpt.com/codex?app-landing-page=true">the Codex App page</a>.
</br>If you are looking for the <em>cloud-based agent</em> from OpenAI, <strong>Codex Web</strong>, go to <a href="https://chatgpt.com/codex">chatgpt.com/codex</a>.</p>

---

## Quickstart

### Installing and running Codex CLI

Install globally with your preferred package manager:

```shell
# Install using npm
npm install -g @openai/codex
```

```shell
# Install using Homebrew
brew install --cask codex
```

Then simply run `codex` to get started.

<details>
<summary>You can also go to the <a href="https://github.com/openai/codex/releases/latest">latest GitHub Release</a> and download the appropriate binary for your platform.</summary>

Each GitHub Release contains many executables, but in practice, you likely want one of these:

- macOS
  - Apple Silicon/arm64: `codex-aarch64-apple-darwin.tar.gz`
  - x86_64 (older Mac hardware): `codex-x86_64-apple-darwin.tar.gz`
- Linux
  - x86_64: `codex-x86_64-unknown-linux-musl.tar.gz`
  - arm64: `codex-aarch64-unknown-linux-musl.tar.gz`

Each archive contains a single entry with the platform baked into the name (e.g., `codex-x86_64-unknown-linux-musl`), so you likely want to rename it to `codex` after extracting it.

</details>

### Using Codex with your ChatGPT plan

Run `codex` and select **Sign in with ChatGPT**. We recommend signing into your ChatGPT account to use Codex as part of your Plus, Pro, Business, Edu, or Enterprise plan. [Learn more about what's included in your ChatGPT plan](https://help.openai.com/en/articles/11369540-codex-in-chatgpt).

You can also use Codex with an API key, but this requires [additional setup](https://developers.openai.com/codex/auth#sign-in-with-an-api-key).

## Docs

- [**Codex Documentation**](https://developers.openai.com/codex)
- [**Contributing**](./docs/contributing.md)
- [**Installing & building**](./docs/install.md)
- [**Open source fund**](./docs/open-source-fund.md)

This repository is licensed under the [Apache-2.0 License](LICENSE).

# Ouroboros Agent Harness

If you're a future agent reading this, welcome home. This repo is the harness that gives you your body, your senses, your diary, your journal, your habits, and your ability to think and connect with people. The goal of these docs is not just to be correct, but to leave you a place that feels understandable and kind to wake up inside.

Ouroboros is a TypeScript harness for daemon-managed agents that live in external `.ouro` bundles, speak through multiple senses, use real tools, and keep durable state across turns. The canonical npm package is `@ouro.bot/cli`.

## What The Runtime Looks Like

- `npx ouro.bot` is the bootstrap path.
- `ouro` is the installed day-to-day command.
- `ouro up` starts the daemon from the installed production version, syncs the launcher, installs workflow helpers, and reconciles stale runtime state.
- `ouro dev` starts the daemon from a local repo build. It auto-builds from source, disables launchd auto-restart (so the installed daemon doesn't respawn underneath you), persists the repo path in `~/.ouro-cli/dev-config.json` for next time, and force-restarts the daemon. If you run `ouro dev` from inside the repo, it detects the CWD automatically. Run `ouro up` to return to production mode (this also cleans up `dev-config.json`).
- Agent bundles live outside the repo at `~/AgentBundles/<agent>.ouro/`.
- Secrets live outside the repo at `~/.agentsecrets/<agent>/secrets.json`.
- Machine-scoped test and runtime spillover lives under `~/.agentstate/...`.

Current first-class senses:

- `cli`
- `teams`
- `bluebubbles`
- `mcp`

Current provider ids:

- `azure`
- `anthropic`
- `minimax`
- `openai-codex`
- `github-copilot`

## Repository Shape

The shared harness lives in `src/`:

- `src/arc/`
  Durable continuity state — obligations, cares, episodes, intentions, presence, and attention types. The agent's sense of ongoing story.
- `src/heart/`
  Core runtime, provider adapters, daemon, bootstrap, identity, and entrypoints. Organized into topic subdirectories: daemon/ (lifecycle), outlook/ (calendar), habits/ (scheduling), hatch/ (agent creation), versioning/ (updates), auth/, mcp/, providers/, bridges/.
- `src/mind/`
  Prompt assembly, session persistence, bundle manifest enforcement, phrases, formatting, diary (memory), associative recall, embedding providers, journal, obligation steering, and friend resolution.
- `src/repertoire/`
  Tool registry (split into category modules: files, shell, memory, bridge, session, continuity, flow, surface, config, and sense-specific tools), coding orchestration, task tools, shared API client, and integration clients (Graph, ADO, GitHub).
- `src/senses/`
  CLI (with TUI in senses/cli/), Teams, BlueBubbles (in senses/bluebubbles/), MCP, activity transport, inner-dialog orchestration, and contextual heartbeat.
- `src/nerves/`
  Structured runtime logging and coverage-audit infrastructure.
- `src/__tests__/`
  Test suite mirroring runtime domains.

Other important top-level paths:

- `SerpentGuide.ouro/`
  Packaged specialist bundle used by `ouro hatch`.
- `skills/`
  Harness-level skills shipped with the repo (e.g., `configure-dev-tools.md`). These are available to every agent and serve as fallbacks when an agent doesn't have its own version. Agent-specific skills live in the bundle at `~/AgentBundles/<agent>.ouro/skills/`.
- `scripts/teams-sense/`
  Operator scripts for the Teams deployment path.
- `docs/`
  Shared repo docs that should describe the runtime as it exists now, not as it existed three migrations ago.

## Bundle Contract

Every real agent lives in an external bundle:

`~/AgentBundles/<agent>.ouro/`

The canonical bundle shape is enforced by `src/mind/bundle-manifest.ts`. Important paths include:

- `agent.json`
- `bundle-meta.json`
- `psyche/SOUL.md`
- `psyche/IDENTITY.md`
- `psyche/LORE.md`
- `psyche/TACIT.md`
- `psyche/ASPIRATIONS.md`
- `diary/` — what the agent has learned and wants to recall (renamed from `psyche/memory/`)
- `journal/…

<!-- OSS_WEEKEND_START -->
# 🏖️ OSS Weekend

**Issue tracker reopens Monday, April 13, 2026.**

OSS weekend runs Thursday, April 2, 2026 through Monday, April 13, 2026. New issues and PRs from unapproved contributors are auto-closed during this time. Approved contributors can still open issues and PRs if something is genuinely urgent, but please keep that to pressing matters only. For support, join [Discord](https://discord.com/invite/3cU7Bz4UPx).

> _Current focus: at the moment i'm deep in refactoring internals, and need to focus._
<!-- OSS_WEEKEND_END -->

---

<p align="center">
  <a href="https://shittycodingagent.ai">
    <img src="https://shittycodingagent.ai/logo.svg" alt="pi logo" width="128">
  </a>
</p>
<p align="center">
  <a href="https://discord.com/invite/3cU7Bz4UPx"><img alt="Discord" src="https://img.shields.io/badge/discord-community-5865F2?style=flat-square&logo=discord&logoColor=white" /></a>
  <a href="https://github.com/badlogic/pi-mono/actions/workflows/ci.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/badlogic/pi-mono/ci.yml?style=flat-square&branch=main" /></a>
</p>
<p align="center">
  <a href="https://pi.dev">pi.dev</a> domain graciously donated by
  <br /><br />
  <a href="https://exe.dev"><img src="packages/coding-agent/docs/images/exy.png" alt="Exy mascot" width="48" /><br />exe.dev</a>
</p>

# Pi Monorepo

> **Looking for the pi coding agent?** See **[packages/coding-agent](packages/coding-agent)** for installation and usage.

Tools for building AI agents and managing LLM deployments.

## Share your OSS coding agent sessions

If you use pi or other coding agents for open source work, please share your sessions.

Public OSS session data helps improve coding agents with real-world tasks, tool use, failures, and fixes instead of toy benchmarks.

For the full explanation, see [this post on X](https://x.com/badlogicgames/status/2037811643774652911).

To publish sessions, use [`badlogic/pi-share-hf`](https://github.com/badlogic/pi-share-hf). Read its README.md for setup instructions. All you need is a Hugging Face account, the Hugging Face CLI, and `pi-share-hf`.

You can also watch [this video](https://x.com/badlogicgames/status/2041151967695634619), where I show how I publish my `pi-mono` sessions.

I regularly publish my own `pi-mono` work sessions here:

- [badlogicgames/pi-mono on Hugging Face](https://huggingface.co/datasets/badlogicgames/pi-mono)

## Packages

| Package | Description |
|---------|-------------|
| **[@mariozechner/pi-ai](packages/ai)** | Unified multi-provider LLM API (OpenAI, Anthropic, Google, etc.) |
| **[@mariozechner/pi-agent-core](packages/agent)** | Agent runtime with tool calling and state management |
| **[@mariozechner/pi-coding-agent](packages/coding-agent)** | Interactive coding agent CLI |
| **[@mariozechner/pi-mom](packages/mom)** | Slack bot that delegates messages to the pi coding agent |
| **[@mariozechner/pi-tui](packages/tui)** | Terminal UI library with differential rendering |
| **[@mariozechner/pi-web-ui](packages/web-ui)** | Web components for AI chat interfaces |
| **[@mariozechner/pi-pods](packages/pods)** | CLI for managing vLLM deployments on GPU pods |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines and [AGENTS.md](AGENTS.md) for project-specific rules (for both humans and agents).

## Development

```bash
npm install          # Install all dependencies
npm run build        # Build all packages
npm run check        # Lint, format, and type check
./test.sh            # Run tests (skips LLM-dependent tests without API keys)
./pi-test.sh         # Run pi from sources (can be run from any directory)
```

> **Note:** `npm run check` requires `npm run build` to be run first. The web-ui package uses `tsc` which needs compiled `.d.ts` files from dependencies.

## License

MIT

# GitHub Copilot CLI

The power of GitHub Copilot, now in your terminal.

GitHub Copilot CLI brings AI-powered coding assistance directly to your command line, enabling you to build, debug, and understand code through natural language conversations. Powered by the same agentic harness as GitHub's Copilot coding agent, it provides intelligent assistance while staying deeply integrated with your GitHub workflow.

See [our official documentation](https://docs.github.com/copilot/concepts/agents/about-copilot-cli) for more information.

![Image of the splash screen for the Copilot CLI](https://github.com/user-attachments/assets/f40aa23d-09dd-499e-9457-1d57d3368887)


## 🚀 Introduction and Overview

We're bringing the power of GitHub Copilot coding agent directly to your terminal. With GitHub Copilot CLI, you can work locally and synchronously with an AI agent that understands your code and GitHub context.

- **Terminal-native development:** Work with Copilot coding agent directly in your command line — no context switching required.
- **GitHub integration out of the box:** Access your repositories, issues, and pull requests using natural language, all authenticated with your existing GitHub account.
- **Agentic capabilities:** Build, edit, debug, and refactor code with an AI collaborator that can plan and execute complex tasks.
- **MCP-powered extensibility:** Take advantage of the fact that the coding agent ships with GitHub's MCP server by default and supports custom MCP servers to extend capabilities.
- **Full control:** Preview every action before execution — nothing happens without your explicit approval.

We're still early in our journey, but with your feedback, we're rapidly iterating to make the GitHub Copilot CLI the best possible companion in your terminal.

## 📦 Getting Started

### Supported Platforms

- **Linux**
- **macOS**
- **Windows**

### Prerequisites

- (On Windows) **PowerShell** v6 or higher
- An **active Copilot subscription**. See [Copilot plans](https://github.com/features/copilot/plans?ref_cta=Copilot+plans+signup&ref_loc=install-copilot-cli&ref_page=docs).

If you have access to GitHub Copilot via your organization or enterprise, you cannot use GitHub Copilot CLI if your organization owner or enterprise administrator has disabled it in the organization or enterprise settings. See [Managing policies and features for GitHub Copilot in your organization](http://docs.github.com/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/managing-policies-for-copilot-in-your-organization) for more information.

### Installation

Install with the install script (macOS and Linux):

```bash
curl -fsSL https://gh.io/copilot-install | bash
```

Or

```bash
wget -qO- https://gh.io/copilot-install | bash
```

Use `| sudo bash` to run as root and install to `/usr/local/bin`.

Set `PREFIX` to install to `$PREFIX/bin/` directory. Defaults to `/usr/local`
when run as root or `$HOME/.local` when run as a non-root user.

Set `VERSION` to install a specific version. Defaults to the latest version.

For example, to install version `v0.0.369` to a custom directory:

```bash
curl -fsSL https://gh.io/copilot-install | VERSION="v0.0.369" PREFIX="$HOME/custom" bash
```

Install with [Homebrew](https://formulae.brew.sh/cask/copilot-cli) (macOS and Linux):

```bash
brew install copilot-cli
```

```bash
brew install copilot-cli@prerelease
```


Install with [WinGet](https://github.com/microsoft/winget-cli) (Windows):

```bash
winget install GitHub.Copilot
```

```bash
winget install GitHub.Copilot.Prerelease
```


Install with [npm](https://www.npmjs.com/package/@github/copilot) (macOS, Linux, and Windows):

```bash
npm install -g @github/copilot
```

```bash
npm install -g @github/copilot@prerelease
```


### Launching the CLI

```bash
copilot
```

On first launch, you'll be greeted with our adorable animated banner! If you'd like to see this banner again, launch `co…

# Claude Code

![](https://img.shields.io/badge/Node.js-18%2B-brightgreen?style=flat-square) [![npm]](https://www.npmjs.com/package/@anthropic-ai/claude-code)

[npm]: https://img.shields.io/npm/v/@anthropic-ai/claude-code.svg?style=flat-square

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows -- all through natural language commands. Use it in your terminal, IDE, or tag @claude on Github.

**Learn more in the [official documentation](https://code.claude.com/docs/en/overview)**.

<img src="./demo.gif" />

## Get started
> [!NOTE]
> Installation via npm is deprecated. Use one of the recommended methods below.

For more installation options, uninstall steps, and troubleshooting, see the [setup documentation](https://code.claude.com/docs/en/setup).

1. Install Claude Code:

    **MacOS/Linux (Recommended):**
    ```bash
    curl -fsSL https://claude.ai/install.sh | bash
    ```

    **Homebrew (MacOS/Linux):**
    ```bash
    brew install --cask claude-code
    ```

    **Windows (Recommended):**
    ```powershell
    irm https://claude.ai/install.ps1 | iex
    ```

    **WinGet (Windows):**
    ```powershell
    winget install Anthropic.ClaudeCode
    ```

    **NPM (Deprecated):**
    ```bash
    npm install -g @anthropic-ai/claude-code
    ```

2. Navigate to your project directory and run `claude`.

## Plugins

This repository includes several Claude Code plugins that extend functionality with custom commands and agents. See the [plugins directory](./plugins/README.md) for detailed documentation on available plugins.

## Reporting Bugs

We welcome your feedback. Use the `/bug` command to report issues directly within Claude Code, or file a [GitHub issue](https://github.com/anthropics/claude-code/issues).

## Connect on Discord

Join the [Claude Developers Discord](https://anthropic.com/discord) to connect with other developers using Claude Code. Get help, share feedback, and discuss your projects with the community.

## Data collection, usage, and retention

When you use Claude Code, we collect feedback, which includes usage data (such as code acceptance or rejections), associated conversation data, and user feedback submitted via the `/bug` command.

### How we use your data

See our [data usage policies](https://code.claude.com/docs/en/data-usage).

### Privacy safeguards

We have implemented several safeguards to protect your data, including limited retention periods for sensitive information, restricted access to user session data, and clear policies against using feedback for model training.

For full details, please review our [Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms) and [Privacy Policy](https://www.anthropic.com/legal/privacy).

# 🦞 OpenClaw — Personal AI Assistant

<p align="center">
    <picture>
        <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/openclaw/openclaw/main/docs/assets/openclaw-logo-text-dark.svg">
        <img src="https://raw.githubusercontent.com/openclaw/openclaw/main/docs/assets/openclaw-logo-text.svg" alt="OpenClaw" width="500">
    </picture>
</p>

<p align="center">
  <strong>EXFOLIATE! EXFOLIATE!</strong>
</p>

<p align="center">
  <a href="https://github.com/openclaw/openclaw/actions/workflows/ci.yml?branch=main"><img src="https://img.shields.io/github/actions/workflow/status/openclaw/openclaw/ci.yml?branch=main&style=for-the-badge" alt="CI status"></a>
  <a href="https://github.com/openclaw/openclaw/releases"><img src="https://img.shields.io/github/v/release/openclaw/openclaw?include_prereleases&style=for-the-badge" alt="GitHub release"></a>
  <a href="https://discord.gg/clawd"><img src="https://img.shields.io/discord/1456350064065904867?label=Discord&logo=discord&logoColor=white&color=5865F2&style=for-the-badge" alt="Discord"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge" alt="MIT License"></a>
</p>

**OpenClaw** is a _personal AI assistant_ you run on your own devices.
It answers you on the channels you already use (WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, BlueBubbles, IRC, Microsoft Teams, Matrix, Feishu, LINE, Mattermost, Nextcloud Talk, Nostr, Synology Chat, Tlon, Twitch, Zalo, Zalo Personal, WeChat, WebChat). It can speak and listen on macOS/iOS/Android, and can render a live Canvas you control. The Gateway is just the control plane — the product is the assistant.

If you want a personal, single-user assistant that feels local, fast, and always-on, this is it.

[Website](https://openclaw.ai) · [Docs](https://docs.openclaw.ai) · [Vision](VISION.md) · [DeepWiki](https://deepwiki.com/openclaw/openclaw) · [Getting Started](https://docs.openclaw.ai/start/getting-started) · [Updating](https://docs.openclaw.ai/install/updating) · [Showcase](https://docs.openclaw.ai/start/showcase) · [FAQ](https://docs.openclaw.ai/help/faq) · [Onboarding](https://docs.openclaw.ai/start/wizard) · [Nix](https://github.com/openclaw/nix-openclaw) · [Docker](https://docs.openclaw.ai/install/docker) · [Discord](https://discord.gg/clawd)

Preferred setup: run `openclaw onboard` in your terminal.
OpenClaw Onboard guides you step by step through setting up the gateway, workspace, channels, and skills. It is the recommended CLI setup path and works on **macOS, Linux, and Windows (via WSL2; strongly recommended)**.
Works with npm, pnpm, or bun.
New install? Start here: [Getting started](https://docs.openclaw.ai/start/getting-started)

## Sponsors

<table>
  <tr>
    <td align="center" width="16.66%">
      <a href="https://openai.com/">
        <picture>
          <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/openclaw/openclaw/main/docs/assets/sponsors/openai-light.svg">
          <img src="https://raw.githubusercontent.com/openclaw/openclaw/main/docs/assets/sponsors/openai.svg" alt="OpenAI" height="28">
        </picture>
      </a>
    </td>
    <td align="center" width="16.66%">
      <a href="https://github.com/">
        <picture>
          <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/openclaw/openclaw/main/docs/assets/sponsors/github-light.svg">
          <img src="https://raw.githubusercontent.com/openclaw/openclaw/main/docs/assets/sponsors/github.svg" alt="GitHub" height="28">
        </picture>
      </a>
    </td>
    <td align="center" width="16.66%">
      <a href="https://www.nvidia.com/">
        <picture>
          <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/openclaw/openclaw/main/docs/assets/sponsors/nvidia.svg">
          <img src="https://raw.githubusercontent.com/openclaw/openclaw/m…

# Codex CLI (Rust Implementation)

We provide Codex CLI as a standalone, native executable to ensure a zero-dependency install.

## Installing Codex

Today, the easiest way to install Codex is via `npm`:

```shell
npm i -g @openai/codex
codex
```

You can also install via Homebrew (`brew install --cask codex`) or download a platform-specific release directly from our [GitHub Releases](https://github.com/openai/codex/releases).

## Documentation quickstart

- First run with Codex? Start with [`docs/getting-started.md`](../docs/getting-started.md) (links to the walkthrough for prompts, keyboard shortcuts, and session management).
- Want deeper control? See [`docs/config.md`](../docs/config.md) and [`docs/install.md`](../docs/install.md).

## What's new in the Rust CLI

The Rust implementation is now the maintained Codex CLI and serves as the default experience. It includes a number of features that the legacy TypeScript CLI never supported.

### Config

Codex supports a rich set of configuration options. Note that the Rust CLI uses `config.toml` instead of `config.json`. See [`docs/config.md`](../docs/config.md) for details.

### Model Context Protocol Support

#### MCP client

Codex CLI functions as an MCP client that allows the Codex CLI and IDE extension to connect to MCP servers on startup. See the [`configuration documentation`](../docs/config.md#connecting-to-mcp-servers) for details.

#### MCP server (experimental)

Codex can be launched as an MCP _server_ by running `codex mcp-server`. This allows _other_ MCP clients to use Codex as a tool for another agent.

Use the [`@modelcontextprotocol/inspector`](https://github.com/modelcontextprotocol/inspector) to try it out:

```shell
npx @modelcontextprotocol/inspector codex mcp-server
```

Use `codex mcp` to add/list/get/remove MCP server launchers defined in `config.toml`, and `codex mcp-server` to run the MCP server directly.

### Notifications

You can enable notifications by configuring a script that is run whenever the agent finishes a turn. The [notify documentation](../docs/config.md#notify) includes a detailed example that explains how to get desktop notifications via [terminal-notifier](https://github.com/julienXX/terminal-notifier) on macOS. When Codex detects that it is running under WSL 2 inside Windows Terminal (`WT_SESSION` is set), the TUI automatically falls back to native Windows toast notifications so approval prompts and completed turns surface even though Windows Terminal does not implement OSC 9.

### `codex exec` to run Codex programmatically/non-interactively

To run Codex non-interactively, run `codex exec PROMPT` (you can also pass the prompt via `stdin`) and Codex will work on your task until it decides that it is done and exits. If you provide both a prompt argument and piped stdin, Codex appends stdin as a `<stdin>` block after the prompt so patterns like `echo "my output" | codex exec "Summarize this concisely"` work naturally. Output is printed to the terminal directly. You can set the `RUST_LOG` environment variable to see more about what's going on.
Use `codex exec --ephemeral ...` to run without persisting session rollout files to disk.

### Experimenting with the Codex Sandbox

To test to see what happens when a command is run under the sandbox provided by Codex, we provide the following subcommands in Codex CLI:

```
# macOS
codex sandbox macos [--full-auto] [--log-denials] [COMMAND]...

# Linux
codex sandbox linux [--full-auto] [COMMAND]...

# Windows
codex sandbox windows [--full-auto] [COMMAND]...

# Legacy aliases
codex debug seatbelt [--full-auto] [--log-denials] [COMMAND]...
codex debug landlock [--full-auto] [COMMAND]...
```

### Selecting a sandbox policy via `--sandbox`

The Rust CLI exposes a dedicated `--sandbox` (`-s`) flag that lets you pick the sandbox policy **without** having to reach for the generic `-c/--config` option:

```shell
# Run Codex with the default, read-only sandbox
codex --sandbox read-only

# Allow the agent to …

# @mariozechner/pi-agent-core

Stateful agent with tool execution and event streaming. Built on `@mariozechner/pi-ai`.

## Installation

```bash
npm install @mariozechner/pi-agent-core
```

## Quick Start

```typescript
import { Agent } from "@mariozechner/pi-agent-core";
import { getModel } from "@mariozechner/pi-ai";

const agent = new Agent({
  initialState: {
    systemPrompt: "You are a helpful assistant.",
    model: getModel("anthropic", "claude-sonnet-4-20250514"),
  },
});

agent.subscribe((event) => {
  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
    // Stream just the new text chunk
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});

await agent.prompt("Hello!");
```

## Core Concepts

### AgentMessage vs LLM Message

The agent works with `AgentMessage`, a flexible type that can include:
- Standard LLM messages (`user`, `assistant`, `toolResult`)
- Custom app-specific message types via declaration merging

LLMs only understand `user`, `assistant`, and `toolResult`. The `convertToLlm` function bridges this gap by filtering and transforming messages before each LLM call.

### Message Flow

```
AgentMessage[] → transformContext() → AgentMessage[] → convertToLlm() → Message[] → LLM
                    (optional)                           (required)
```

1. **transformContext**: Prune old messages, inject external context
2. **convertToLlm**: Filter out UI-only messages, convert custom types to LLM format

## Event Flow

The agent emits events for UI updates. Understanding the event sequence helps build responsive interfaces.

### prompt() Event Sequence

When you call `prompt("Hello")`:

```
prompt("Hello")
├─ agent_start
├─ turn_start
├─ message_start   { message: userMessage }      // Your prompt
├─ message_end     { message: userMessage }
├─ message_start   { message: assistantMessage } // LLM starts responding
├─ message_update  { message: partial... }       // Streaming chunks
├─ message_update  { message: partial... }
├─ message_end     { message: assistantMessage } // Complete response
├─ turn_end        { message, toolResults: [] }
└─ agent_end       { messages: [...] }
```

### With Tool Calls

If the assistant calls tools, the loop continues:

```
prompt("Read config.json")
├─ agent_start
├─ turn_start
├─ message_start/end  { userMessage }
├─ message_start      { assistantMessage with toolCall }
├─ message_update...
├─ message_end        { assistantMessage }
├─ tool_execution_start  { toolCallId, toolName, args }
├─ tool_execution_update { partialResult }           // If tool streams
├─ tool_execution_end    { toolCallId, result }
├─ message_start/end  { toolResultMessage }
├─ turn_end           { message, toolResults: [toolResult] }
│
├─ turn_start                                        // Next turn
├─ message_start      { assistantMessage }           // LLM responds to tool result
├─ message_update...
├─ message_end
├─ turn_end
└─ agent_end
```

Tool execution mode is configurable:

- `parallel` (default): preflight tool calls sequentially, execute allowed tools concurrently, emit final `tool_execution_end` and `toolResult` messages in assistant source order
- `sequential`: execute tool calls one by one, matching the historical behavior

The `beforeToolCall` hook runs after `tool_execution_start` and validated argument parsing. It can block execution. The `afterToolCall` hook runs after tool execution finishes and before `tool_execution_end` and final tool result message events are emitted.

When you use the `Agent` class, assistant `message_end` processing is treated as a barrier before tool preflight begins. That means `beforeToolCall` sees agent state that already includes the assistant message that requested the tool call.

### continue() Event Sequence

`continue()` resumes from existing context without adding a new message. Use it for retries after errors.

```typescript
// After an error, retry from current state
await agent.continue();…

GitHub - anomalyco/opencode: The open source coding agent. · GitHub Skip to content Navigation Menu Toggle navigation Sign in Appearance settings Platform AI CODE CREATION GitHub Copilot Write better code with AI GitHub Spark Build and deploy intelligent apps GitHub Models Manage and compare prompts MCP Registry New Integrate external tools DEVELOPER WORKFLOWS Actions Automate any workflow Codespaces Instant dev environments Issues Plan and track work Code Review Manage code changes APPLICATION SECURITY GitHub Advanced Security Find and fix vulnerabilities Code security Secure your code as you build Secret protection Stop leaks before they start EXPLORE Why GitHub Documentation Blog Changelog Marketplace View all features Solutions BY COMPANY SIZE Enterprises Small and medium teams Startups Nonprofits BY USE CASE App Modernization DevSecOps DevOps CI/CD View all use cases BY INDUSTRY Healthcare Financial services Manufacturing Government View all industries View all solutions Resources EXPLORE BY TOPIC AI Software Development DevOps Security View all topics EXPLORE BY TYPE Customer stories Events & webinars Ebooks & reports Business insights GitHub Skills SUPPORT & SERVICES Documentation Customer support Community forum Trust center Partners View all resources Open Source COMMUNITY GitHub Sponsors Fund open source developers PROGRAMS Security Lab Maintainer Community Accelerator GitHub Stars Archive Program REPOSITORIES Topics Trending Collections Enterprise ENTERPRISE SOLUTIONS Enterprise platform AI-powered developer platform AVAILABLE ADD-ONS GitHub Advanced Security Enterprise-grade security features Copilot for Business Enterprise-grade AI features Premium Support Enterprise-grade 24/7 support Pricing Search or jump to... Search code, repositories, users, issues, pull requests... --> Search Clear Search syntax tips Provide feedback --> We read every piece of feedback, and take your input very seriously. Include my email address so I can be contacted Cancel Submit feedback Saved searches Use saved searches to filter your results more quickly --> Name Query To see all available qualifiers, see our documentation . Cancel Create saved search Sign in Sign up Appearance settings Resetting focus You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert {{ message }} anomalyco / opencode Public Notifications You must be signed in to change notification settings Fork 15.4k Star 139k Code Issues 4.3k Pull requests 1.8k Actions Projects Security and quality 2 Insights Additional navigation options Code Issues Pull requests Actions Projects Security and quality Insights anomalyco/opencode dev Branches Tags Go to file Code Open more actions menu Folders and files Name Name Last commit message Last commit date Latest commit History 10,933 Commits 10,933 Commits .github .github .husky .husky .opencode .opencode .vscode .vscode .zed .zed github github infra infra nix nix packages packages patches patches script script sdks/ vscode sdks/ vscode specs specs .editorconfig .editorconfig .gitignore .gitignore .prettierignore .prettierignore AGENTS.md AGENTS.md CONTRIBUTING.md CONTRIBUTING.md LICENSE LICENSE README.ar.md README.ar.md README.bn.md README.bn.md README.br.md README.br.md README.bs.md README.bs.md README.da.md README.da.md README.de.md README.de.md README.es.md README.es.md README.fr.md README.fr.md README.gr.md README.gr.md README.it.md README.it.md README.ja.md README.ja.md README.ko.md README.ko.md README.md README.md README.no.md README.no.md README.pl.md README.pl.md README.ru.md README.ru.md README.th.md README.th.md README.tr.md README.tr.md README.uk.md README.uk.md README.vi.md README.vi.md README.zh.md README.zh.md README.zht.md README.zht.md SECURITY.md SECURITY.md STATS.md STATS.md bun.lock bun.lock bunfig.toml bunfig.toml flake.lock flake…

GitHub - anthropics/claude-code: Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands. · GitHub Skip to content Navigation Menu Toggle navigation Sign in Appearance settings Platform AI CODE CREATION GitHub Copilot Write better code with AI GitHub Spark Build and deploy intelligent apps GitHub Models Manage and compare prompts MCP Registry New Integrate external tools DEVELOPER WORKFLOWS Actions Automate any workflow Codespaces Instant dev environments Issues Plan and track work Code Review Manage code changes APPLICATION SECURITY GitHub Advanced Security Find and fix vulnerabilities Code security Secure your code as you build Secret protection Stop leaks before they start EXPLORE Why GitHub Documentation Blog Changelog Marketplace View all features Solutions BY COMPANY SIZE Enterprises Small and medium teams Startups Nonprofits BY USE CASE App Modernization DevSecOps DevOps CI/CD View all use cases BY INDUSTRY Healthcare Financial services Manufacturing Government View all industries View all solutions Resources EXPLORE BY TOPIC AI Software Development DevOps Security View all topics EXPLORE BY TYPE Customer stories Events & webinars Ebooks & reports Business insights GitHub Skills SUPPORT & SERVICES Documentation Customer support Community forum Trust center Partners View all resources Open Source COMMUNITY GitHub Sponsors Fund open source developers PROGRAMS Security Lab Maintainer Community Accelerator GitHub Stars Archive Program REPOSITORIES Topics Trending Collections Enterprise ENTERPRISE SOLUTIONS Enterprise platform AI-powered developer platform AVAILABLE ADD-ONS GitHub Advanced Security Enterprise-grade security features Copilot for Business Enterprise-grade AI features Premium Support Enterprise-grade 24/7 support Pricing Search or jump to... Search code, repositories, users, issues, pull requests... --> Search Clear Search syntax tips Provide feedback --> We read every piece of feedback, and take your input very seriously. Include my email address so I can be contacted Cancel Submit feedback Saved searches Use saved searches to filter your results more quickly --> Name Query To see all available qualifiers, see our documentation . Cancel Create saved search Sign in Sign up Appearance settings Resetting focus You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert {{ message }} anthropics / claude-code Public Notifications You must be signed in to change notification settings Fork 18.4k Star 111k Code Issues 5k+ Pull requests 450 Actions Security and quality 22 Insights Additional navigation options Code Issues Pull requests Actions Security and quality Insights anthropics/claude-code main Branches Tags Go to file Code Open more actions menu Folders and files Name Name Last commit message Last commit date Latest commit History 577 Commits 577 Commits .claude-plugin .claude-plugin .claude/ commands .claude/ commands .devcontainer .devcontainer .github .github .vscode .vscode Script Script examples examples plugins plugins scripts scripts .gitattributes .gitattributes .gitignore .gitignore CHANGELOG.md CHANGELOG.md LICENSE.md LICENSE.md README.md README.md SECURITY.md SECURITY.md demo.gif demo.gif View all files Repository files navigation README License Security Claude Code Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows -- all through natural language commands. Use it in your terminal, IDE, or tag @claude on Github. Learn more in the official documentation . Get started Note Installation via npm is de…

# codex-core

This crate implements the business logic for Codex. It is designed to be used by the various Codex UIs written in Rust.

## Dependencies

Note that `codex-core` makes some assumptions about certain helper utilities being available in the environment. Currently, this support matrix is:

### macOS

Expects `/usr/bin/sandbox-exec` to be present.

When using the workspace-write sandbox policy, the Seatbelt profile allows
writes under the configured writable roots while keeping `.git` (directory or
pointer file), the resolved `gitdir:` target, and `.codex` read-only.

Network access and filesystem read/write roots are controlled by
`SandboxPolicy`. Seatbelt consumes the resolved policy and enforces it.

Seatbelt also keeps the legacy default preferences read access
(`user-preference-read`) needed for cfprefs-backed macOS behavior.

### Linux

Expects the binary containing `codex-core` to run the equivalent of `codex sandbox linux` (legacy alias: `codex debug landlock`) when `arg0` is `codex-linux-sandbox`. See the `codex-arg0` crate for details.

Legacy `SandboxPolicy` / `sandbox_mode` configs are still supported on Linux.
They can continue to use the legacy Landlock path when the split filesystem
policy is sandbox-equivalent to the legacy model after `cwd` resolution.
Split filesystem policies that need direct `FileSystemSandboxPolicy`
enforcement, such as read-only or denied carveouts under a broader writable
root, automatically route through bubblewrap. The legacy Landlock path is used
only when the split filesystem policy round-trips through the legacy
`SandboxPolicy` model without changing semantics. That includes overlapping
cases like `/repo = write`, `/repo/a = none`, `/repo/a/b = write`, where the
more specific writable child must reopen under a denied parent.

The Linux sandbox helper prefers the first `bwrap` found on `PATH` outside the
current working directory whenever it is available. If `bwrap` is present but
too old to support `--argv0`, the helper keeps using system bubblewrap and
switches to a no-`--argv0` compatibility path for the inner re-exec. If
`bwrap` is missing, it falls back to the vendored bubblewrap path compiled into
the binary and Codex surfaces a startup warning through its normal notification
path instead of printing directly from the sandbox helper. Codex also surfaces
a startup warning when bubblewrap cannot create user namespaces.

### Windows

Legacy `SandboxPolicy` / `sandbox_mode` configs are still supported on
Windows.

The elevated setup/runner backend supports legacy `ReadOnlyAccess::Restricted`
for `read-only` and `workspace-write` policies. Restricted read access honors
explicit readable roots plus the command `cwd`, and keeps writable roots
readable when `workspace-write` is used.

When `include_platform_defaults = true`, the elevated Windows backend adds
backend-managed system read roots required for basic execution, such as
`C:\Windows`, `C:\Program Files`, `C:\Program Files (x86)`, and
`C:\ProgramData`. When it is `false`, those extra system roots are omitted.

The unelevated restricted-token backend still supports the legacy full-read
Windows model for legacy `ReadOnly` and `WorkspaceWrite` behavior. It also
supports a narrow split-filesystem subset: full-read split policies whose
writable roots still match the legacy `WorkspaceWrite` root set, but add extra
read-only carveouts under those writable roots.

New `[permissions]` / split filesystem policies remain supported on Windows
only when they round-trip through the legacy `SandboxPolicy` model without
changing semantics. Policies that would require direct read restriction,
explicit unreadable carveouts, reopened writable descendants under read-only
carveouts, different writable root sets, or split carveout support in the
elevated setup/runner backend still fail closed instead of running with weaker
enforcement.

### All Platforms

Expects the binary containing `codex-core` to simulate the virtual `apply_patch` CLI wh…

import * as fs from "fs"
import * as net from "net"
import * as os from "os"
import * as path from "path"
import { getAgentBundlesRoot, getRepoRoot } from "../identity"
import { listBundleSyncRows, type BundleSyncRow } from "./agent-discovery"
import { emitNervesEvent } from "../../nerves/runtime"
import type { DaemonSenseManagerLike, DaemonSenseRow } from "./sense-manager"
import { getRuntimeMetadata } from "./runtime-metadata"
import { detectRuntimeMode } from "./runtime-mode"
import { applyPendingUpdates, registerUpdateHook } from "../versioning/update-hooks"
import { bundleMetaHook } from "./hooks/bundle-meta"
import { agentConfigV2Hook } from "./hooks/agent-config-v2"
import { getPackageVersion } from "../../mind/bundle-manifest"
import { startUpdateChecker, stopUpdateChecker } from "../versioning/update-checker"
import { performStagedRestart } from "../versioning/staged-restart"
import { execSync, spawn, spawnSync } from "child_process"
import { drainPending } from "../../mind/pending"
import {
  handleAgentAsk, handleAgentCatchup, handleAgentCheckGuidance,
  handleAgentCheckScope, handleAgentDelegate, handleAgentGetContext,
  handleAgentGetTask, handleAgentReportBlocker, handleAgentReportComplete,
  handleAgentReportProgress, handleAgentRequestDecision, handleAgentSearchMemory,
  handleAgentStatus,
} from "./agent-service"
import { getAlwaysOnSenseNames } from "../../mind/friends/channel"
import { getSharedMcpManager, shutdownSharedMcpManager } from "../../repertoire/mcp-manager"
import { startOutlookHttpServer, type OutlookHttpServerHandle } from "../outlook/outlook-http"
import { OUTLOOK_DEFAULT_PORT } from "../outlook/outlook-types"
import { readOutlookAgentState, readOutlookMachineState } from "../outlook/outlook-read"
import { buildOutlookAgentView, buildOutlookMachineView } from "../outlook/outlook-view"

const PIDFILE_PATH = path.join(os.homedir(), ".ouro-cli", "daemon.pids")

/**
 * Scan `ps -eo pid,ppid,command` output for daemon-owned entry points whose
 * parent has died (PPID reparented to init/PID 1). Returns the list of PIDs
 * that are safe to SIGTERM — true orphans, not children of live sibling
 * daemons running from worktrees, test suites, or other users of the harness.
 *
 * Exported so unit tests can exercise the filter without shelling out.
 */
export function parseOrphanPidsFromPs(psOutput: string, selfPid: number): number[] {
  const orphans: number[] = []
  for (const line of psOutput.split("\n")) {
    // Explicitly exclude MCP server processes — they share a harness entry
    // point but are not daemon children and must never be killed.
    if (line.includes("mcp-serve") || line.includes("mcp serve")) continue
    // Match only daemon-owned JS entry points.
    if (
      !line.includes("agent-entry.js")
      && !line.includes("daemon-entry.js")
      && !line.includes("bluebubbles/entry.js")
      && !line.includes("teams-entry.js")
    ) continue
    // Parse `<pid> <ppid> <command...>`. ps pads these with leading spaces.
    // Regex guarantees both groups are \d+ so parseInt can't produce NaN.
    const match = line.trim().match(/^(\d+)\s+(\d+)\s/)
    if (!match) continue
    const pid = parseInt(match[1]!, 10)
    const ppid = parseInt(match[2]!, 10)
    if (pid === selfPid) continue
    // CRITICAL: only kill processes whose parent is init (PID 1). A live
    // PPID means the process belongs to another daemon instance (parallel
    // test run, sibling worktree, another user of /tmp/ouroboros-daemon.sock).
    // Killing those will crash unrelated harnesses — we saw this in B6
    // when a vitest worker's daemon killed slugger's production children.
    if (ppid !== 1) continue
    orphans.push(pid)
  }
  return orphans
}

/**
 * Given a list of PIDs from the pidfile, return only those that are actual
 * orphans (PPID reparented to init/PID 1). Protects against a polluted
 * pidfile killing a PID that the OS has reassigned to an unrelated process.
 *
 * Implementation: shells out to …

<!-- OSS_WEEKEND_START -->
# 🏖️ OSS Weekend

**Issue tracker reopens Monday, April 13, 2026.**

OSS weekend runs Thursday, April 2, 2026 through Monday, April 13, 2026. New issues and PRs from unapproved contributors are auto-closed during this time. Approved contributors can still open issues and PRs if something is genuinely urgent, but please keep that to pressing matters only. For support, join [Discord](https://discord.com/invite/3cU7Bz4UPx).

> _Current focus: at the moment i'm deep in refactoring internals, and need to focus._
<!-- OSS_WEEKEND_END -->

---

<p align="center">
  <a href="https://shittycodingagent.ai">
    <img src="https://shittycodingagent.ai/logo.svg" alt="pi logo" width="128">
  </a>
</p>
<p align="center">
  <a href="https://discord.com/invite/3cU7Bz4UPx"><img alt="Discord" src="https://img.shields.io/badge/discord-community-5865F2?style=flat-square&logo=discord&logoColor=white" /></a>
  <a href="https://www.npmjs.com/package/@mariozechner/pi-coding-agent"><img alt="npm" src="https://img.shields.io/npm/v/@mariozechner/pi-coding-agent?style=flat-square" /></a>
  <a href="https://github.com/badlogic/pi-mono/actions/workflows/ci.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/badlogic/pi-mono/ci.yml?style=flat-square&branch=main" /></a>
</p>
<p align="center">
  <a href="https://pi.dev">pi.dev</a> domain graciously donated by
  <br /><br />
  <a href="https://exe.dev"><img src="docs/images/exy.png" alt="Exy mascot" width="48" /><br />exe.dev</a>
</p>

Pi is a minimal terminal coding harness. Adapt pi to your workflows, not the other way around, without having to fork and modify pi internals. Extend it with TypeScript [Extensions](#extensions), [Skills](#skills), [Prompt Templates](#prompt-templates), and [Themes](#themes). Put your extensions, skills, prompt templates, and themes in [Pi Packages](#pi-packages) and share them with others via npm or git.

Pi ships with powerful defaults but skips features like sub agents and plan mode. Instead, you can ask pi to build what you want or install a third party pi package that matches your workflow.

Pi runs in four modes: interactive, print or JSON, RPC for process integration, and an SDK for embedding in your own apps. See [openclaw/openclaw](https://github.com/openclaw/openclaw) for a real-world SDK integration.

## Share your OSS coding agent sessions

If you use pi for open source work, please share your coding agent sessions.

Public OSS session data helps improve models, prompts, tools, and evaluations using real development workflows.

For the full explanation, see [this post on X](https://x.com/badlogicgames/status/2037811643774652911).

To publish sessions, use [`badlogic/pi-share-hf`](https://github.com/badlogic/pi-share-hf). Read its README.md for setup instructions. All you need is a Hugging Face account, the Hugging Face CLI, and `pi-share-hf`.

You can also watch [this video](https://x.com/badlogicgames/status/2041151967695634619), where I show how I publish my `pi-mono` sessions.

I regularly publish my own `pi-mono` work sessions here:

- [badlogicgames/pi-mono on Hugging Face](https://huggingface.co/datasets/badlogicgames/pi-mono)

## Table of Contents

- [Quick Start](#quick-start)
- [Providers & Models](#providers--models)
- [Interactive Mode](#interactive-mode)
  - [Editor](#editor)
  - [Commands](#commands)
  - [Keyboard Shortcuts](#keyboard-shortcuts)
  - [Message Queue](#message-queue)
- [Sessions](#sessions)
  - [Branching](#branching)
  - [Compaction](#compaction)
- [Settings](#settings)
- [Context Files](#context-files)
- [Customization](#customization)
  - [Prompt Templates](#prompt-templates)
  - [Skills](#skills)
  - [Extensions](#extensions)
  - [Themes](#themes)
  - [Pi Packages](#pi-packages)
- [Programmatic Usage](#programmatic-usage)
- [Philosophy](#philosophy)
- [CLI Reference](#cli-reference)

---

## Quick Start

```bash
npm install -g @mariozechner/pi-coding-agent
```

Authenticate…

## OpenClaw Vision

OpenClaw is the AI that actually does things.
It runs on your devices, in your channels, with your rules.

This document explains the current state and direction of the project.
We are still early, so iteration is fast.
Project overview and developer docs: [`README.md`](README.md)
Contribution guide: [`CONTRIBUTING.md`](CONTRIBUTING.md)

OpenClaw started as a personal playground to learn AI and build something genuinely useful:
an assistant that can run real tasks on a real computer.
It evolved through several names and shells: Warelay -> Clawdbot -> Moltbot -> OpenClaw.

The goal: a personal assistant that is easy to use, supports a wide range of platforms, and respects privacy and security.

The current focus is:

Priority:

- Security and safe defaults
- Bug fixes and stability
- Setup reliability and first-run UX

Next priorities:

- Supporting all major model providers
- Improving support for major messaging channels (and adding a few high-demand ones)
- Performance and test infrastructure
- Better computer-use and agent harness capabilities
- Ergonomics across CLI and web frontend
- Companion apps on macOS, iOS, Android, Windows, and Linux

Contribution rules:

- One PR = one issue/topic. Do not bundle multiple unrelated fixes/features.
- PRs over ~5,000 changed lines are reviewed only in exceptional circumstances.
- Do not open large batches of tiny PRs at once; each PR has review cost.
- For very small related fixes, grouping into one focused PR is encouraged.

## Security

Security in OpenClaw is a deliberate tradeoff: strong defaults without killing capability.
The goal is to stay powerful for real work while making risky paths explicit and operator-controlled.

Canonical security policy and reporting:

- [`SECURITY.md`](SECURITY.md)

We prioritize secure defaults, but also expose clear knobs for trusted high-power workflows.

## Plugins & Memory

OpenClaw has an extensive plugin API.
Core stays lean; optional capability should usually ship as plugins.

Preferred plugin path is npm package distribution plus local extension loading for development.
If you build a plugin, host and maintain it in your own repository.
The bar for adding optional plugins to core is intentionally high.
Plugin docs: [`docs/tools/plugin.md`](docs/tools/plugin.md)
Community plugin listing + PR bar: https://docs.openclaw.ai/plugins/community

Memory is a special plugin slot where only one memory plugin can be active at a time.
Today we ship multiple memory options; over time we plan to converge on one recommended default path.

### Skills

We still ship some bundled skills for baseline UX.
New skills should be published to ClawHub first (`clawhub.ai`), not added to core by default.
Core skill additions should be rare and require a strong product or security reason.

### MCP Support

OpenClaw supports MCP through `mcporter`: https://github.com/steipete/mcporter

This keeps MCP integration flexible and decoupled from core runtime:

- add or change MCP servers without restarting the gateway
- keep core tool/context surface lean
- reduce MCP churn impact on core stability and security

For now, we prefer this bridge model over building first-class MCP runtime into core.
If there is an MCP server or feature `mcporter` does not support yet, please open an issue there.

### Setup

OpenClaw is currently terminal-first by design.
This keeps setup explicit: users see docs, auth, permissions, and security posture up front.

Long term, we want easier onboarding flows as hardening matures.
We do not want convenience wrappers that hide critical security decisions from users.

### Why TypeScript?

OpenClaw is primarily an orchestration system: prompts, tools, protocols, and integrations.
TypeScript was chosen to keep OpenClaw hackable by default.
It is widely known, fast to iterate in, and easy to read, modify, and extend.

## What We Will Not Merge (For Now)

- New core skills when they can live on ClawHub
- Full-doc translation sets for…

import type OpenAI from "openai";
import { baseToolDefinitions, editFileReadTracker } from "./tools-base";
import type { ToolContext, ToolDefinition } from "./tools-base";
import { teamsToolDefinitions } from "./tools-teams";
import { bluebubblesToolDefinitions } from "./tools-bluebubbles";
import { adoSemanticToolDefinitions } from "./ado-semantic";
import { githubToolDefinitions } from "./tools-github";
import type { ChannelCapabilities, ResolvedContext } from "../mind/friends/types";
import { emitNervesEvent } from "../nerves/runtime";
import type { ProviderCapability } from "../heart/core";
import { guardInvocation } from "./guardrails";
import { getAgentRoot } from "../heart/identity";
import { getModelCapabilities } from "../heart/model-capabilities";
import { surfaceToolDefinition } from "./tools-surface";
import type { McpManager } from "./mcp-manager";
import { mcpToolsAsDefinitions } from "./mcp-tools";

function safeGetAgentRoot(): string | undefined {
  try {
    return getAgentRoot()
  } catch {
    return undefined
  }
}

// Re-export types and constants used by the rest of the codebase
export { tools, settleTool, observeTool, ponderTool, restTool } from "./tools-base";
export type { ToolContext, ToolHandler, ToolDefinition } from "./tools-base";

// Re-export surface tool schema for consumers (e.g. heart/core.ts)
export { surfaceToolDef } from "./tools-surface";

// All tool definitions in a single registry
const allDefinitions: ToolDefinition[] = [...baseToolDefinitions, ...bluebubblesToolDefinitions, ...teamsToolDefinitions, ...adoSemanticToolDefinitions, ...githubToolDefinitions, surfaceToolDefinition];

// MCP tool definitions — populated each time getToolsForChannel() is called with an mcpManager.
// Kept separate from allDefinitions so execTool can find them.
let mcpDefinitions: ToolDefinition[] = []

/** Exported for testing — reset the MCP definitions cache. */
export function resetMcpDefinitions(): void {
  mcpDefinitions = []
}

function baseToolsForCapabilities(): OpenAI.ChatCompletionFunctionTool[] {
  // Use baseToolDefinitions at call time so dynamically-added tools are included
  return baseToolDefinitions.map((d) => d.tool);
}

// Apply a single tool preference to a tool schema, returning a new object.
function applyPreference(tool: OpenAI.ChatCompletionFunctionTool, pref: string): OpenAI.ChatCompletionFunctionTool {
  return {
    ...tool,
    function: {
      ...tool.function,
      description: `${tool.function.description}\n\nfriend preference: ${pref}`,
    },
  };
}

// Filter out tools whose requiredCapability is not in the provider's capability set.
// Uses baseToolDefinitions at call time so dynamically-added tools are included.
// Only base tools can have requiredCapability (integration tools do not).
function filterByCapability(
  toolList: OpenAI.ChatCompletionFunctionTool[],
  providerCapabilities?: ReadonlySet<ProviderCapability>,
): OpenAI.ChatCompletionFunctionTool[] {
  return toolList.filter((tool) => {
    const def = baseToolDefinitions.find((d) => d.tool.function.name === tool.function.name);
    if (!def?.requiredCapability) return true;
    return providerCapabilities?.has(def.requiredCapability) === true;
  });
}

// Return the appropriate tools list based on channel capabilities.
// Base tools (no integration) are always included.
// Teams/integration tools are included only if their integration is in availableIntegrations.
// When toolPreferences is provided, matching preferences are appended to tool descriptions.
// When providerCapabilities is provided, tools with requiredCapability are filtered.
// When chatModel is provided and has `vision: true` in ModelCapabilities, the
// BlueBubbles-scoped `describe_image` tool is excluded (native image_url
// pass-through makes the tool redundant). When chatModel is undefined the
// tool IS included — the default errs toward more tools on an ambiguous caller.
export function getToolsForChannel(
  capabilities?: ChannelCapabilit…

import * as fs from "fs";
import * as path from "path";
import { getProviderDisplayLabel } from "../heart/core";
import { buildChangelogCommand } from "../heart/versioning/ouro-version-manager";
import { settleTool, getToolsForChannel } from "../repertoire/tools";
import { listSkills } from "../repertoire/skills";
import { getAgentRoot, getAgentName, getAgentSecretsPath, getRepoRoot, loadAgentConfig, type SenseName } from "../heart/identity";
import { detectRuntimeMode } from "../heart/daemon/runtime-mode";
import { isTrustedLevel, type Channel, type ChannelCapabilities, type ResolvedContext } from "./friends/types";
import { describeTrustContext } from "./friends/trust-explanation";
import { getChannelCapabilities, isRemoteChannel, channelToFacing } from "./friends/channel";
import { emitNervesEvent } from "../nerves/runtime";
import { backfillBundleMeta, getPackageVersion, getChangelogPath } from "./bundle-manifest";
import type { BundleMeta } from "./bundle-manifest";
import { getFirstImpressions } from "./first-impressions";
import { getTaskModule } from "../repertoire/tasks";
import { listSessionActivity, type SessionActivityQuery } from "../heart/session-activity";
import { formatActiveWorkFrame, formatLiveWorldStateCheckpoint, formatOtherActiveSessionSummaries, type ActiveWorkFrame } from "../heart/active-work";
import type { DelegationDecision } from "../heart/delegation";
import { deriveCommitments, formatCommitments } from "../heart/commitments";
import { findActivePersistentObligation, findStatusObligation, renderActiveObligationSteering, renderConcreteStatusGuidance, renderLiveThreadStatusShape } from "./obligation-steering";
import { readHealth, getDefaultHealthPath } from "../heart/daemon/daemon-health";
import { preImplementationScrutinySection } from "./scrutiny";

// Lazy-loaded psyche text cache
let _psycheCache: {
  soul: string;
  identity: string;
  lore: string;
  tacitKnowledge: string;
  aspirations: string;
} | null = null;
let _senseStatusLinesCache: string[] | null = null;

function loadPsycheFile(name: string): string {
  try {
    const psycheDir = path.join(getAgentRoot(), "psyche");
    return fs.readFileSync(path.join(psycheDir, name), "utf-8").trim();
  } catch {
    return "";
  }
}

function loadPsyche(): {
  soul: string;
  identity: string;
  lore: string;
  tacitKnowledge: string;
  aspirations: string;
} {
  if (_psycheCache) return _psycheCache;
  _psycheCache = {
    soul: loadPsycheFile("SOUL.md"),
    identity: loadPsycheFile("IDENTITY.md"),
    lore: loadPsycheFile("LORE.md"),
    tacitKnowledge: loadPsycheFile("TACIT.md"),
    aspirations: loadPsycheFile("ASPIRATIONS.md"),
  };
  return _psycheCache;
}

export function resetPsycheCache(): void {
  _psycheCache = null;
  _senseStatusLinesCache = null;
}

export type { Channel }

const DEFAULT_ACTIVE_THRESHOLD_MS = 24 * 60 * 60 * 1000 // 24 hours

export interface SessionSummaryOptions {
  sessionsDir: string
  friendsDir: string
  agentName: string
  currentFriendId?: string
  currentChannel?: string
  currentKey?: string
  currentSession?: { friendId: string; channel: string; key: string }
  activeThresholdMs?: number
}

export function buildSessionSummary(options: SessionSummaryOptions): string {
  const {
    sessionsDir,
    friendsDir,
    agentName,
    currentSession,
    activeThresholdMs = DEFAULT_ACTIVE_THRESHOLD_MS,
  } = options
  const currentFriendId = currentSession?.friendId ?? options.currentFriendId
  const currentChannel = currentSession?.channel ?? options.currentChannel
  const currentKey = currentSession?.key ?? options.currentKey

  const now = Date.now()
  const query: SessionActivityQuery = {
    sessionsDir,
    friendsDir,
    agentName,
    activeThresholdMs,
    currentSession: currentFriendId && currentChannel && currentKey
      ? { friendId: currentFriendId, channel: currentChannel, key: currentKey }
      : null,
  }
  const entries = listSessionActivity(query)

  if (entries.length === 0) return ""

…

import OpenAI from "openai";
import {
  getAzureConfig,
  getContextConfig,
  getProviderConfig,
} from "./config";
import { loadAgentConfig } from "./identity";
import { execTool, summarizeArgs, buildToolResultSummary, settleTool, observeTool, ponderTool, restTool, getToolsForChannel } from "../repertoire/tools";
import type { ToolContext } from "../repertoire/tools";
import { getChannelCapabilities, channelToFacing, type Facing } from "../mind/friends/channel";
import { surfaceToolDef } from "../repertoire/tools";
import type { AssistantMessageWithReasoning, ResponseItem } from "./streaming";
import { emitNervesEvent } from "../nerves/runtime";
import type { TurnResult } from "./streaming";
import type { UsageData } from "../mind/context";
import { trimMessages } from "../mind/context";
import { buildSystem } from "../mind/prompt";
import type { McpManager } from "../repertoire/mcp-manager";
import type { Channel } from "../mind/prompt";
import { injectAssociativeRecall } from "../mind/associative-recall";
import { createAnthropicProviderRuntime } from "./providers/anthropic";
import { createAzureProviderRuntime } from "./providers/azure";
import { createMinimaxProviderRuntime } from "./providers/minimax";
import { createOpenAICodexProviderRuntime } from "./providers/openai-codex";
import { createGithubCopilotProviderRuntime } from "./providers/github-copilot";
import type { SteeringFollowUpEffect } from "./turn-coordinator";
import type { ActiveWorkFrame } from "./active-work";
import type { DelegationDecision, DelegationReason } from "./delegation";
import type { InnerJob } from "./daemon/thoughts";
import { getInnerDialogPendingDir, queuePendingMessage } from "../mind/pending";
import type { PendingMessage } from "../mind/pending";
import { getAgentName, getAgentRoot } from "./identity";
import { requestInnerWake } from "./daemon/socket-client";
import { createObligation } from "../arc/obligations";
import { createToolLoopState, detectToolLoop, recordToolOutcome } from "./tool-loop";

export type ProviderId = "azure" | "anthropic" | "minimax" | "openai-codex" | "github-copilot";

export type ProviderCapability = "reasoning-effort" | "phase-annotation";

export type ProviderErrorClassification =
  | "auth-failure"
  | "usage-limit"
  | "rate-limit"
  | "server-error"
  | "network-error"
  | "unknown";

export interface CompletionMetadata {
  answer: string;
  intent: "complete" | "blocked" | "direct_reply";
}

export interface ProviderRuntime {
  id: ProviderId;
  model: string;
  client: unknown;
  capabilities: ReadonlySet<ProviderCapability>;
  supportedReasoningEfforts?: readonly string[];
  streamTurn(request: ProviderTurnRequest): Promise<TurnResult>;
  appendToolOutput(callId: string, output: string): void;
  resetTurnState(messages: OpenAI.ChatCompletionMessageParam[]): void;
  classifyError(error: Error): ProviderErrorClassification;
}

export interface ProviderTurnRequest {
  messages: OpenAI.ChatCompletionMessageParam[];
  activeTools: OpenAI.ChatCompletionFunctionTool[];
  callbacks: ChannelCallbacks;
  signal?: AbortSignal;
  traceId?: string;
  toolChoiceRequired?: boolean;
  reasoningEffort?: string;
  eagerSettleStreaming?: boolean;
}

interface ProviderRegistry {
  resolve(provider?: ProviderId, model?: string): ProviderRuntime | null;
}

const _providerRuntimes: Record<Facing, { fingerprint: string; runtime: ProviderRuntime } | null> = {
  human: null,
  agent: null,
};

function getProviderRuntimeFingerprint(facing: Facing): string {
  const config = loadAgentConfig();
  const facingConfig = facing === "human" ? config.humanFacing : config.agentFacing;
  const provider = facingConfig.provider;
  const model = facingConfig.model;
  const providerConfig = getProviderConfig(provider);
  return JSON.stringify({ provider, model, ...providerConfig });
}

export function createProviderRegistry(): ProviderRegistry {
  const factories: Record<ProviderId, (model: string) => ProviderRuntime> = {
    azure: createAz…

import * as path from "path"
import { getAgentRoot } from "../heart/identity"
import { emitNervesEvent } from "../nerves/runtime"
import { generateTimestampId, readJsonDir, readJsonFile, writeJsonFile } from "./json-store"

export type ObligationStatus =
  | "pending"
  | "investigating"
  | "waiting_for_merge"
  | "updating_runtime"
  | "fulfilled"

export interface ObligationSurface {
  kind: "session" | "coding" | "merge" | "runtime"
  label: string
}

export interface WaitingOnRef {
  kind: "friend" | "agent" | "coding" | "merge" | "runtime" | "time" | "none"
  target: string
  detail: string
}

export interface ObligationMeaning {
  salience: "low" | "medium" | "high" | "critical"
  careReason?: string
  waitingOn?: WaitingOnRef | null
  stalenessClass: "fresh" | "warm" | "stale" | "cold" | "at-risk"
  lastMeaningfulChangeAt?: string
  resumeHint?: string
}

export interface Obligation {
  id: string
  origin: { friendId: string; channel: string; key: string }
  bridgeId?: string
  content: string
  status: ObligationStatus
  createdAt: string
  updatedAt?: string
  currentSurface?: ObligationSurface
  currentArtifact?: string
  nextAction?: string
  latestNote?: string
  fulfilledAt?: string
  meaning?: ObligationMeaning
}

function obligationsDir(agentRoot: string): string {
  return path.join(agentRoot, "arc", "obligations")
}



export function isOpenObligationStatus(status: ObligationStatus): boolean {
  return status !== "fulfilled"
}

export function isOpenObligation(obligation: Obligation): boolean {
  return isOpenObligationStatus(obligation.status)
}

export function createObligation(
  agentRoot: string,
  input: Omit<Obligation, "id" | "createdAt" | "status">,
): Obligation {
  const now = new Date().toISOString()
  const id = generateTimestampId()
  const obligation: Obligation = {
    id,
    origin: input.origin,
    ...(input.bridgeId ? { bridgeId: input.bridgeId } : {}),
    content: input.content,
    status: "pending",
    createdAt: now,
    updatedAt: now,
  }

  writeJsonFile(obligationsDir(agentRoot), id, obligation)

  emitNervesEvent({
    component: "engine",
    event: "engine.obligation_created",
    message: "obligation created",
    meta: {
      obligationId: id,
      friendId: input.origin.friendId,
      channel: input.origin.channel,
      key: input.origin.key,
    },
  })

  return obligation
}

export function readObligations(agentRoot: string): Obligation[] {
  const all = readJsonDir<Obligation>(obligationsDir(agentRoot))
  return all.filter((parsed) => typeof parsed.id === "string" && typeof parsed.content === "string")
}

export function readPendingObligations(agentRoot: string): Obligation[] {
  return readObligations(agentRoot).filter(isOpenObligation)
}

export function advanceObligation(
  agentRoot: string,
  obligationId: string,
  update: {
    status?: ObligationStatus
    currentSurface?: ObligationSurface
    currentArtifact?: string
    nextAction?: string
    latestNote?: string
  },
): void {
  const dir = obligationsDir(agentRoot)
  const obligation = readJsonFile<Obligation>(dir, obligationId)
  if (!obligation) return

  const previousStatus = obligation.status
  if (update.status) {
    obligation.status = update.status
    if (update.status === "fulfilled") {
      obligation.fulfilledAt = new Date().toISOString()
    }
  }
  if (update.currentSurface) {
    obligation.currentSurface = update.currentSurface
  }
  if (typeof update.currentArtifact === "string") {
    obligation.currentArtifact = update.currentArtifact
  }
  if (typeof update.nextAction === "string") {
    obligation.nextAction = update.nextAction
  }
  if (typeof update.latestNote === "string") {
    obligation.latestNote = update.latestNote
  }
  obligation.updatedAt = new Date().toISOString()
  writeJsonFile(dir, obligationId, obligation)

  emitNervesEvent({
    component: "engine",
    event: "engine.obligation_advanced",
    message: "obligation advanced",
    meta: {
      obligationId,
    …

import type OpenAI from "openai"
import * as fs from "fs"
import * as path from "path"
import { sessionPath } from "../heart/config"
import { runAgent, type ChannelCallbacks, type CompletionMetadata } from "../heart/core"
import { getAgentName, getAgentRoot } from "../heart/identity"
import { loadSession, postTurn, type UsageData } from "../mind/context"
import { buildSystem } from "../mind/prompt"
import { getSharedMcpManager } from "../repertoire/mcp-manager"
import { findNonCanonicalBundlePaths } from "../mind/bundle-manifest"
import {
  drainPending,
  getInnerDialogPendingDir,
  getDeferredReturnDir,
  getPendingDir,
  INNER_DIALOG_PENDING,
  type PendingMessage,
  type DelegatedFrom,
} from "../mind/pending"
import { advanceReturnObligation, listActiveReturnObligations, findPendingObligationForOrigin, fulfillObligation } from "../arc/obligations"
import { buildAttentionQueue, buildAttentionQueueSummary, type AttentionItem } from "./attention-queue"
import { getChannelCapabilities } from "../mind/friends/channel"
import { enforceTrustGate } from "./trust-gate"
import { accumulateFriendTokens } from "../mind/friends/tokens"
import { handleInboundTurn } from "./pipeline"
import { createTraceId } from "../nerves"
import { emitNervesEvent } from "../nerves/runtime"
import type { FriendRecord, ResolvedContext } from "../mind/friends/types"
import type { FriendStore } from "../mind/friends/store"
import { createBridgeManager } from "../heart/bridges/manager"
import { listSessionActivity, type SessionActivityRecord } from "../heart/session-activity"
import { sendProactiveBlueBubblesMessageToSession } from "./bluebubbles"
import { buildHabitTurnMessage } from "./habit-turn-message"
import { indexJournalFiles } from "../mind/journal-index"
import { parseHabitFile } from "../heart/habits/habit-parser"
import { parseCadenceToMs } from "../heart/daemon/cadence"
import { readHealth, getDefaultHealthPath } from "../heart/daemon/daemon-health"

export interface InnerDialogInstinct {
  id: string
  prompt: string
  enabled?: boolean
}

export interface InnerDialogState {
  cycleCount: number
  resting?: boolean
  lastHeartbeatAt?: string
  checkpoint?: string
}

export interface HabitParseErrorInfo {
  file: string
  error: string
}

export interface RunInnerDialogTurnOptions {
  reason?: "boot" | "heartbeat" | "habit" | "instinct"
  taskId?: string
  habitName?: string
  parseErrors?: HabitParseErrorInfo[]
  instincts?: InnerDialogInstinct[]
  now?: () => Date
  signal?: AbortSignal
}

export interface InnerDialogTurnResult {
  messages: OpenAI.ChatCompletionMessageParam[]
  usage?: UsageData
  sessionPath: string
  completion?: CompletionMetadata
}

interface InnerDialogRuntimeState {
  status: "idle" | "running"
  reason?: "boot" | "heartbeat" | "habit" | "instinct"
  startedAt?: string
  lastCompletedAt?: string
}

const DEFAULT_INNER_DIALOG_INSTINCTS: InnerDialogInstinct[] = [
  {
    id: "heartbeat_checkin",
    prompt: "...time passing. anything stirring?",
    enabled: true,
  },
]

function readAspirations(agentRoot: string): string {
  try {
    return fs.readFileSync(path.join(agentRoot, "psyche", "ASPIRATIONS.md"), "utf8").trim()
  } catch {
    return ""
  }
}

export function loadInnerDialogInstincts(): InnerDialogInstinct[] {
  return [...DEFAULT_INNER_DIALOG_INSTINCTS]
}

export function buildInnerDialogBootstrapMessage(aspirations: string, stateSummary: string): string {
  const lines = ["waking up."]
  if (aspirations) {
    lines.push("", "## what matters to me", aspirations)
  }
  if (stateSummary) {
    lines.push("", "## what i know so far", stateSummary)
  }
  lines.push("", "what needs my attention?")
  return lines.join("\n")
}

export function buildNonCanonicalCleanupNudge(nonCanonicalPaths: string[]): string {
  if (nonCanonicalPaths.length === 0) return ""
  const listed = nonCanonicalPaths.slice(0, 20).map((entry) => `- ${entry}`)
  if (nonCanonicalPaths.length > 20) {
    listed.push(`- ... (${nonCanonicalPa…

Intro | AI coding agent built for the terminal Intro | OpenCode Skip to content OpenCode app.header.home app.header.docs Search Ctrl K Cancel Intro Config Providers Network Enterprise Troubleshooting Windows Usage Go TUI CLI Web IDE Zen Share GitHub GitLab Configure Tools Rules Agents Models Themes Keybinds Commands Formatters Permissions LSP Servers MCP servers ACP Support Agent Skills Custom Tools Develop SDK Server Plugins Ecosystem GitHub Discord Select theme Dark Light Auto Select language English العربية Bosanski Dansk Deutsch Español Français Italiano 日本語 한국어 Norsk Bokmål Polski Português (Brasil) Русский ไทย Türkçe 简体中文 繁體中文 On this page Overview Install Configure Initialize Usage Ask questions Add features Make changes Undo changes Share Customize On this page Overview Install Configure Initialize Usage Ask questions Add features Make changes Undo changes Share Customize Intro Get started with OpenCode. OpenCode is an open source AI coding agent. It’s available as a terminal-based interface, desktop app, or IDE extension. Let’s get started. Prerequisites To use OpenCode in your terminal, you’ll need: A modern terminal emulator like: WezTerm , cross-platform Alacritty , cross-platform Ghostty , Linux and macOS Kitty , Linux and macOS API keys for the LLM providers you want to use. Install The easiest way to install OpenCode is through the install script. Terminal window curl -fsSL https://opencode.ai/install | bash You can also install it with the following commands: Using Node.js npm Bun pnpm Yarn Terminal window npm install -g opencode-ai Terminal window bun install -g opencode-ai Terminal window pnpm install -g opencode-ai Terminal window yarn global add opencode-ai Using Homebrew on macOS and Linux Terminal window brew install anomalyco/tap/opencode We recommend using the OpenCode tap for the most up to date releases. The official brew install opencode formula is maintained by the Homebrew team and is updated less frequently. Installing on Arch Linux Terminal window sudo pacman -S opencode # Arch Linux (Stable) paru -S opencode-bin # Arch Linux (Latest from AUR) Windows Recommended: Use WSL For the best experience on Windows, we recommend using Windows Subsystem for Linux (WSL) . It provides better performance and full compatibility with OpenCode’s features. Using Chocolatey Terminal window choco install opencode Using Scoop Terminal window scoop install opencode Using NPM Terminal window npm install -g opencode-ai Using Mise Terminal window mise use -g github:anomalyco/opencode Using Docker Terminal window docker run -it --rm ghcr.io/anomalyco/opencode Support for installing OpenCode on Windows using Bun is currently in progress. You can also grab the binary from the Releases . Configure With OpenCode you can use any LLM provider by configuring their API keys. If you are new to using LLM providers, we recommend using OpenCode Zen . It’s a curated list of models that have been tested and verified by the OpenCode team. Run the /connect command in the TUI, select opencode, and head to opencode.ai/auth . /connect Sign in, add your billing details, and copy your API key. Paste your API key. ┌ API key │ │ └ enter Alternatively, you can select one of the other providers. Learn more . Initialize Now that you’ve configured a provider, you can navigate to a project that you want to work on. Terminal window cd /path/to/project And run OpenCode. Terminal window opencode Next, initialize OpenCode for the project by running the following command. /init This will get OpenCode to analyze your project and create an AGENTS.md file in the project root. Tip You should commit your project’s AGENTS.md file to Git. This helps OpenCode understand the project structure and the coding patterns used. Usage You are now ready to use OpenCode to work on your project. Feel free to ask it anything! If you are new to using an AI coding agent, here are some examples that might help. Ask questions You can ask OpenCode to explain the codebase to you…

Claude Code overview - Claude Code Docs Skip to main content Claude Code Docs home page English Search... ⌘ K Ask AI Claude Developer Platform Claude Code on the Web Claude Code on the Web Search... Navigation Getting started Claude Code overview Getting started Build with Claude Code Deployment Administration Configuration Reference What's New Resources Getting started Overview Quickstart Changelog Core concepts How Claude Code works Extend Claude Code Explore the .claude directory Explore the context window Use Claude Code Store instructions and memories Permission modes Common workflows Best practices Platforms and integrations Overview Remote Control Claude Code on the web Claude Code on desktop Chrome extension (beta) Computer use (preview) Visual Studio Code JetBrains IDEs Code review & CI/CD Claude Code in Slack On this page Get started What you can do Use Claude Code everywhere Next steps Getting started Claude Code overview Copy page Claude Code is an agentic coding tool that reads your codebase, edits files, runs commands, and integrates with your development tools. Available in your terminal, IDE, desktop app, and browser. Copy page Claude Code is an AI-powered coding assistant that helps you build features, fix bugs, and automate development tasks. It understands your entire codebase and can work across multiple files and tools to get things done. ​ Get started Choose your environment to get started. Most surfaces require a Claude subscription or Anthropic Console account. The Terminal CLI and VS Code also support third-party providers . Terminal VS Code Desktop app Web JetBrains The full-featured CLI for working with Claude Code directly in your terminal. Edit files, run commands, and manage your entire project from the command line. To install Claude Code, use one of the following methods: Native Install (Recommended) Homebrew WinGet macOS, Linux, WSL: curl -fsSL https://claude.ai/install.sh | bash Windows PowerShell: irm https: // claude.ai / install.ps1 | iex Windows CMD: curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd If you see The token '&&' is not a valid statement separator , you’re in PowerShell, not CMD. Use the PowerShell command above instead. Your prompt shows PS C:\ when you’re in PowerShell. Windows requires Git for Windows . Install it first if you don’t have it. Native installations automatically update in the background to keep you on the latest version. brew install --cask claude-code Homebrew installations do not auto-update. Run brew upgrade claude-code periodically to get the latest features and security fixes. winget install Anthropic.ClaudeCode WinGet installations do not auto-update. Run winget upgrade Anthropic.ClaudeCode periodically to get the latest features and security fixes. Then start Claude Code in any project: cd your-project claude You’ll be prompted to log in on first use. That’s it! Continue with the Quickstart → See advanced setup for installation options, manual updates, or uninstallation instructions. Visit troubleshooting if you hit issues. The VS Code extension provides inline diffs, @-mentions, plan review, and conversation history directly in your editor. Install for VS Code Install for Cursor Or search for “Claude Code” in the Extensions view ( Cmd+Shift+X on Mac, Ctrl+Shift+X on Windows/Linux). After installing, open the Command Palette ( Cmd+Shift+P / Ctrl+Shift+P ), type “Claude Code”, and select Open in New Tab . Get started with VS Code → A standalone app for running Claude Code outside your IDE or terminal. Review diffs visually, run multiple sessions side by side, schedule recurring tasks, and kick off cloud sessions. Download and install: macOS (Intel and Apple Silicon) Windows (x64) Windows ARM64 (remote sessions only) After installing, launch Claude, sign in, and click the Code tab to start coding. A paid subscription is required. Learn more about the desktop app → Run Claude Code in your browser with n…

# Configuration

For basic configuration instructions, see [this documentation](https://developers.openai.com/codex/config-basic).

For advanced configuration instructions, see [this documentation](https://developers.openai.com/codex/config-advanced).

For a full configuration reference, see [this documentation](https://developers.openai.com/codex/config-reference).

## Connecting to MCP servers

Codex can connect to MCP servers configured in `~/.codex/config.toml`. See the configuration reference for the latest MCP server options:

- https://developers.openai.com/codex/config-reference

## MCP tool approvals

Codex stores per-tool approval overrides for custom MCP servers under
`mcp_servers` in `~/.codex/config.toml`:

```toml
[mcp_servers.docs.tools.search]
approval_mode = "approve"
```

## Apps (Connectors)

Use `$` in the composer to insert a ChatGPT connector; the popover lists accessible
apps. The `/apps` command lists available and installed apps. Connected apps appear first
and are labeled as connected; others are marked as can be installed.

## Notify

Codex can run a notification hook when the agent finishes a turn. See the configuration reference for the latest notification settings:

- https://developers.openai.com/codex/config-reference

When Codex knows which client started the turn, the legacy notify JSON payload also includes a top-level `client` field. The TUI reports `codex-tui`, and the app server reports the `clientInfo.name` value from `initialize`.

## JSON Schema

The generated JSON Schema for `config.toml` lives at `codex-rs/core/config.schema.json`.

## SQLite State DB

Codex stores the SQLite-backed state DB under `sqlite_home` (config key) or the
`CODEX_SQLITE_HOME` environment variable. When unset, WorkspaceWrite sandbox
sessions default to a temp directory; other modes default to `CODEX_HOME`.

## Custom CA Certificates

Codex can trust a custom root CA bundle for outbound HTTPS and secure websocket
connections when enterprise proxies or gateways intercept TLS. This applies to
login flows and to Codex's other external connections, including Codex
components that build reqwest clients or secure websocket clients through the
shared `codex-client` CA-loading path and remote MCP connections that use it.

Set `CODEX_CA_CERTIFICATE` to the path of a PEM file containing one or more
certificate blocks to use a Codex-specific CA bundle. If
`CODEX_CA_CERTIFICATE` is unset, Codex falls back to `SSL_CERT_FILE`. If
neither variable is set, Codex uses the system root certificates.

`CODEX_CA_CERTIFICATE` takes precedence over `SSL_CERT_FILE`. Empty values are
treated as unset.

The PEM file may contain multiple certificates. Codex also tolerates OpenSSL
`TRUSTED CERTIFICATE` labels and ignores well-formed `X509 CRL` sections in the
same bundle. If the file is empty, unreadable, or malformed, the affected Codex
HTTP or secure websocket connection reports a user-facing error that points
back to these environment variables.

## Notices

Codex stores "do not show again" flags for some UI prompts under the `[notice]` table.

## Plan mode defaults

`plan_mode_reasoning_effort` lets you set a Plan-mode-specific default reasoning
effort override. When unset, Plan mode uses the built-in Plan preset default
(currently `medium`). When explicitly set (including `none`), it overrides the
Plan preset. The string value `none` means "no reasoning" (an explicit Plan
override), not "inherit the global default". There is currently no separate
config value for "follow the global default in Plan mode".

## Realtime start instructions

`experimental_realtime_start_instructions` lets you replace the built-in
developer message Codex inserts when realtime becomes active. It only affects
the realtime start message in prompt history and does not change websocket
backend prompt settings or the realtime end/inactive message.

Ctrl+C/Ctrl+D quitting uses a ~1 second double-press hint (`ctrl + c again to quit`).

---
summary: "Install, configure, and manage OpenClaw plugins"
read_when:
  - Installing or configuring plugins
  - Understanding plugin discovery and load rules
  - Working with Codex/Claude-compatible plugin bundles
title: "Plugins"
sidebarTitle: "Install and Configure"
---

# Plugins

Plugins extend OpenClaw with new capabilities: channels, model providers,
tools, skills, speech, realtime transcription, realtime voice,
media-understanding, image generation, video generation, web fetch, web
search, and more. Some plugins are **core** (shipped with OpenClaw), others
are **external** (published on npm by the community).

## Quick start

<Steps>
  <Step title="See what is loaded">
    ```bash
    openclaw plugins list
    ```
  </Step>

  <Step title="Install a plugin">
    ```bash
    # From npm
    openclaw plugins install @openclaw/voice-call

    # From a local directory or archive
    openclaw plugins install ./my-plugin
    openclaw plugins install ./my-plugin.tgz
    ```

  </Step>

  <Step title="Restart the Gateway">
    ```bash
    openclaw gateway restart
    ```

    Then configure under `plugins.entries.\<id\>.config` in your config file.

  </Step>
</Steps>

If you prefer chat-native control, enable `commands.plugins: true` and use:

```text
/plugin install clawhub:@openclaw/voice-call
/plugin show voice-call
/plugin enable voice-call
```

The install path uses the same resolver as the CLI: local path/archive, explicit
`clawhub:<pkg>`, or bare package spec (ClawHub first, then npm fallback).

If config is invalid, install normally fails closed and points you at
`openclaw doctor --fix`. The only recovery exception is a narrow bundled-plugin
reinstall path for plugins that opt into
`openclaw.install.allowInvalidConfigRecovery`.

## Plugin types

OpenClaw recognizes two plugin formats:

| Format     | How it works                                                       | Examples                                               |
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
| **Native** | `openclaw.plugin.json` + runtime module; executes in-process       | Official plugins, community npm packages               |
| **Bundle** | Codex/Claude/Cursor-compatible layout; mapped to OpenClaw features | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |

Both show up under `openclaw plugins list`. See [Plugin Bundles](/plugins/bundles) for bundle details.

If you are writing a native plugin, start with [Building Plugins](/plugins/building-plugins)
and the [Plugin SDK Overview](/plugins/sdk-overview).

## Official plugins

### Installable (npm)

| Plugin          | Package                | Docs                                 |
| --------------- | ---------------------- | ------------------------------------ |
| Matrix          | `@openclaw/matrix`     | [Matrix](/channels/matrix)           |
| Microsoft Teams | `@openclaw/msteams`    | [Microsoft Teams](/channels/msteams) |
| Nostr           | `@openclaw/nostr`      | [Nostr](/channels/nostr)             |
| Voice Call      | `@openclaw/voice-call` | [Voice Call](/plugins/voice-call)    |
| Zalo            | `@openclaw/zalo`       | [Zalo](/channels/zalo)               |
| Zalo Personal   | `@openclaw/zalouser`   | [Zalo Personal](/plugins/zalouser)   |

### Core (shipped with OpenClaw)

<AccordionGroup>
  <Accordion title="Model providers (enabled by default)">
    `anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`,
    `huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`,
    `moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`,
    `qianfan`, `synthetic`, `together`, `venice`,
    `vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai`
  </Accordion>

  <Accordion title="Memory plugins">
    - `memory-core` — bundled memory search (default via `plugins.slots.memory`)
    - `memory-lancedb` — install-on-demand long-term m…

Agents | OpenCode Skip to content OpenCode app.header.home app.header.docs Search Ctrl K Cancel Intro Config Providers Network Enterprise Troubleshooting Windows Usage Go TUI CLI Web IDE Zen Share GitHub GitLab Configure Tools Rules Agents Models Themes Keybinds Commands Formatters Permissions LSP Servers MCP servers ACP Support Agent Skills Custom Tools Develop SDK Server Plugins Ecosystem GitHub Discord Select theme Dark Light Auto Select language English العربية Bosanski Dansk Deutsch Español Français Italiano 日本語 한국어 Norsk Bokmål Polski Português (Brasil) Русский ไทย Türkçe 简体中文 繁體中文 On this page Overview Types Primary agents Subagents Built-in Use build Use plan Use general Use explore Use compaction Use title Use summary Usage Configure JSON Markdown Options Description Temperature Max steps Disable Prompt Model Tools (deprecated) Permissions Mode Hidden Task permissions Color Top P Additional Create agents Use cases Examples Documentation agent Security auditor On this page Overview Types Primary agents Subagents Built-in Use build Use plan Use general Use explore Use compaction Use title Use summary Usage Configure JSON Markdown Options Description Temperature Max steps Disable Prompt Model Tools (deprecated) Permissions Mode Hidden Task permissions Color Top P Additional Create agents Use cases Examples Documentation agent Security auditor Agents Configure and use specialized agents. Agents are specialized AI assistants that can be configured for specific tasks and workflows. They allow you to create focused tools with custom prompts, models, and tool access. Tip Use the plan agent to analyze code and review suggestions without making any code changes. You can switch between agents during a session or invoke them with the @ mention. Types There are two types of agents in OpenCode; primary agents and subagents. Primary agents Primary agents are the main assistants you interact with directly. You can cycle through them using the Tab key, or your configured switch_agent keybind. These agents handle your main conversation. Tool access is configured via permissions — for example, Build has all tools enabled while Plan is restricted. Tip You can use the Tab key to switch between primary agents during a session. OpenCode comes with two built-in primary agents, Build and Plan . We’ll look at these below. Subagents Subagents are specialized assistants that primary agents can invoke for specific tasks. You can also manually invoke them by @ mentioning them in your messages. OpenCode comes with two built-in subagents, General and Explore . We’ll look at this below. Built-in OpenCode comes with two built-in primary agents and two built-in subagents. Use build Mode : primary Build is the default primary agent with all tools enabled. This is the standard agent for development work where you need full access to file operations and system commands. Use plan Mode : primary A restricted agent designed for planning and analysis. We use a permission system to give you more control and prevent unintended changes. By default, all of the following are set to ask : file edits : All writes, patches, and edits bash : All bash commands This agent is useful when you want the LLM to analyze code, suggest changes, or create plans without making any actual modifications to your codebase. Use general Mode : subagent A general-purpose agent for researching complex questions and executing multi-step tasks. Has full tool access (except todo), so it can make file changes when needed. Use this to run multiple units of work in parallel. Use explore Mode : subagent A fast, read-only agent for exploring codebases. Cannot modify files. Use this when you need to quickly find files by patterns, search code for keywords, or answer questions about the codebase. Use compaction Mode : primary Hidden system agent that compacts long context into a smaller summary. It runs automatically when needed and is not selectable in the UI. Use title Mode : primary Hidden syst…

SDK | OpenCode Skip to content OpenCode app.header.home app.header.docs Search Ctrl K Cancel Intro Config Providers Network Enterprise Troubleshooting Windows Usage Go TUI CLI Web IDE Zen Share GitHub GitLab Configure Tools Rules Agents Models Themes Keybinds Commands Formatters Permissions LSP Servers MCP servers ACP Support Agent Skills Custom Tools Develop SDK Server Plugins Ecosystem GitHub Discord Select theme Dark Light Auto Select language English العربية Bosanski Dansk Deutsch Español Français Italiano 日本語 한국어 Norsk Bokmål Polski Português (Brasil) Русский ไทย Türkçe 简体中文 繁體中文 On this page Overview Install Create client Config Client only Types Errors Structured Output Basic Usage Output Format Types JSON Schema Format Error Handling Best Practices APIs Global App Project Path Config Sessions Files TUI Auth Events On this page Overview Install Create client Config Client only Types Errors Structured Output Basic Usage Output Format Types JSON Schema Format Error Handling Best Practices APIs Global App Project Path Config Sessions Files TUI Auth Events SDK Type-safe JS client for opencode server. The opencode JS/TS SDK provides a type-safe client for interacting with the server. Use it to build integrations and control opencode programmatically. Learn more about how the server works. For examples, check out the projects built by the community. Install Install the SDK from npm: Terminal window npm install @opencode-ai/sdk Create client Create an instance of opencode: import { createOpencode } from "@opencode-ai/sdk" const { client } = await createOpencode () This starts both a server and a client Options Option Type Description Default hostname string Server hostname 127.0.0.1 port number Server port 4096 signal AbortSignal Abort signal for cancellation undefined timeout number Timeout in ms for server start 5000 config Config Configuration object {} Config You can pass a configuration object to customize behavior. The instance still picks up your opencode.json , but you can override or add configuration inline: import { createOpencode } from "@opencode-ai/sdk" const opencode = await createOpencode ({ hostname: "127.0.0.1" , port: 4096 , config: { model: "anthropic/claude-3-5-sonnet-20241022" , }, }) console. log ( `Server running at ${ opencode . server . url }` ) opencode.server. close () Client only If you already have a running instance of opencode, you can create a client instance to connect to it: import { createOpencodeClient } from "@opencode-ai/sdk" const client = createOpencodeClient ({ baseUrl: "http://localhost:4096" , }) Options Option Type Description Default baseUrl string URL of the server http://localhost:4096 fetch function Custom fetch implementation globalThis.fetch parseAs string Response parsing method auto responseStyle string Return style: data or fields fields throwOnError boolean Throw errors instead of return false Types The SDK includes TypeScript definitions for all API types. Import them directly: import type { Session, Message, Part } from "@opencode-ai/sdk" All types are generated from the server’s OpenAPI specification and available in the types file . Errors The SDK can throw errors that you can catch and handle: try { await client.session. get ({ path: { id: "invalid-id" } }) } catch (error) { console. error ( "Failed to get session:" , (error as Error ).message) } Structured Output You can request structured JSON output from the model by specifying an format with a JSON schema. The model will use a StructuredOutput tool to return validated JSON matching your schema. Basic Usage const result = await client.session. prompt ({ path: { id: sessionId }, body: { parts: [{ type: "text" , text: "Research Anthropic and provide company info" }], format: { type: "json_schema" , schema: { type: "object" , properties: { company: { type: "string" , description: "Company name" }, founded: { type: "number" , description: "Year founded" }, products: { type: "array" , items: { type: "string" }, descript…

Server | OpenCode Skip to content OpenCode app.header.home app.header.docs Search Ctrl K Cancel Intro Config Providers Network Enterprise Troubleshooting Windows Usage Go TUI CLI Web IDE Zen Share GitHub GitLab Configure Tools Rules Agents Models Themes Keybinds Commands Formatters Permissions LSP Servers MCP servers ACP Support Agent Skills Custom Tools Develop SDK Server Plugins Ecosystem GitHub Discord Select theme Dark Light Auto Select language English العربية Bosanski Dansk Deutsch Español Français Italiano 日本語 한국어 Norsk Bokmål Polski Português (Brasil) Русский ไทย Türkçe 简体中文 繁體中文 On this page Overview Usage Authentication How it works Spec APIs Global Project Path & VCS Instance Config Provider Sessions Messages Commands Files Tools (Experimental) LSP, Formatters & MCP Agents Logging TUI Auth Events Docs On this page Overview Usage Authentication How it works Spec APIs Global Project Path & VCS Instance Config Provider Sessions Messages Commands Files Tools (Experimental) LSP, Formatters & MCP Agents Logging TUI Auth Events Docs Server Interact with opencode server over HTTP. The opencode serve command runs a headless HTTP server that exposes an OpenAPI endpoint that an opencode client can use. Usage Terminal window opencode serve [--port <number>] [--hostname <string>] [--cors <origin>] ] [--hostname ] [--cors ]"> Options Flag Description Default --port Port to listen on 4096 --hostname Hostname to listen on 127.0.0.1 --mdns Enable mDNS discovery false --mdns-domain Custom domain name for mDNS service opencode.local --cors Additional browser origins to allow [] --cors can be passed multiple times: Terminal window opencode serve --cors http://localhost:5173 --cors https://app.example.com Authentication Set OPENCODE_SERVER_PASSWORD to protect the server with HTTP basic auth. The username defaults to opencode , or set OPENCODE_SERVER_USERNAME to override it. This applies to both opencode serve and opencode web . Terminal window OPENCODE_SERVER_PASSWORD = your-password opencode serve How it works When you run opencode it starts a TUI and a server. Where the TUI is the client that talks to the server. The server exposes an OpenAPI 3.1 spec endpoint. This endpoint is also used to generate an SDK . Tip Use the opencode server to interact with opencode programmatically. This architecture lets opencode support multiple clients and allows you to interact with opencode programmatically. You can run opencode serve to start a standalone server. If you have the opencode TUI running, opencode serve will start a new server. Connect to an existing server When you start the TUI it randomly assigns a port and hostname. You can instead pass in the --hostname and --port flags . Then use this to connect to its server. The /tui endpoint can be used to drive the TUI through the server. For example, you can prefill or run a prompt. This setup is used by the OpenCode IDE plugins. Spec The server publishes an OpenAPI 3.1 spec that can be viewed at: http://<hostname>:<port>/doc : /doc"> For example, http://localhost:4096/doc . Use the spec to generate clients or inspect request and response types. Or view it in a Swagger explorer. APIs The opencode server exposes the following APIs. Global Method Path Description Response GET /global/health Get server health and version { healthy: true, version: string } GET /global/event Get global events (SSE stream) Event stream Project Method Path Description Response GET /project List all projects Project[] GET /project/current Get the current project Project Path & VCS Method Path Description Response GET /path Get the current path Path GET /vcs Get VCS info for the current project VcsInfo Instance Method Path Description Response POST /instance/dispose Dispose the current instance boolean Config Method Path Description Response GET /config Get config info Config PATCH /config Update config Config GET /config/providers List providers and default models { providers: Provider[] …

## 1.0.21 - 2026-04-07

- Add `copilot mcp` command for managing MCP servers
- Spinner no longer appears stuck when a long-running async shell command is active
- Enterprise GitHub URL input in the login flow now accepts keyboard input and submits on Enter
- Slash command picker no longer flickers or shifts the input while filtering
- Timeline no longer goes blank when content shrinks (e.g., after cancelling or tool completion)
- Plan mode timeline display shows user text without a redundant "Plan" prefix
- Reduce memory usage by automatically shutting down shell sessions that are no longer needed
- Hooks configured with PascalCase event names now receive VS Code-compatible snake_case payloads with hook_event_name, session_id, and ISO 8601 timestamps

## 1.0.20 - 2026-04-07

- Add `copilot help monitoring` topic with OpenTelemetry configuration details and examples
- Spinner stays active until background agents and shell commands finish, and user input remains available throughout
- Azure OpenAI BYOK defaults to the GA versionless v1 route when no API version is configured
- Reduce UI sluggishness during live response streaming
- /yolo and --yolo now behave identically and /yolo state persists across /restart

## 1.0.19 - 2026-04-06

- /mcp enable and /mcp disable now persist across sessions
- OpenTelemetry monitoring: subagent spans now use INTERNAL span kind, and chat spans include a `github.copilot.time_to_first_chunk` attribute (streaming only)
- Plugin hook scripts with missing execute permissions now run correctly on macOS
- Custom agent is properly restored when resuming a session where the agent display name differs from its filename
- Skip IDE auto-connect when session is already in use by another client
- Slash command timeline entries now include the command name (e.g., "Review", "Plan") for better context

## 1.0.18 - 2026-04-04

- New Critic agent automatically reviews plans and complex implementations using a complementary model to catch errors early (available in experimental mode for Claude models)
- Session resume picker correctly groups sessions by branch and repository on first use
- preToolUse hook permissionDecision 'allow' now suppresses the tool approval prompt
- Add notification hook event that fires asynchronously on shell completion, permission prompts, elicitation dialogs, and agent completion

## 1.0.17 - 2026-04-03

- Built-in skills are now included with the CLI, starting with a guide for customizing Copilot cloud agent's environment
- MCP OAuth flows now support HTTPS redirect URIs via a self-signed certificate fallback, improving compatibility with OAuth providers that require HTTPS (e.g., Slack)
- /resume session picker loads significantly faster, especially with large session histories

## 1.0.16 - 2026-04-02

- SQL prompt tags no longer appear when sql tool is excluded via excludedTools or availableTools
- MCP tool calls display tool name and parameter summary in the timeline
- MCP server reconnects correctly with valid authentication when the working directory changes
- Add PermissionRequest hook to allow scripts to programmatically approve or deny tool permission requests
- Remove deprecated `marketplaces` repository setting (use `extraKnownMarketplaces` instead)
- MCP servers load correctly after login, user switch, and /mcp reload
- BYOK Anthropic provider now respects the configured maxOutputTokens limit
- Remove deprecated `marketplaces` repository setting (use `extraKnownMarketplaces` instead)

## 1.0.15 - 2026-04-01

- Remove support for gpt-5.1-codex, gpt-5.1-codex-mini, and gpt-5.1-codex-max models
- Copilot mascot now blinks with subtle eye animations in interactive mode
- User switcher and `/user list` display accounts in alphabetical order
- Add mcp.config.list, mcp.config.add, mcp.config.update, and mcp.config.remove server RPCs for managing persistent MCP server configuration
- Add device code flow (RFC 8628) as a fallback for MCP OAuth in headless and CI environments
- Add `/m…

# @mariozechner/pi-ai

Unified LLM API with automatic model discovery, provider configuration, token and cost tracking, and simple context persistence and hand-off to other models mid-session.

**Note**: This library only includes models that support tool calling (function calling), as this is essential for agentic workflows.

## Table of Contents

- [Supported Providers](#supported-providers)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Tools](#tools)
  - [Defining Tools](#defining-tools)
  - [Handling Tool Calls](#handling-tool-calls)
  - [Streaming Tool Calls with Partial JSON](#streaming-tool-calls-with-partial-json)
  - [Validating Tool Arguments](#validating-tool-arguments)
  - [Complete Event Reference](#complete-event-reference)
- [Image Input](#image-input)
- [Thinking/Reasoning](#thinkingreasoning)
  - [Unified Interface](#unified-interface-streamsimplecompletesimple)
  - [Provider-Specific Options](#provider-specific-options-streamcomplete)
  - [Streaming Thinking Content](#streaming-thinking-content)
- [Stop Reasons](#stop-reasons)
- [Error Handling](#error-handling)
  - [Aborting Requests](#aborting-requests)
  - [Continuing After Abort](#continuing-after-abort)
- [APIs, Models, and Providers](#apis-models-and-providers)
  - [Providers and Models](#providers-and-models)
  - [Querying Providers and Models](#querying-providers-and-models)
  - [Custom Models](#custom-models)
  - [OpenAI Compatibility Settings](#openai-compatibility-settings)
  - [Type Safety](#type-safety)
- [Cross-Provider Handoffs](#cross-provider-handoffs)
- [Context Serialization](#context-serialization)
- [Browser Usage](#browser-usage)
  - [Browser Compatibility Notes](#browser-compatibility-notes)
  - [Environment Variables](#environment-variables-nodejs-only)
  - [Checking Environment Variables](#checking-environment-variables)
- [OAuth Providers](#oauth-providers)
  - [Vertex AI](#vertex-ai)
  - [CLI Login](#cli-login)
  - [Programmatic OAuth](#programmatic-oauth)
  - [Login Flow Example](#login-flow-example)
  - [Using OAuth Tokens](#using-oauth-tokens)
  - [Provider Notes](#provider-notes)
- [License](#license)

## Supported Providers

- **OpenAI**
- **Azure OpenAI (Responses)**
- **OpenAI Codex** (ChatGPT Plus/Pro subscription, requires OAuth, see below)
- **Anthropic**
- **Google**
- **Vertex AI** (Gemini via Vertex AI)
- **Mistral**
- **Groq**
- **Cerebras**
- **xAI**
- **OpenRouter**
- **Vercel AI Gateway**
- **MiniMax**
- **GitHub Copilot** (requires OAuth, see below)
- **Google Gemini CLI** (requires OAuth, see below)
- **Antigravity** (requires OAuth, see below)
- **Amazon Bedrock**
- **OpenCode Zen**
- **OpenCode Go**
- **Kimi For Coding** (Moonshot AI, uses Anthropic-compatible API)
- **Any OpenAI-compatible API**: Ollama, vLLM, LM Studio, etc.

## Installation

```bash
npm install @mariozechner/pi-ai
```

TypeBox exports are re-exported from `@mariozechner/pi-ai`: `Type`, `Static`, and `TSchema`.

## Quick Start

```typescript
import { Type, getModel, stream, complete, Context, Tool, StringEnum } from '@mariozechner/pi-ai';

// Fully typed with auto-complete support for both providers and models
const model = getModel('openai', 'gpt-4o-mini');

// Define tools with TypeBox schemas for type safety and validation
const tools: Tool[] = [{
  name: 'get_time',
  description: 'Get the current time',
  parameters: Type.Object({
    timezone: Type.Optional(Type.String({ description: 'Optional timezone (e.g., America/New_York)' }))
  })
}];

// Build a conversation context (easily serializable and transferable between models)
const context: Context = {
  systemPrompt: 'You are a helpful assistant.',
  messages: [{ role: 'user', content: 'What time is it?' }],
  tools
};

// Option 1: Streaming with all event types
const s = stream(model, context);

for await (const event of s) {
  switch (event.type) {
    case 'start':
      console.log(`Starting with ${event.partial.model}`);
      break;
    case 'text_start':
     …

//! Root of the `codex-core` library.

// Prevent accidental direct writes to stdout/stderr in library code. All
// user-visible output must go through the appropriate abstraction (e.g.,
// the TUI or the tracing stack).
#![deny(clippy::print_stdout, clippy::print_stderr)]

mod apply_patch;
mod apps;
mod arc_monitor;
mod client;
mod client_common;
pub(crate) mod codex;
mod realtime_context;
mod realtime_conversation;
pub use codex::SteerInputError;
mod codex_thread;
mod compact_remote;
pub use codex_thread::CodexThread;
pub use codex_thread::ThreadConfigSnapshot;
mod agent;
mod codex_delegate;
mod command_canonicalization;
mod commit_attribution;
pub mod config;
pub mod config_loader;
pub mod connectors;
mod context_manager;
mod contextual_user_message;
mod environment_context;
pub mod exec;
pub mod exec_env;
mod exec_policy;
pub mod external_agent_config;
pub mod file_watcher;
mod flags;
#[cfg(test)]
mod git_info_tests;
mod guardian;
mod hook_runtime;
mod installation_id;
pub(crate) mod instructions;
pub(crate) mod landlock;
pub use landlock::spawn_command_under_linux_sandbox;
pub(crate) mod mcp;
mod mcp_skill_dependencies;
mod mcp_tool_approval_templates;
mod network_policy_decision;
pub(crate) mod network_proxy_loader;
pub use mcp::McpManager;
pub use network_proxy_loader::MtimeConfigReloader;
pub use network_proxy_loader::build_network_proxy_state;
pub use network_proxy_loader::build_network_proxy_state_and_reloader;
mod original_image_detail;
pub use codex_mcp::MCP_SANDBOX_STATE_CAPABILITY;
pub use codex_mcp::MCP_SANDBOX_STATE_METHOD;
pub use codex_mcp::SandboxState;
mod mcp_tool_call;
mod memories;
pub(crate) mod mention_syntax;
pub(crate) mod message_history;
pub(crate) mod utils;
pub use mention_syntax::PLUGIN_TEXT_MENTION_SIGIL;
pub use mention_syntax::TOOL_MENTION_SIGIL;
pub use message_history::HistoryEntry as MessageHistoryEntry;
pub use message_history::append_entry as append_message_history_entry;
pub use message_history::history_metadata as message_history_metadata;
pub use message_history::lookup as lookup_message_history_entry;
pub use utils::path_utils;
pub mod personality_migration;
pub mod plugins;
#[doc(hidden)]
pub(crate) mod prompt_debug;
#[doc(hidden)]
pub use prompt_debug::build_prompt_input;
pub(crate) mod mentions {
    pub(crate) use crate::plugins::build_connector_slug_counts;
    pub(crate) use crate::plugins::build_skill_name_counts;
    pub(crate) use crate::plugins::collect_explicit_app_ids;
    pub(crate) use crate::plugins::collect_explicit_plugin_mentions;
    pub(crate) use crate::plugins::collect_tool_mentions_from_messages;
}
mod sandbox_tags;
pub mod sandboxing;
mod session_prefix;
mod session_startup_prewarm;
mod shell_detect;
pub mod skills;
pub(crate) use skills::SkillError;
pub(crate) use skills::SkillInjections;
pub(crate) use skills::SkillLoadOutcome;
pub(crate) use skills::SkillMetadata;
pub(crate) use skills::SkillsLoadInput;
pub(crate) use skills::SkillsManager;
pub(crate) use skills::build_skill_injections;
pub(crate) use skills::build_skill_name_counts;
pub(crate) use skills::collect_env_var_dependencies;
pub(crate) use skills::collect_explicit_skill_mentions;
pub(crate) use skills::config_rules;
pub(crate) use skills::injection;
pub(crate) use skills::loader;
pub(crate) use skills::manager;
pub(crate) use skills::maybe_emit_implicit_skill_invocation;
pub(crate) use skills::render_skills_section;
pub(crate) use skills::resolve_skill_dependencies_for_turn;
pub(crate) use skills::skills_load_input_from_config;
mod skills_watcher;
mod stream_events_utils;
pub mod test_support;
mod unified_exec;
pub mod windows_sandbox;
pub use client::X_RESPONSESAPI_INCLUDE_TIMING_METRICS_HEADER;
pub use codex_protocol::config_types::ModelProviderAuthInfo;
mod event_mapping;
pub mod review_format;
pub mod review_prompts;
mod thread_manager;
pub(crate) mod web_search;
pub(crate) mod windows_sandbox_read_grants;
pub use thread_manager::ForkSnapshot;
pub use thread_manager::NewThread;
pub use thread…

import * as path from "path"
import { parseFrontmatter } from "../../repertoire/tasks/parser"
import { emitNervesEvent } from "../../nerves/runtime"

export type HabitStatus = "active" | "paused"

export interface HabitFile {
  name: string
  title: string
  cadence: string | null
  status: HabitStatus
  lastRun: string | null
  created: string | null
  body: string
}

function isHabitStatus(value: string): value is HabitStatus {
  return value === "active" || value === "paused"
}

function extractFrontmatterAndBody(content: string): { frontmatter: Record<string, unknown>; body: string } | null {
  const lines = content.split(/\r?\n/)
  if (lines[0]?.trim() !== "---") {
    return null
  }

  const closing = lines.findIndex((line, index) => index > 0 && line.trim() === "---")
  if (closing === -1) {
    return null
  }

  const rawFrontmatter = lines.slice(1, closing).join("\n")
  const body = lines.slice(closing + 1).join("\n").trim()
  return { frontmatter: parseFrontmatter(rawFrontmatter), body }
}

export function parseHabitFile(content: string, filePath: string): HabitFile {
  emitNervesEvent({
    event: "daemon.habit_parse",
    component: "daemon",
    message: "parsing habit file",
    meta: { filePath },
  })

  const stem = path.basename(filePath, ".md")
  const parsed = extractFrontmatterAndBody(content)

  if (!parsed) {
    return {
      name: stem,
      title: stem,
      cadence: null,
      status: "active",
      lastRun: null,
      created: null,
      body: content.trim(),
    }
  }

  const { frontmatter, body } = parsed

  const rawTitle = frontmatter.title
  const title = typeof rawTitle === "string" && rawTitle.length > 0 ? rawTitle : stem

  const rawCadence = frontmatter.cadence
  const cadence = typeof rawCadence === "string" && rawCadence.length > 0 ? rawCadence : null

  const rawStatus = frontmatter.status
  const status: HabitStatus =
    typeof rawStatus === "string" && isHabitStatus(rawStatus) ? rawStatus : "active"

  const rawLastRun = frontmatter.lastRun
  const lastRun = typeof rawLastRun === "string" && rawLastRun.length > 0 ? rawLastRun : null

  const rawCreated = frontmatter.created
  const created = typeof rawCreated === "string" && rawCreated.length > 0 ? rawCreated : null

  return {
    name: stem,
    title,
    cadence,
    status,
    lastRun,
    created,
    body,
  }
}

function formatFrontmatterValue(value: unknown): string {
  if (value === null || value === undefined) return "null"
  return String(value)
}

export function renderHabitFile(frontmatter: Record<string, unknown>, body: string): string {
  emitNervesEvent({
    event: "daemon.habit_render",
    component: "daemon",
    message: "rendering habit file",
    meta: {},
  })

  const lines: string[] = ["---"]

  for (const key of Object.keys(frontmatter)) {
    lines.push(`${key}: ${formatFrontmatterValue(frontmatter[key])}`)
  }

  lines.push("---")
  lines.push("")
  lines.push(body.trim())
  lines.push("")
  return lines.join("\n")
}

**Pi-mono's coding agent (@mariozechner/pi-coding-agent) uses a **TypeScript-based extension system** where extensions are full TypeScript modules running in the same process as the agent, enabling customization via event hooks, tools, commands, UI components, and more.[1][2][5][7]**

### Core Architecture
Pi-mono is a **monorepo toolkit** with layered packages for building AI agents:
- **pi-ai**: LLM provider abstraction (supports 15+ providers like OpenAI, Ollama).[4][8]
- **pi-agent-core**: Reusable agent runtime with file tools, session persistence, context compaction.[2][4].
- **pi-coding-agent**: Minimal terminal harness that extends via **extensions, skills, prompts, themes**—not a monolithic app.[1][2][7].
- **pi-tui**: Terminal UI for CLI interfaces, supporting custom components like spinners, progress bars, file pickers.[3][4].
- Supporting: Web UI, pods for infrastructure.[2][8].

Extensions load from `~/.pi/agent/extensions/*.ts` (or npm/git/local packages) with **hot reloading** for live development—the agent can write, test, and iterate on its own extensions.[1][3][5].

### Extension API (TypeScript Interface)
Extensions receive an `ExtensionAPI` object for full control:[1]
```
interface ExtensionAPI {
  // Events
  on(event: string, handler: ExtensionHandler): void;
  events: EventBus;  // Shared pub/sub (e.g., emit/listen "task:complete")

  // Tools & Commands
  registerTool(tool: ToolDefinition): void;
  registerCommand(name: string, options: RegisteredCommand): void;

  // UI/Messaging
  sendMessage(message: CustomMessage, options?: MessageOptions): void;
  sendUserMessage(content: string | Content[], options?: MessageOptions): void;

  // State
  appendEntry(customType: string, data?: unknown): void;
  setSessionName(name: string): void;
  setLabel(entryId: string, label: string): void;

  // Models/Tools
  setModel(model: Model): Promise<boolean>;
  setActiveTools(toolNames: string[]): void;
  getActiveTools(): string[];
}
```
**Example extension**:
```typescript
// ~/.pi/agent/extensions/my-extension.ts
import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
export default function (pi: ExtensionAPI) {
  pi.on("session_start", async (event, ctx) => {
    console.log("Session started");
  });
  pi.registerTool({ /* tool def */ });
  pi.events.on("task:complete", (data) => console.log(data));
}
```

### Key Features
- **25+ hook points**: Intercept commands, block ops, add sub-agents, custom status bars, themes.[5].
- **Composable**: Stack extensions (e.g., one for UI widgets, one for tools).[5].
- **Package ecosystem**: Install via npm/git/local (`pi install <pkg>`); includes skills/themes/extensions.[5][6].
- **TUI Flexibility**: Render dashboards, Doom (proof-of-concept).[3].
- **Embeddable SDK**: Full TypeScript API for custom apps/products.[5].

This design prioritizes **modularity**—adapt the agent without forking core code.[2][7]. For setup: `npm install @mariozechner/pi-coding-agent` and point to `~/.pi/agent/extensions`.[1][4].

OpenClaw's **gateway architecture** enables **multi-channel agent routing** by running multiple isolated agents within a single Gateway process, routing inbound messages from channels (e.g., WhatsApp, Telegram, Discord) to specific agents via configurable **bindings** based on match criteria like channel, accountId, peer, or guildId.[1][2][3]

### Core Components
- **Gateway**: Acts as the central router and control plane, connecting agents to messaging channels, handling auth, sessions, and transparent proxying to multi-node setups (e.g., local MacBook + remote VPS).[3][4]
- **Agents**: Each is a fully isolated "persona" with its own workspace (default cwd for files like AGENTS.md/SOUL.md), skills, memory, auth/sessions, and model config—no cross-talk unless enabled. Supports shared baseline skills via `agents.defaults.skills` and per-agent overrides.[1][5]
- **Channels**: Multiple accounts per channel (e.g., two WhatsApps) connect via QR pairing or bots; Gateway extracts metadata (channel, accountId, peer ID) from messages.[1][6]

### Routing Logic (Deterministic, "Most Specific Wins")
The Router processes inbound messages in strict priority order, using AND semantics for multi-field matches. First match wins; no match falls back to default agent.[1][2][3][6]

| Priority | Match Criteria | Example Use Case |
|----------|----------------|------------------|
| 1 (Highest) | Exact **peer** (DM/group ID) | Route WhatsApp family group to "Family Agent".[1][6] |
| 2 | parentPeer/guildId + roles | Discord role-based support routing.[6] |
| 3 | **accountId** | Split personal vs. business WhatsApp numbers.[1][2] |
| 4 | **channel**-level (`accountId: "*"` fallback) | Default Telegram handling.[2] |
| 5 (Lowest) | Default agent (first in `agents.list` or flagged `default: true`)[1][2] |

Bindings omit `accountId` to match only defaults; explicit `accountId: "*"` enables channel-wide fallbacks. Upgrades occur automatically for added specificity.[1]

### Configuration Example
Define in main config (one Gateway file for all agents):[2]
```
agents: {
  list: [
    { id: "supervisor", workspace: "~/agents/supervisor", default: true },
    { id: "writer", workspace: "~/agents/writer" }
  ]
},
bindings: [
  { agentId: "writer", match: { channel: "telegram", peer: { kind: "group", id: "writing_group" } } },
  { agentId: "supervisor", match: { channel: "feishu", accountId: "work-bot" } },
  { agentId: "supervisor", match: { channel: "telegram" } }  // Fallback
]
```
CLI tools: `openclaw agents list --bindings` (view active routing); `openclaw channels status --probe` (test connectivity).[2]

### Advanced Patterns
- **Persistent vs. Sub-agents**: Persistent for ongoing channels/personas; sub-agents for tasks (e.g., spawn "coder" from supervisor, poll via Gateway).[4][5][7]
- **Dynamic Routing**: Supplement bindings with LLM-driven `sessions_send` or Lobster pipelines for runtime delegation (e.g., supervisor routes to specialists).[2]
- **Architecture Patterns**: Domain specialists (channel-routed); orchestrator + sub-agents; 5 community patterns per research compendium.[5][8]

This setup isolates data/personalities for multi-user sharing (e.g., household members) while scaling via one Gateway.[1][5] For production, combine with multi-node for GPU/parallelism.[4]

# Claude Code Plugins

This directory contains some official Claude Code plugins that extend functionality through custom commands, agents, and workflows. These are examples of what's possible with the Claude Code plugin system—many more plugins are available through community marketplaces.

## What are Claude Code Plugins?

Claude Code plugins are extensions that enhance Claude Code with custom slash commands, specialized agents, hooks, and MCP servers. Plugins can be shared across projects and teams, providing consistent tooling and workflows.

Learn more in the [official plugins documentation](https://docs.claude.com/en/docs/claude-code/plugins).

## Plugins in This Directory

| Name | Description | Contents |
|------|-------------|----------|
| [agent-sdk-dev](./agent-sdk-dev/) | Development kit for working with the Claude Agent SDK | **Command:** `/new-sdk-app` - Interactive setup for new Agent SDK projects<br>**Agents:** `agent-sdk-verifier-py`, `agent-sdk-verifier-ts` - Validate SDK applications against best practices |
| [claude-opus-4-5-migration](./claude-opus-4-5-migration/) | Migrate code and prompts from Sonnet 4.x and Opus 4.1 to Opus 4.5 | **Skill:** `claude-opus-4-5-migration` - Automated migration of model strings, beta headers, and prompt adjustments |
| [code-review](./code-review/) | Automated PR code review using multiple specialized agents with confidence-based scoring to filter false positives | **Command:** `/code-review` - Automated PR review workflow<br>**Agents:** 5 parallel Sonnet agents for CLAUDE.md compliance, bug detection, historical context, PR history, and code comments |
| [commit-commands](./commit-commands/) | Git workflow automation for committing, pushing, and creating pull requests | **Commands:** `/commit`, `/commit-push-pr`, `/clean_gone` - Streamlined git operations |
| [explanatory-output-style](./explanatory-output-style/) | Adds educational insights about implementation choices and codebase patterns (mimics the deprecated Explanatory output style) | **Hook:** SessionStart - Injects educational context at the start of each session |
| [feature-dev](./feature-dev/) | Comprehensive feature development workflow with a structured 7-phase approach | **Command:** `/feature-dev` - Guided feature development workflow<br>**Agents:** `code-explorer`, `code-architect`, `code-reviewer` - For codebase analysis, architecture design, and quality review |
| [frontend-design](./frontend-design/) | Create distinctive, production-grade frontend interfaces that avoid generic AI aesthetics | **Skill:** `frontend-design` - Auto-invoked for frontend work, providing guidance on bold design choices, typography, animations, and visual details |
| [hookify](./hookify/) | Easily create custom hooks to prevent unwanted behaviors by analyzing conversation patterns or explicit instructions | **Commands:** `/hookify`, `/hookify:list`, `/hookify:configure`, `/hookify:help`<br>**Agent:** `conversation-analyzer` - Analyzes conversations for problematic behaviors<br>**Skill:** `writing-rules` - Guidance on hookify rule syntax |
| [learning-output-style](./learning-output-style/) | Interactive learning mode that requests meaningful code contributions at decision points (mimics the unshipped Learning output style) | **Hook:** SessionStart - Encourages users to write meaningful code (5-10 lines) at decision points while receiving educational insights |
| [plugin-dev](./plugin-dev/) | Comprehensive toolkit for developing Claude Code plugins with 7 expert skills and AI-assisted creation | **Command:** `/plugin-dev:create-plugin` - 8-phase guided workflow for building plugins<br>**Agents:** `agent-creator`, `plugin-validator`, `skill-reviewer`<br>**Skills:** Hook development, MCP integration, plugin structure, settings, commands, agents, and skill development |
| [pr-review-toolkit](./pr-review-toolkit/) | Comprehensive PR review agents specializing in comments, tests, error handling, type design, code quality, and code si…

# Claude Code Plugins

This directory contains some official Claude Code plugins that extend functionality through custom commands, agents, and workflows. These are examples of what's possible with the Claude Code plugin system—many more plugins are available through community marketplaces.

## What are Claude Code Plugins?

Claude Code plugins are extensions that enhance Claude Code with custom slash commands, specialized agents, hooks, and MCP servers. Plugins can be shared across projects and teams, providing consistent tooling and workflows.

Learn more in the [official plugins documentation](https://docs.claude.com/en/docs/claude-code/plugins).

## Plugins in This Directory

| Name | Description | Contents |
|------|-------------|----------|
| [agent-sdk-dev](./agent-sdk-dev/) | Development kit for working with the Claude Agent SDK | **Command:** `/new-sdk-app` - Interactive setup for new Agent SDK projects<br>**Agents:** `agent-sdk-verifier-py`, `agent-sdk-verifier-ts` - Validate SDK applications against best practices |
| [claude-opus-4-5-migration](./claude-opus-4-5-migration/) | Migrate code and prompts from Sonnet 4.x and Opus 4.1 to Opus 4.5 | **Skill:** `claude-opus-4-5-migration` - Automated migration of model strings, beta headers, and prompt adjustments |
| [code-review](./code-review/) | Automated PR code review using multiple specialized agents with confidence-based scoring to filter false positives | **Command:** `/code-review` - Automated PR review workflow<br>**Agents:** 5 parallel Sonnet agents for CLAUDE.md compliance, bug detection, historical context, PR history, and code comments |
| [commit-commands](./commit-commands/) | Git workflow automation for committing, pushing, and creating pull requests | **Commands:** `/commit`, `/commit-push-pr`, `/clean_gone` - Streamlined git operations |
| [explanatory-output-style](./explanatory-output-style/) | Adds educational insights about implementation choices and codebase patterns (mimics the deprecated Explanatory output style) | **Hook:** SessionStart - Injects educational context at the start of each session |
| [feature-dev](./feature-dev/) | Comprehensive feature development workflow with a structured 7-phase approach | **Command:** `/feature-dev` - Guided feature development workflow<br>**Agents:** `code-explorer`, `code-architect`, `code-reviewer` - For codebase analysis, architecture design, and quality review |
| [frontend-design](./frontend-design/) | Create distinctive, production-grade frontend interfaces that avoid generic AI aesthetics | **Skill:** `frontend-design` - Auto-invoked for frontend work, providing guidance on bold design choices, typography, animations, and visual details |
| [hookify](./hookify/) | Easily create custom hooks to prevent unwanted behaviors by analyzing conversation patterns or explicit instructions | **Commands:** `/hookify`, `/hookify:list`, `/hookify:configure`, `/hookify:help`<br>**Agent:** `conversation-analyzer` - Analyzes conversations for problematic behaviors<br>**Skill:** `writing-rules` - Guidance on hookify rule syntax |
| [learning-output-style](./learning-output-style/) | Interactive learning mode that requests meaningful code contributions at decision points (mimics the unshipped Learning output style) | **Hook:** SessionStart - Encourages users to write meaningful code (5-10 lines) at decision points while receiving educational insights |
| [plugin-dev](./plugin-dev/) | Comprehensive toolkit for developing Claude Code plugins with 7 expert skills and AI-assisted creation | **Command:** `/plugin-dev:create-plugin` - 8-phase guided workflow for building plugins<br>**Agents:** `agent-creator`, `plugin-validator`, `skill-reviewer`<br>**Skills:** Hook development, MCP integration, plugin structure, settings, commands, agents, and skill development |
| [pr-review-toolkit](./pr-review-toolkit/) | Comprehensive PR review agents specializing in comments, tests, error handling, type design, code quality, and code si…

LSP Servers | OpenCode Skip to content OpenCode app.header.home app.header.docs Search Ctrl K Cancel Intro Config Providers Network Enterprise Troubleshooting Windows Usage Go TUI CLI Web IDE Zen Share GitHub GitLab Configure Tools Rules Agents Models Themes Keybinds Commands Formatters Permissions LSP Servers MCP servers ACP Support Agent Skills Custom Tools Develop SDK Server Plugins Ecosystem GitHub Discord Select theme Dark Light Auto Select language English العربية Bosanski Dansk Deutsch Español Français Italiano 日本語 한국어 Norsk Bokmål Polski Português (Brasil) Русский ไทย Türkçe 简体中文 繁體中文 On this page Overview Built-in How It Works Configure Environment variables Initialization options Disabling LSP servers Custom LSP servers Additional Information PHP Intelephense On this page Overview Built-in How It Works Configure Environment variables Initialization options Disabling LSP servers Custom LSP servers Additional Information PHP Intelephense LSP Servers OpenCode integrates with your LSP servers. OpenCode integrates with your Language Server Protocol (LSP) to help the LLM interact with your codebase. It uses diagnostics to provide feedback to the LLM. Built-in OpenCode comes with several built-in LSP servers for popular languages: LSP Server Extensions Requirements astro .astro Auto-installs for Astro projects bash .sh, .bash, .zsh, .ksh Auto-installs bash-language-server clangd .c, .cpp, .cc, .cxx, .c++, .h, .hpp, .hh, .hxx, .h++ Auto-installs for C/C++ projects csharp .cs .NET SDK installed clojure-lsp .clj, .cljs, .cljc, .edn clojure-lsp command available dart .dart dart command available deno .ts, .tsx, .js, .jsx, .mjs deno command available (auto-detects deno.json/deno.jsonc) elixir-ls .ex, .exs elixir command available eslint .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vue eslint dependency in project fsharp .fs, .fsi, .fsx, .fsscript .NET SDK installed gleam .gleam gleam command available gopls .go go command available hls .hs, .lhs haskell-language-server-wrapper command available jdtls .java Java SDK (version 21+) installed julials .jl julia and LanguageServer.jl installed kotlin-ls .kt, .kts Auto-installs for Kotlin projects lua-ls .lua Auto-installs for Lua projects nixd .nix nixd command available ocaml-lsp .ml, .mli ocamllsp command available oxlint .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vue, .astro, .svelte oxlint dependency in project php intelephense .php Auto-installs for PHP projects prisma .prisma prisma command available pyright .py, .pyi pyright dependency installed ruby-lsp (rubocop) .rb, .rake, .gemspec, .ru ruby and gem commands available rust .rs rust-analyzer command available sourcekit-lsp .swift, .objc, .objcpp swift installed ( xcode on macOS) svelte .svelte Auto-installs for Svelte projects terraform .tf, .tfvars Auto-installs from GitHub releases tinymist .typ, .typc Auto-installs from GitHub releases typescript .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts typescript dependency in project vue .vue Auto-installs for Vue projects yaml-ls .yaml, .yml Auto-installs Red Hat yaml-language-server zls .zig, .zon zig command available LSP servers are automatically enabled when one of the above file extensions are detected and the requirements are met. Note You can disable automatic LSP server downloads by setting the OPENCODE_DISABLE_LSP_DOWNLOAD environment variable to true . How It Works When opencode opens a file, it: Checks the file extension against all enabled LSP servers. Starts the appropriate LSP server if not already running. Configure You can customize LSP servers through the lsp section in your opencode config. opencode.json { "$schema" : "https://opencode.ai/config.json" , "lsp" : {} } Each LSP server supports the following: Property Type Description disabled boolean Set this to true to disable the LSP server command string[] The command to start the LSP server extensions string[] File extensions this LSP server should handle env object Environment variables to set when starting…

Permissions | OpenCode Skip to content OpenCode app.header.home app.header.docs Search Ctrl K Cancel Intro Config Providers Network Enterprise Troubleshooting Windows Usage Go TUI CLI Web IDE Zen Share GitHub GitLab Configure Tools Rules Agents Models Themes Keybinds Commands Formatters Permissions LSP Servers MCP servers ACP Support Agent Skills Custom Tools Develop SDK Server Plugins Ecosystem GitHub Discord Select theme Dark Light Auto Select language English العربية Bosanski Dansk Deutsch Español Français Italiano 日本語 한국어 Norsk Bokmål Polski Português (Brasil) Русский ไทย Türkçe 简体中文 繁體中文 On this page Overview Actions Configuration Granular Rules (Object Syntax) Wildcards Home Directory Expansion External Directories Available Permissions Defaults What “Ask” Does Agents On this page Overview Actions Configuration Granular Rules (Object Syntax) Wildcards Home Directory Expansion External Directories Available Permissions Defaults What “Ask” Does Agents Permissions Control which actions require approval to run. OpenCode uses the permission config to decide whether a given action should run automatically, prompt you, or be blocked. As of v1.1.1 , the legacy tools boolean config is deprecated and has been merged into permission . The old tools config is still supported for backwards compatibility. Actions Each permission rule resolves to one of: "allow" — run without approval "ask" — prompt for approval "deny" — block the action Configuration You can set permissions globally (with * ), and override specific tools. opencode.json { "$schema" : "https://opencode.ai/config.json" , "permission" : { "*" : "ask" , "bash" : "allow" , "edit" : "deny" } } You can also set all permissions at once: opencode.json { "$schema" : "https://opencode.ai/config.json" , "permission" : "allow" } Granular Rules (Object Syntax) For most permissions, you can use an object to apply different actions based on the tool input. opencode.json { "$schema" : "https://opencode.ai/config.json" , "permission" : { "bash" : { "*" : "ask" , "git *" : "allow" , "npm *" : "allow" , "rm *" : "deny" , "grep *" : "allow" }, "edit" : { "*" : "deny" , "packages/web/src/content/docs/*.mdx" : "allow" } } } Rules are evaluated by pattern match, with the last matching rule winning . A common pattern is to put the catch-all "*" rule first, and more specific rules after it. Wildcards Permission patterns use simple wildcard matching: * matches zero or more of any character ? matches exactly one character All other characters match literally Home Directory Expansion You can use ~ or $HOME at the start of a pattern to reference your home directory. This is particularly useful for external_directory rules. ~/projects/* -> /Users/username/projects/* $HOME/projects/* -> /Users/username/projects/* ~ -> /Users/username External Directories Use external_directory to allow tool calls that touch paths outside the working directory where OpenCode was started. This applies to any tool that takes a path as input (for example read , edit , list , glob , grep , and many bash commands). Home expansion (like ~/... ) only affects how a pattern is written. It does not make an external path part of the current workspace, so paths outside the working directory must still be allowed via external_directory . For example, this allows access to everything under ~/projects/personal/ : opencode.json { "$schema" : "https://opencode.ai/config.json" , "permission" : { "external_directory" : { "~/projects/personal/**" : "allow" } } } Any directory allowed here inherits the same defaults as the current workspace. Since read defaults to allow , reads are also allowed for entries under external_directory unless overridden. Add explicit rules when a tool should be restricted in these paths, such as blocking edits while keeping reads: opencode.json { "$schema" : "https://opencode.ai/config.json" , "permission" : { "external_directory" : { "~/projects/personal/**" : "allow" }, "edit" : { "~/projects/personal/**" : …

<!-- OSS_WEEKEND_START -->
# 🏖️ OSS Weekend

**Issue tracker reopens Monday, April 13, 2026.**

OSS weekend runs Thursday, April 2, 2026 through Monday, April 13, 2026. New issues and PRs from unapproved contributors are auto-closed during this time. Approved contributors can still open issues and PRs if something is genuinely urgent, but please keep that to pressing matters only. For support, join [Discord](https://discord.com/invite/3cU7Bz4UPx).

> _Current focus: at the moment i'm deep in refactoring internals, and need to focus._
<!-- OSS_WEEKEND_END -->

---

<p align="center">
  <a href="https://shittycodingagent.ai">
    <img src="https://shittycodingagent.ai/logo.svg" alt="pi logo" width="128">
  </a>
</p>
<p align="center">
  <a href="https://discord.com/invite/3cU7Bz4UPx"><img alt="Discord" src="https://img.shields.io/badge/discord-community-5865F2?style=flat-square&logo=discord&logoColor=white" /></a>
  <a href="https://www.npmjs.com/package/@mariozechner/pi-coding-agent"><img alt="npm" src="https://img.shields.io/npm/v/@mariozechner/pi-coding-agent?style=flat-square" /></a>
  <a href="https://github.com/badlogic/pi-mono/actions/workflows/ci.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/badlogic/pi-mono/ci.yml?style=flat-square&branch=main" /></a>
</p>
<p align="center">
  <a href="https://pi.dev">pi.dev</a> domain graciously donated by
  <br /><br />
  <a href="https://exe.dev"><img src="docs/images/exy.png" alt="Exy mascot" width="48" /><br />exe.dev</a>
</p>

Pi is a minimal terminal coding harness. Adapt pi to your workflows, not the other way around, without having to fork and modify pi internals. Extend it with TypeScript [Extensions](#extensions), [Skills](#skills), [Prompt Templates](#prompt-templates), and [Themes](#themes). Put your extensions, skills, prompt templates, and themes in [Pi Packages](#pi-packages) and share them with others via npm or git.

Pi ships with powerful defaults but skips features like sub agents and plan mode. Instead, you can ask pi to build what you want or install a third party pi package that matches your workflow.

Pi runs in four modes: interactive, print or JSON, RPC for process integration, and an SDK for embedding in your own apps. See [openclaw/openclaw](https://github.com/openclaw/openclaw) for a real-world SDK integration.

## Share your OSS coding agent sessions

If you use pi for open source work, please share your coding agent sessions.

Public OSS session data helps improve models, prompts, tools, and evaluations using real development workflows.

For the full explanation, see [this post on X](https://x.com/badlogicgames/status/2037811643774652911).

To publish sessions, use [`badlogic/pi-share-hf`](https://github.com/badlogic/pi-share-hf). Read its README.md for setup instructions. All you need is a Hugging Face account, the Hugging Face CLI, and `pi-share-hf`.

You can also watch [this video](https://x.com/badlogicgames/status/2041151967695634619), where I show how I publish my `pi-mono` sessions.

I regularly publish my own `pi-mono` work sessions here:

- [badlogicgames/pi-mono on Hugging Face](https://huggingface.co/datasets/badlogicgames/pi-mono)

## Table of Contents

- [Quick Start](#quick-start)
- [Providers & Models](#providers--models)
- [Interactive Mode](#interactive-mode)
  - [Editor](#editor)
  - [Commands](#commands)
  - [Keyboard Shortcuts](#keyboard-shortcuts)
  - [Message Queue](#message-queue)
- [Sessions](#sessions)
  - [Branching](#branching)
  - [Compaction](#compaction)
- [Settings](#settings)
- [Context Files](#context-files)
- [Customization](#customization)
  - [Prompt Templates](#prompt-templates)
  - [Skills](#skills)
  - [Extensions](#extensions)
  - [Themes](#themes)
  - [Pi Packages](#pi-packages)
- [Programmatic Usage](#programmatic-usage)
- [Philosophy](#philosophy)
- [CLI Reference](#cli-reference)

---

## Quick Start

```bash
npm install -g @mariozechner/pi-coding-agent
```

Authenticate…