apex-code 0.0.1-alpha.1 → 0.0.1-alpha.2

package/docs/containerization.md

@@ -1,25 +1,28 @@
 # Containerization
 
-Pi runs with all permissions by default, but in some cases, you will want to have more control over what directories Pi can write to and which accesses it has.
+Apex Code has its own permission gate and, on Linux and macOS, an OS-level sandbox (see
+[Security](security.md)); Windows has no supported sandbox backend, and even where the
+built-in sandbox applies, you may want stronger or environment-level control over what
+directories Apex Code can write to and which accesses it has.
 
 There are two general options. You can either
-1. run the whole `pi` process inside an isolated environment, or
-2. run `pi` on the host and route tool execution into an isolated environment.
+1. run the whole `apex-code` process inside an isolated environment, or
+2. run `apex-code` on the host and route tool execution into an isolated environment.
 
 ## Choose a pattern
 
 | Pattern | What is isolated | Best for | Notes |
 | --- | --- | --- | --- |
 | Gondolin extension | Built-in tools and `!` commands | Local micro-VM isolation while keeping auth on host | See [`examples/extensions/gondolin/`](../examples/extensions/gondolin/). |
-| Plain Docker | Whole `pi` process in a local container | Simple local isolation | Provider API keys enter the container. |
-| OpenShell | Whole `pi` process in a policy-controlled sandbox | Local or remote managed sandbox | Requires an OpenShell gateway |
+| Plain Docker | Whole `apex-code` process in a local container | Simple local isolation | Provider API keys enter the container. |
+| OpenShell | Whole `apex-code` process in a policy-controlled sandbox | Local or remote managed sandbox | Requires an OpenShell gateway |
 
-Extensions run wherever the `pi` process runs. If you run host `pi` with a tool-routing extension, other custom extension tools still run on the host unless they also delegate their operations.
+Extensions run wherever the `apex-code` process runs. If you run host `apex-code` with a tool-routing extension, other custom extension tools still run on the host unless they also delegate their operations.
 
 ## Gondolin
 
 [Gondolin](https://github.com/earendil-works/gondolin) is a local Linux micro-VM.
-Use the [example extension](../examples/extensions/gondolin) when you want `pi` on the host but all built-in tools routed into the VM.
+Use the [example extension](../examples/extensions/gondolin) when you want `apex-code` on the host but all built-in tools routed into the VM.
 
 Setup:
 
@@ -33,7 +36,7 @@ Run from the project you want mounted:
 
 ```bash
 cd /path/to/project
-pi -e ~/.apex-code/agent/extensions/gondolin
+apex-code -e ~/.apex-code/agent/extensions/gondolin
 ```
 
 The extension mounts the host cwd at `/workspace` in the VM and overrides `read`, `write`, `edit`, `bash`, `grep`, `find`, and `ls`.
@@ -44,9 +47,9 @@ Requirements: Node.js >= 23.6.0 for `@earendil-works/gondolin`, plus QEMU (requi
 
 ## Plain Docker
 
-Run the whole `pi` process in Docker when you want the simplest local container boundary.
+Run the whole `apex-code` process in Docker when you want the simplest local container boundary.
 
-`Dockerfile.pi`:
+`Dockerfile.apex-code`:
 
 ```dockerfile
 FROM node:24-bookworm-slim
@@ -57,24 +60,24 @@ RUN apt-get update \
 RUN npm install -g --ignore-scripts apex-code
 
 WORKDIR /workspace
-ENTRYPOINT ["pi"]
+ENTRYPOINT ["apex-code"]
 ```
 
 Build and run:
 
 ```bash
-docker build -t pi-sandbox -f Dockerfile.pi .
+docker build -t apex-code-sandbox -f Dockerfile.apex-code .
 
 docker run --rm -it \
   -e ANTHROPIC_API_KEY \
   -v "$PWD:/workspace" \
-  -v pi-agent-home:/root/.pi/agent \
-  pi-sandbox
+  -v apex-code-agent-home:/root/.apex-code/agent \
+  apex-code-sandbox
 ```
 
 The `-v "$PWD:/workspace"` mounts your current directory into the container at /workspace such that reads and writes in `/workspace` inside Docker directly affect your host files, like in the Gondolin example.
 
-Use a named volume for `/root/.pi/agent` if you want container-local settings and sessions. Mounting your host `~/.apex-code/agent` exposes host auth and session files to the container.
+Use a named volume for `/root/.apex-code/agent` if you want container-local settings and sessions. Mounting your host `~/.apex-code/agent` exposes host auth and session files to the container.
 
 ## OpenShell
 
@@ -89,23 +92,23 @@ openshell gateway add <gateway-url> --name <name>
 openshell gateway select <name>
 ```
 
-Launch `pi` inside an OpenShell sandbox:
+Launch `apex-code` inside an OpenShell sandbox:
 
 ```bash
-openshell sandbox create --name pi-sandbox --from pi -- pi
+openshell sandbox create --name apex-code-sandbox --from apex-code -- apex-code
 ```
 
-In this pattern, the whole `pi` process runs inside the sandbox.
+In this pattern, the whole `apex-code` process runs inside the sandbox.
 Built-in tools, `!` commands, and extension tools execute inside the OpenShell boundary.
 
 If the gateway is remote, project files are not bind-mounted from the host, meaning writes in the sandbox are not reflected on your machine.
 Clone the repository inside the sandbox or use OpenShell file transfer commands:
 
 ```bash
-openshell sandbox upload pi-sandbox ./repo /workspace
-openshell sandbox download pi-sandbox /workspace/repo ./repo-out
+openshell sandbox upload apex-code-sandbox ./repo /workspace
+openshell sandbox download apex-code-sandbox /workspace/repo ./repo-out
 ```
 
 OpenShell providers can keep raw model API keys outside the sandbox.
 When inference routing is configured, code inside the sandbox can call `https://inference.local`, and the gateway injects the configured provider credentials upstream.
-Configure Pi to use the corresponding OpenAI-compatible or Anthropic-compatible endpoint if you want model traffic to use this route.
+Configure Apex Code to use the corresponding OpenAI-compatible or Anthropic-compatible endpoint if you want model traffic to use this route.

package/docs/custom-provider.md

@@ -30,7 +30,7 @@ See these complete provider examples:
 
 ## Quick Reference
 
-Extensions can register either a complete pi-ai `Provider` or use the legacy provider-config form. Prefer a complete provider when custom authentication, filtering, refresh, or streaming behavior is required. Pi composes `models.json` overrides above registered native providers.
+Extensions can register either a complete pi-ai `Provider` or use the legacy provider-config form. Prefer a complete provider when custom authentication, filtering, refresh, or streaming behavior is required. Apex Code composes `models.json` overrides above registered native providers.
 
 ```typescript
 import { createProvider, openAICompletionsApi } from "@earendil-works/pi-ai";
@@ -88,7 +88,7 @@ export default function (pi: ExtensionAPI) {
 }
 ```
 
-The extension factory can also be `async`. For dynamic model discovery, fetch and register models in the factory instead of `session_start`. pi waits for the factory before startup continues, so the provider is available during interactive startup and to `pi --list-models`.
+The extension factory can also be `async`. For dynamic model discovery, fetch and register models in the factory instead of `session_start`. Apex Code waits for the factory before startup continues, so the provider is available during interactive startup and to `apex-code --list-models`.
 
 ## Override Existing Provider
 
@@ -239,7 +239,7 @@ models: [{
   id: "custom-model",
   // ...
   reasoning: true,
-  thinkingLevelMap: {              // map pi levels to provider values; null hides unsupported levels
+  thinkingLevelMap: {              // map Apex Code levels to provider values; null hides unsupported levels
     minimal: null,
     low: null,
     medium: null,
@@ -566,14 +566,14 @@ calculateCost(model, output.usage);
 
 ### Context Overflow Errors
 
-When a request exceeds the model's context window, pi can recover automatically by compacting the conversation and retrying. This recovery only kicks in if pi recognizes the failure as an overflow.
+When a request exceeds the model's context window, Apex Code can recover automatically by compacting the conversation and retrying. This recovery only kicks in if Apex Code recognizes the failure as an overflow.
 
 Detection runs on the finalized assistant message:
 
 - `stopReason === "error"`
-- `errorMessage` matches one of pi's known overflow patterns (see [`packages/ai/src/utils/overflow.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/utils/overflow.ts))
+- `errorMessage` matches one of Apex Code's known overflow patterns (see [`packages/ai/src/utils/overflow.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/utils/overflow.ts))
 
-If your provider returns overflow errors with a message pi does not recognize, normalize the error from the same extension that registers the provider. Use a `message_end` handler to rewrite the assistant message so its `errorMessage` starts with a phrase pi recognizes. The generic fallback `context_length_exceeded` is the safest choice.
+If your provider returns overflow errors with a message Apex Code does not recognize, normalize the error from the same extension that registers the provider. Use a `message_end` handler to rewrite the assistant message so its `errorMessage` starts with a phrase Apex Code recognizes. The generic fallback `context_length_exceeded` is the safest choice.
 
 ```typescript
 const MY_PROVIDER_OVERFLOW_PATTERN = /your provider's overflow phrase/i;
@@ -605,7 +605,7 @@ export default function (pi: ExtensionAPI) {
 }
 ```
 
-`message_end` runs before pi tracks the assistant message for auto-compaction, so the rewritten `errorMessage` is what pi checks. With this in place, pi will:
+`message_end` runs before Apex Code tracks the assistant message for auto-compaction, so the rewritten `errorMessage` is what Apex Code checks. With this in place, Apex Code will:
 
 1. Detect the overflow from `errorMessage`.
 2. Drop the failed assistant message from live context.
@@ -615,7 +615,7 @@ export default function (pi: ExtensionAPI) {
 Guard the rewrite carefully:
 
 - Scope it to your provider (`message.provider` and `ctx.model?.provider`) so unrelated errors from other providers are untouched.
-- Match a provider-specific pattern, not pi's generic overflow patterns. Rewriting rate-limit or throttling errors (`rate limit`, `too many requests`) would falsely trigger compaction instead of pi's normal retry-with-backoff path.
+- Match a provider-specific pattern, not Apex Code's generic overflow patterns. Rewriting rate-limit or throttling errors (`rate limit`, `too many requests`) would falsely trigger compaction instead of Apex Code's normal retry-with-backoff path.
 - Skip when `errorMessage` already includes `context_length_exceeded` so the handler is idempotent.
 
 ### Registration
@@ -713,7 +713,7 @@ interface ProviderModelConfig {
   /** Whether the model supports extended thinking. */
   reasoning: boolean;
 
-  /** Maps pi thinking levels to provider/model-specific values; null marks a level unsupported. */
+  /** Maps Apex Code thinking levels to provider/model-specific values; null marks a level unsupported. */
   thinkingLevelMap?: Partial<Record<"off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max", string | null>>;
 
   /** Supported input types. */

package/docs/development.md

@@ -1,38 +1,38 @@
 # Development
 
-See [AGENTS.md](https://github.com/earendil-works/pi-mono/blob/main/AGENTS.md) for additional guidelines.
+See [AGENTS.md](https://github.com/Fchery87/apex-code/blob/main/AGENTS.md) for additional guidelines.
 
 ## Setup
 
 ```bash
-git clone https://github.com/earendil-works/pi-mono
-cd pi-mono
+git clone https://github.com/Fchery87/apex-code
+cd apex-code
 npm install
 npm run build
 ```
 
-Run from source:
+Run tests from source:
 
 ```bash
-/path/to/pi-mono/pi-test.sh
+/path/to/apex-code/test.sh
 ```
 
-The script can be run from any directory. Pi keeps the caller's current working directory.
+The script can be run from any directory. Apex Code keeps the caller's current working directory.
 
 ## Forking / Rebranding
 
-Configure via `package.json`:
+Apex Code itself is a fork of Pi configured this way. Configure via `package.json`:
 
 ```json
 {
   "piConfig": {
-    "name": "pi",
-    "configDir": ".pi"
+    "name": "apex-code",
+    "configDir": ".apex-code"
   }
 }
 ```
 
-Change `name`, `configDir`, and `bin` field for your fork. Affects CLI banner, config paths, and environment variable names.
+Change `name`, `configDir`, and `bin` field for your own fork. Affects CLI banner, config paths, and environment variable names. `piConfig` is the retained upstream key name for this mechanism, not a reference to a running "pi" product.
 
 ## Path Resolution
 
@@ -48,7 +48,7 @@ Never use `__dirname` directly for package assets.
 
 ## Debug Command
 
-`/debug` (hidden) writes to `~/.apex-code/agent/pi-debug.log`:
+`/debug` (hidden) writes to `~/.apex-code/agent/apex-code-debug.log`:
 - Rendered TUI lines with ANSI codes
 - Last messages sent to the LLM
 

package/docs/environment-variables.md

@@ -1,88 +1,47 @@
-# Environment Variables
+# Environment variables
 
-Pi uses environment variables in three ways:
+Apex Code uses canonical `APEX_CODE_*` variables for its owned runtime controls and
+subprocess metadata. Provider API-key variables remain documented in
+[Providers](providers.md#environment-variables-or-auth-file).
 
-- Variables such as `PI_OFFLINE` configure the Pi process.
-- Pi sets `PI_CODING_AGENT` so child processes can detect that they run inside Pi.
-- Commands run by the LLM-callable bash tool receive `PI_*` variables describing the current session.
-
-Provider API-key variables are documented separately in [Providers](providers.md#environment-variables-or-auth-file).
-
-## Process Marker
-
-The CLI and RPC entry points set `PI_CODING_AGENT=true`. Child processes inherit it and can use it to detect that they run inside Pi. It is not session-specific and is not set automatically when Pi is embedded through the SDK.
-
-## Bash Tool Session Environment
-
-Commands run by the bash tool receive the current Pi session state:
+## Runtime controls
 
 | Variable | Description |
-|----------|-------------|
-| `PI_SESSION_ID` | Current session ID |
-| `PI_SESSION_FILE` | Absolute path to the current session JSONL file; unset for ephemeral sessions |
-| `PI_PROVIDER` | Currently selected model provider |
-| `PI_MODEL` | Currently selected model ID |
-| `PI_REASONING_LEVEL` | Current effective reasoning level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` |
-
-The values are resolved when each command starts. Switching models or changing the reasoning level therefore affects the next bash command without restarting Pi. `PI_PROVIDER` and `PI_MODEL` identify the selected Pi model, not a different upstream model that a router may choose internally.
-
-When asked which model or provider is running, inspect these variables instead of inferring the answer from the system prompt:
-
-```bash
-printf '%s/%s\n' "$PI_PROVIDER" "$PI_MODEL"
-printf 'reasoning=%s session=%s\n' "$PI_REASONING_LEVEL" "$PI_SESSION_ID"
-```
+| --- | --- |
+| `APEX_CODE_CODING_AGENT_DIR` | Config root; defaults to `~/.apex-code/agent` |
+| `APEX_CODE_CODING_AGENT_SESSION_DIR` | Override session storage |
+| `APEX_CODE_PACKAGE_DIR` | Override package assets (for Nix/Guix paths) |
+| `APEX_CODE_OFFLINE` | Disable startup network operations |
+| `APEX_CODE_SKIP_VERSION_CHECK` | Disable the npm `apex-code@next` version request |
+| `APEX_CODE_EXPERIMENTAL` | Enable experimental features when set to `1` |
+| `APEX_CODE_STARTUP_BENCHMARK` | Enable startup benchmarking |
+| `APEX_CODE_TIMING` | Enable timing diagnostics when set to `1` |
+| `APEX_CODE_CLEAR_ON_SHRINK` | Clear context on shrink when set to `1` |
+| `APEX_CODE_HARDWARE_CURSOR` | Show the hardware cursor when set to `1` |
+| `APEX_CODE_MODEL_CATALOG_URL` | Optional base URL for remote model catalog overlays; unset uses bundled catalogs only |
+| `APEX_CODE_SHARE_VIEWER_URL` | Optional base URL for preview links after `/share`; unset returns the GitHub Gist URL only |
+| `VISUAL`, `EDITOR` | External editor fallback |
+| `HTTP_PROXY`, `HTTPS_PROXY` | Proxy outbound HTTP requests |
 
-The session file can be inspected directly when the session is persistent:
+The CLI and RPC entry points set `APEX_CODE_CODING_AGENT=true`. Commands run through
+the built-in bash tool receive `APEX_CODE_SESSION_ID`, `APEX_CODE_SESSION_FILE`,
+`APEX_CODE_PROVIDER`, `APEX_CODE_MODEL`, and `APEX_CODE_REASONING_LEVEL`. Values are
+resolved when each command starts. User-entered `!` and `!!` commands do not receive
+this session metadata.
 
 ```bash
-if [ -n "$PI_SESSION_FILE" ]; then
-  tail -n 1 "$PI_SESSION_FILE"
-fi
+printf '%s/%s\n' "$APEX_CODE_PROVIDER" "$APEX_CODE_MODEL"
+printf 'reasoning=%s session=%s\n' "$APEX_CODE_REASONING_LEVEL" "$APEX_CODE_SESSION_ID"
 ```
 
-These variables are injected into the LLM-callable bash tool. They are not injected into user-entered `!` or `!!` commands.
-
-### Custom Bash Tools
+## Temporary legacy aliases
 
-Bash tools created with `createBashTool()` expose the session environment by default when registered with Pi. Injection happens before `spawnHook`, so a hook receives the variables in `ctx.env`:
-
-```typescript
-const bashTool = createBashTool(cwd, {
-  spawnHook: (ctx) => ({
-    ...ctx,
-    env: { ...ctx.env, CI: "1" },
-  }),
-});
-```
-
-Disable session metadata independently of the spawn hook:
-
-```typescript
-const bashTool = createBashTool(cwd, {
-  exposeSessionEnvironment: false,
-  spawnHook: (ctx) => ctx,
-});
-```
-
-When disabled, Pi removes inherited values for these variables so nested Pi processes do not expose stale parent-session metadata.
-
-## Pi Process Configuration
-
-These variables are read by Pi itself:
-
-| Variable | Description |
-|----------|-------------|
-| `PI_CODING_AGENT_DIR` | Override the config directory; default is `~/.apex-code/agent` |
-| `PI_CODING_AGENT_SESSION_DIR` | Override session storage; overridden by `--session-dir` |
-| `PI_PACKAGE_DIR` | Override the package directory, useful for Nix/Guix store paths |
-| `PI_OFFLINE` | Disable startup network operations, including update checks, package updates, and install/update telemetry |
-| `PI_SKIP_VERSION_CHECK` | Disable the `pi.dev` latest-version request |
-| `PI_TELEMETRY` | Override install/update telemetry and provider attribution headers: `1`/`true`/`yes` or `0`/`false`/`no` |
-| `PI_CACHE_RETENTION` | Set to `long` for extended provider prompt caching where supported |
-| `PI_SHARE_VIEWER_URL` | Override the base URL used by `/share` |
-| `PI_HARDWARE_CURSOR` | Set to `1` to show the hardware cursor; see [Terminal setup](terminal-setup.md) |
-| `VISUAL`, `EDITOR` | External editor fallback when `externalEditor` is unset |
-| `HTTP_PROXY`, `HTTPS_PROXY` | Proxy outbound HTTP requests |
+The equivalent `PI_*` names remain aliases during the compatibility window. Apex Code
+reads the canonical name first; when both are set, the canonical value wins. A
+legacy-only read emits one deprecation diagnostic per process. Apex Code exports both
+forms to child processes during this window so existing scripts continue working.
 
-Provider credentials such as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and cloud-provider configuration are listed in [Providers](providers.md#environment-variables-or-auth-file).
+Legacy aliases will be removed no earlier than Apex Code 1.0.0 and no earlier than
+2027-02-16. Removal requires release notes and an intentional compatibility-test
+change. Consumed dependency variables, provider API-key variables, and extension API
+vocabulary are not part of this rename.