Skip to main content

n3Plugins Environment Profiles

This document defines execution-environment behavior.

Identify the environment before substantive repository work.

1. Environment Profiles​

Select exactly one primary profile:

WINDOWS_LOCAL
CODEX_CLOUD_LINUX
OTHER

Do this once per session unless the environment changes.

Do not continuously re-detect the environment.

2. WINDOWS_LOCAL​

Use this profile when commands execute on native Windows.

Assume:

  • native Windows filesystem semantics,
  • PowerShell or Windows-compatible command execution,
  • Windows Gradle wrapper execution,
  • local developer applications may exist,
  • local RuneLite may exist,
  • local MCP integrations may exist,
  • Linux tooling is not assumed.

Potential availability is not guaranteed availability.

Probe a capability only when the task needs it.

Windows local setup scripts​

Before the first toolchain-dependent compile/test/build operation, verify the local environment:

.\scripts\windows\doctor.ps1

Required baseline:

JDK 11
repository Gradle wrapper (gradlew.bat)
Gradle 8.5 through the wrapper
Git
curl
jq
ripgrep (rg)
Node.js >=20 when agent-mcp is in scope
npm when agent-mcp is in scope

For its JDK check, doctor.ps1 uses valid JAVA_HOME\bin\java.exe and javac.exe first, then falls back to PATH. A newer system Java may remain first on PATH when JAVA_HOME correctly points to the project JDK 11.

If required capabilities are missing, run the one-time setup script:

.\scripts\windows\setup.ps1

setup.ps1 will:

  • install missing utilities (curl, jq, ripgrep) via winget when available,
  • install Eclipse Temurin JDK 11 via winget when JDK 11 is not active,
  • write a persistent environment file at $HOME\.n3plugins-windows-env.ps1,
  • validate and bootstrap the Gradle wrapper,
  • install and build tools/agent-mcp when present,
  • install pinned CodeGraph, codebase-memory-mcp, and Serena when enabled and uv is available.

Do not run setup.ps1 repeatedly after it succeeds once.

Recommended environment values (set via system environment variables or the sourced env file):

N3_ENVIRONMENT=WINDOWS_LOCAL
JAVA_HOME=<path to JDK 11 installation>
GRADLE_USER_HOME=%USERPROFILE%\.cache\n3plugins\gradle
N3_WINDOWS_CACHE=%USERPROFILE%\.cache\n3plugins

The setup script writes these defaults to $HOME\.n3plugins-windows-env.ps1 when the system does not provide them. Dot-source this file in agent sessions or your PowerShell profile:

. "$HOME\.n3plugins-windows-env.ps1"

Gradle​

Use:

.\gradlew.bat <task> --console plain

Examples:

.\gradlew.bat test --console plain
.\gradlew.bat build --console plain

Do not default to:

./gradlew
chmod +x gradlew
apt install ...
sudo ...
export ...
/tmp/...

unless execution is inside a Unix-compatible environment.

Do not introduce WSL to perform work that functions natively on Windows.

Filesystem​

Use the repository root discovered from the active workspace.

Do not translate:

C:\Users\...

into guessed paths such as:

/mnt/c/Users/...

unless such a mount is confirmed.

Never hard-code developer-specific local paths into:

  • production source,
  • tests,
  • configuration,
  • generated defaults,
  • committed documentation intended as runtime configuration.

Inspect local reference paths when relevant, but do not make them runtime dependencies.

Local RuneLite​

Validate local RuneLite behavior only when:

  • a usable client is available,
  • the required plugin build is installed/running,
  • the relevant account/game state exists,
  • the agent has a real supported interface to observe or control it.

Do not assume local RuneLite because execution occurs on Windows.

3. CODEX_CLOUD_LINUX​

Cloud workspaces (Codespaces, DevContainers, cloud IDEs, CI runners) are isolated Linux workspaces.

Assume:

  • Linux filesystem semantics,
  • Linux shell semantics,
  • isolated repository checkout,
  • no access to the user's arbitrary Windows filesystem,
  • no access to Windows desktop applications,
  • no automatic access to the user's local RuneLite process,
  • no automatic access to localhost services running on another machine,
  • no automatic inheritance of local credentials, SDKs, caches, or MCP services.

Required cloud toolchain​

Before the first toolchain-dependent compile/test/build operation:

bash scripts/codex/doctor.sh

Required baseline:

JDK 11
repository Gradle wrapper
Gradle 8.5 through the wrapper
Git
curl
unzip
ripgrep
Node.js >=20 when agent-mcp is in scope
npm when agent-mcp is in scope

In cloud environment settings, pin Java 11 and Node 20 through the Universal image. Configure these lifecycle commands:

Setup script:       bash scripts/codex/setup.sh
Maintenance script: bash scripts/codex/maintenance.sh

Setup runs with internet access and prepares the cached default-branch image. Maintenance runs after the environment checks out the task branch in a resumed image. Agents run doctor.sh; they do not invoke maintenance themselves.

Recommended non-secret environment values:

N3_ENVIRONMENT=CODEX_CLOUD_LINUX
GRADLE_USER_HOME=$HOME/.cache/n3plugins/gradle
N3_CLOUD_CACHE=$HOME/.cache/n3plugins

Do not copy a literal $HOME value into an environment-settings UI that does not perform shell expansion. The setup script writes these defaults to the sourced cloud environment file when the UI does not provide them.

If required capabilities are missing:

bash scripts/codex/setup.sh

Do not repeatedly run setup after it succeeds.

Building tools/agent-mcp in Cloud​

When working on or validating tools/agent-mcp in cloud environments:

cd tools/agent-mcp
npm ci --no-audit --no-fund
npm run build

This ensures TypeScript compilation from src/ to dist/index.js succeeds in the isolated workspace.

Gradle ownership​

The repository wrapper owns the project Gradle version.

Use:

./gradlew <task> --console plain

The wrapper currently resolves the project's pinned Gradle distribution.

Do not:

  • install a second standalone Gradle because the wrapper needs to download its distribution,
  • change the wrapper version to accommodate the cloud image,
  • upgrade the project's Java target because a newer JDK happens to be installed,
  • commit downloaded Gradle distributions,
  • commit downloaded JDKs.

Executable wrapper​

Only run:

chmod +x gradlew

when the executable bit is missing.

Do not perform it on every task.

Cloud filesystem boundary​

Do not attempt to access arbitrary user-local paths such as:

C:\Users\...
C:\Program Files\...
%APPDATA%
%USERPROFILE%

Do not waste execution attempting guessed mount translations.

Network failures​

If a required dependency cannot be downloaded:

  1. confirm the actual network/domain failure once,
  2. identify which validation is blocked,
  3. continue work not requiring that dependency,
  4. do not redesign project dependencies around a temporary cloud restriction.

Do not repeatedly try random mirrors.

Persistent environment​

Setup-time shell exports may not survive later commands.

Persistent cloud values should come from:

  • configured cloud environment variables,
  • repository scripts,
  • a sourced user-level environment file created by setup.

Never commit secrets.

The setup script installs pinned CodeGraph, Serena, and codebase-memory-mcp releases unless their N3_INSTALL_* switches are set to 0. .codex/config.toml owns MCP startup. Both repository-intelligence MCP servers are optional so their failure cannot prevent normal shell and source work.

Do not configure the n3 Agent Server's loopback endpoint in an ordinary cloud environment. Building and testing tools/agent-mcp is valid static validation; connecting it to the user's Windows RuneLite process requires an explicitly engineered authenticated remote transport.

4. OTHER​

When execution is neither native Windows nor a cloud Linux workspace:

  1. inspect the actual OS,
  2. inspect shell semantics,
  3. select the closest valid execution rules,
  4. note material differences,
  5. do not assume package managers or filesystem behavior.

5. Capability Probing​

Probe a capability once.

Example:

Need Serena
  ↓
Check availability once
  ├─ available → use it
  └─ unavailable → record fallback and continue

Do not repeatedly attempt:

  • alternate command names,
  • equivalent package installs,
  • reconnect loops,
  • guessed filesystem paths,
  • unavailable MCP services,

unless new evidence changes the situation.