# pi-codemode-toggle

> Toggle Pi's native Codemode tool at runtime with `/codemode`.
> Requires Pi 0.99.0 or newer. Once the extension is loaded, Codemode can be enabled or disabled
> without restarting Pi or editing configuration files.
> One dependency-free TypeScript file, MIT licensed.

`pi-codemode-toggle` is a [Pi](https://pi.dev) extension that registers the `/codemode` slash
command for enabling, disabling, and inspecting Pi's built-in Codemode tool while a session is
running.

It changes Pi's active tool set using the `setActiveTools` API. Changes apply to the next model
turn immediately.

## Install

```sh
pi install npm:pi-codemode-toggle
```

Requires **Pi 0.99.0 or newer**, where native Codemode is available.

If Pi is already running when the package is installed, run `/reload` once so the extension loads
and the `/codemode` command is registered. This reload is only needed to load a newly installed
extension. Enabling or disabling Codemode afterward does not require a restart or reload.

## Links

- Source: https://github.com/iamaamir/pi-codemode-toggle
- Package: https://www.npmjs.com/package/pi-codemode-toggle
- Pi package page: https://pi.dev/packages/pi-codemode-toggle
- Landing page: https://iamaamir.github.io/pi-codemode-toggle/

## Commands

| Command | Effect |
| --- | --- |
| `/codemode` | Toggle Pi's native Codemode tool on or off |
| `/codemode on` | Enable Codemode |
| `/codemode off` | Disable Codemode |
| `/codemode status` | Report the current Codemode state |

Argument completions are provided for `on`, `off`, `status`, and `toggle`.

## How to enable Codemode in Pi

1. Make sure Pi 0.99.0 or newer is installed.
2. Install the extension: `pi install npm:pi-codemode-toggle`
3. If Pi was already running during installation, run `/reload` once.
4. Type `/codemode` or `/codemode on`.
5. The footer indicator changes to `codemode:on`.

The native Codemode tool becomes part of Pi's active tool set for the next model turn.

## How to disable Codemode in Pi

Type:

```text
/codemode off
```

The native Codemode tool is removed from Pi's active tool set immediately and the footer indicator
changes to `codemode:off`.

## What is Pi Codemode?

Codemode is Pi's built-in tool for letting the model write a small JavaScript program that calls
available tools instead of issuing each tool call as a separate model step.

This makes workflows such as parallel reads and multi-step tool orchestration possible within a
single Codemode execution.

Pi ships Codemode as the `builtin:codemode` extension.

`pi-codemode-toggle` does not implement or replace Codemode. It provides runtime control over
whether Pi's native Codemode tool is active.

## Status indicator

The extension displays the current state in Pi's footer:

```text
codemode:on
```

or:

```text
codemode:off
```

The indicator is resynchronized on relevant session events so it reflects Pi's current active tool
set.

## Troubleshooting

### `/codemode` is missing

Check these in order:

1. **Pi version**

   Native Codemode requires Pi 0.99.0 or newer.

2. **Extension not loaded yet**

   If the package was installed while Pi was already running, run:

   ```text
   /reload
   ```

3. **Project trust**

   Installing with:

   ```sh
   pi install npm:pi-codemode-toggle -l
   ```

   writes the package declaration to the project's `.pi/settings.json`.

   Pi only reads project-level configuration after that directory is trusted.

   Either grant trust to the project directory or install globally:

   ```sh
   pi install npm:pi-codemode-toggle
   ```

   which adds the package to `~/.pi/agent/settings.json`.

4. **Confirm installation**

   Run:

   ```sh
   pi list
   ```

   and verify that `pi-codemode-toggle` is installed.

## Implementation notes

- Uses Pi's native `builtin:codemode` extension.
- Uses `setActiveTools` to modify the active tool set.
- Does not modify Pi configuration when toggling.
- Does not implement its own Codemode runtime.
- Has no runtime dependencies.
- Source is available at https://github.com/iamaamir/pi-codemode-toggle