@beforewave/agent-helm

Bring ChatGPT’s reasoning into your local engineering environment.

Agent Helm gives ChatGPT a stable local capability layer for working directly on your codebase:

• understand code and navigate symbols
• make structured code changes and refactors
• inspect diagnostics and recover the language server
• execute local commands
• discover and delegate to native coding agents when needed

ChatGPT remains the reasoning layer. Agent Helm provides the local engineering surface that lets those decisions act on the real workspace.

Install

Stable npm release:

npm install -g @beforewave/agent-helm

GitHub bootstrap:

curl -fsSL https://raw.githubusercontent.com/BeforeWave/agent-helm/main/install.sh | sh

Specific version:

curl -fsSL https://raw.githubusercontent.com/BeforeWave/agent-helm/main/install.sh | sh -s -- 0.1.4

Windows x64 (Windows 10/11 on ordinary Intel/AMD PCs):

# latest
irm https://raw.githubusercontent.com/BeforeWave/agent-helm/main/install.ps1 | iex

# specific version
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/BeforeWave/agent-helm/main/install.ps1))) -Version 0.1.4

The Windows wrapper supports win32-x64 only in the first release. It reuses Node.js 22+ when available; otherwise it downloads the official Node win-x64.zip, verifies SHA-256, and installs the runtime under the user's Agent Helm directory without replacing the system Node installation.

The stable raw wrapper resolves the selected GitHub Release to an exact target version first. If that exact Agent Helm version already exists on npm, the stable npm package is installed. Otherwise the same-version GitHub Release tgz is downloaded, SHA-256 verified, and installed locally through npm. The GitHub tgz bundles its exact @beforewave/agent-helm-ui-contract dependency; third-party dependencies continue to come from the npm registry. It never falls back to another npm version.

Standalone installation finishes in the generic agent-helm setup flow. Chrome integration is separate and can be configured later with agent-helm setup chrome.

Chrome Extension

For a clean Terminal-first Chrome installation:

curl -fsSL https://raw.githubusercontent.com/BeforeWave/agent-helm-extensions/main/install-chrome.sh | sh

To install a specific Extension version, pass the version to the same raw wrapper:

curl -fsSL https://raw.githubusercontent.com/BeforeWave/agent-helm-extensions/main/install-chrome.sh | sh -s -- 0.1.0

Windows x64 uses the same Extension Release contract through PowerShell:

# latest
irm https://raw.githubusercontent.com/BeforeWave/agent-helm-extensions/main/install-chrome.ps1 | iex

# specific Extension version
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/BeforeWave/agent-helm-extensions/main/install-chrome.ps1))) -Version 0.1.0

This Extension-owned bootstrap checks the Node.js runtime, installs the Agent Helm version pinned by that Extension release, registers the Native Messaging bridge, downloads and verifies the matching Extension, and places it under ~/Downloads/Agent-Helm-Chrome-Extension. The only remaining Chrome action is Developer mode → Load unpacked and selecting that directory.

Chrome Extension first (macOS)

The Chrome release and macOS Installer use the same entry-product version. For the current release relationship:

• Chrome Extension: 0.1.0
• Agent Helm Installer: 0.1.0
• Agent Helm pinned by both: 0.1.4

When the Extension shows Install required, click Download Installer. The Extension does not fetch compatibility metadata to choose a version at runtime. On macOS it downloads Agent-Helm-Installer-0.1.0.pkg; on Windows x64 it downloads Agent-Helm-Installer-0.1.0-win32-x64.cmd. Chrome requests the optional downloads permission only after this user action.

The Release PKG and the Chrome-downloaded PKG are the same bytes. The generic Release PKG already contains the official Extension ID and registers the official Native Messaging bridge. When Chrome downloads the same PKG, it may save the file locally with the current chrome.runtime.id in its filename; that filename acts only as an explicit bridge-ID override for development or alternate identities.

On Windows x64, double-click the downloaded CMD installer; it reuses the same PowerShell backend and shows Runtime / Node, Agent Helm, and Native Messaging bridge stages. The bridge is registered per-user through HKCU, so the normal Windows path does not require administrator rights.

If the macOS PKG is unsigned and Gatekeeper blocks it, open System Settings → Privacy & Security, choose Open Anyway, then open the PKG again. macOS Installer may also request administrator authorization.

To force Chrome back into the Install required flow without deleting Agent Helm configuration or Core state:

agent-helm uninstall-chrome-native-host

This removes only the Chrome Native Messaging manifest and its ~/.agent-helm/bin/chrome-native-host launcher. Reload the Extension afterward; the next connection probe will see the bridge as not installed. The command is idempotent.

Terminal fallback from the Extension uses the stable Extension raw wrapper with the Extension version as an argument:

curl -fsSL https://raw.githubusercontent.com/BeforeWave/agent-helm-extensions/main/install-chrome.sh | sh -s -- 0.1.0

The installer reuses an existing Node.js 22+ runtime when available. If Node is missing, too old, or does not provide npm, it downloads the manifest-pinned Node.js runtime from the official nodejs.org distribution, verifies SHA-256, and installs it privately under ~/.agent-helm/runtime/node. It does not install or upgrade a global Node.js, Homebrew, nvm, or another version manager.

Register the workspace and start the installed background runtime:

cd /path/to/workspace
agent-helm workspace add
agent-helm start

Daily checks and lifecycle control use the same small command surface:

agent-helm status
agent-helm doctor
agent-helm stop

For development/debugging, agent-helm start --foreground runs the same Core runtime in the current terminal. agent-helm daemon remains an internal runtime primitive rather than the normal user entrypoint.

agent-helm workspace add explicitly registers the workspace with Core. It does not create workspace-local Agent Helm configuration or overwrite the user configuration file.

DeepSeek Harness users normally do not install this package directly. Install @beforewave/dsh-with-chatgpt instead; it brings Agent Helm Core with it.

How it works

ChatGPT reasoning
      ↓
  Agent Helm
      ↓
 local workspace

      or

ChatGPT reasoning
      ↓
  Agent Helm
      ↓
native coding agent

Agent Helm owns the public capability and policy boundary. Serena is currently the internal code-intelligence provider, not a user-facing permission model.

Managed Serena is started lazily with only the semantic provider tools required by the configured MCP capability ceiling. External command, semantic, read-only, and delegation authority come from mcp.external; Native semantic and delegation authority come from mcp.native. External runtime user access can only narrow the configured External ceiling.

You do not configure Serena read_only, optional tool lists, context, or mode as Agent Helm permissions. Host capability ceilings use mcp.external and mcp.native. Workspace config describes workspace execution needs and provider-neutral semantic metadata; repo-local Serena configuration is not interpreted as Agent Helm policy.

Serena memory, onboarding, dashboard, and other unrelated tools are not exposed through Agent Helm. Managed Serena is launched headlessly with its web dashboard, GUI log window, and automatic browser opening disabled.

Configuration

Agent Helm has one user-scoped configuration authority:

~/.config/agent-helm/config.yml

There is no workspace-local Agent Helm config file. Repo-local .agent-helm/config.yml is not read as configuration. Workspace-specific settings live under the existing workspaces entry in the user config.

User-level execution settings provide inherited defaults and own MCP capability policy, service/runtime behavior, and allowUnsandboxed. execution.commandWorkers is a user-level host resource limit (default 4) controlling the maximum number of concurrent command execution workers; workspace config cannot override it. A workspace entry may add only execution and semantic overrides:

execution:
  commandWorkers: 4
  filesystem:
    allowFromEnv:
      - UV_CACHE_DIR

workspaces:
  - title: example
    path: ~/Workspace/example
    worktreeBasePath: ~/Workspace/example/.worktrees

    execution:
      filesystem:
        readOnly:
          - ../shared-reference
        allow:
          - ../shared-generated
        deny:
          - private
      commands:
        deny:
          - npm publish
      network:
        allow:
          - registry.npmjs.org
        allowLocalBinding: true

    semantic:
      languages:
        - typescript
      ignoredPaths:
        - generated/**
      respectGitignore: true

The selected working copy is implicit filesystem authority. User-level filesystem, command, env, network, deny-list, and local-binding settings are inherited by the workspace. filesystem.readOnly grants read-only access, filesystem.allow grants read/write access, and filesystem.deny is the restrictive override when rules overlap. Core-owned control data and common host credential locations remain protected even if a broader parent directory is allowed. Workspace read-only/allow/deny entries extend the corresponding inherited lists, and an explicit workspace allowLocalBinding overrides the inherited boolean. Relative workspace filesystem paths are resolved against the selected execution working copy, including linked worktrees.

filesystem.allowFromEnv is a single declaration: it automatically allows the named environment variable and, when its host value is non-empty, derives canonical filesystem authority from each path in that value. Missing or empty values add no filesystem authority and do not invalidate configuration. It does not resolve or guess missing paths and does not perform ${VAR} interpolation. Managed HOME/TMP* variables cannot be used as authority sources.

command_execute always routes through the execution backend. Destructive-operation guardrails and cwd validation run before execution, but when the execution sandbox is ready, command-text path analysis is not an authorization gate: filesystem, runtime, network, environment, and terminal deny authority are enforced by the sandbox from the computed execution-authority plan. When no ready sandbox is available, static shell-path analysis remains a fail-closed prerequisite for any degraded/unsandboxed execution path; the backend may still reject execution entirely. The backend starts command reads from a filesystem-root deny, then carves back only the selected execution authority plus bounded read-only runtime support such as PATH tool directories, audited runtime/toolchain roots, and required native or script dependencies. Parent directories needed only to reach an allowed path receive traversal metadata access rather than ordinary data-read access. Runtime authority never becomes writable authority, configured denies remain higher priority, and host integration capabilities such as credential stores or local service sockets are not promoted into runtime authority.

Host environment access is name-scoped rather than enumerable. Child execution reads host PATH by default for executable lookup, plus names explicitly granted by execution.env.allow; managed HOME/TMP*/default shell values are supplied by Agent Helm rather than inherited. Credential-bearing environment variables are not inherited as ordinary command environment, and local service sockets are not opened merely by granting filesystem access. npm global/user config paths are forced into the managed execution home, so npm does not probe host-global or user .npmrc files. Config loading reads only names referenced by filesystem.allowFromEnv. Agent Helm does not copy or enumerate the daemon's complete process.env.

Workspace entries cannot change mcp.external, mcp.native, daemon, HTTP, tunnel, workspace registry, host shell grants, answer limits, allowUnsandboxed, or commandWorkers.

Semantic workspace settings

Workspace code-intelligence settings are provider-neutral. Serena is the current backend, but it is not part of the workspace config schema.

.serena/project.yml and .serena/project.local.yml are not Agent Helm permission/config authorities. Migrate only provider metadata that still matters:

Serena language_servers               -> workspaces[].semantic.languages
Serena ignored_paths                  -> workspaces[].semantic.ignoredPaths
Serena ignore_all_files_in_gitignore  -> workspaces[].semantic.respectGitignore

Serena read_only, tool include/exclude lists, context, and mode do not become Agent Helm authority.

The short-lived Agent Helm serena.project.languageServers, serena.project.ignoredPaths, and serena.project.ignoreAllFilesInGitignore shape is also retired; migrate those fields to the corresponding workspaces[].semantic fields. Old serena.project config is rejected rather than treated as a compatibility authority. Managed Serena receives a generated translation of the effective semantic config under per-working-copy directories in ~/.agent-helm/serena/runtimes/; replacing Serena later does not change the workspace config contract.

Runtime defaults

Default runtime identifiers:

• MCP: http://127.0.0.1:3457/mcp
• Tunnel Admin UI: http://127.0.0.1:3458/ui
• adapter socket: ~/.agent-helm/run/daemon.sock (~/.agent-helm/run is owner-only 0700; the Unix socket is 0600)
• default token path: ~/.agent-helm/token
• token env: AGENT_HELM_TOKEN
• local token env: AGENT_HELM_LOCAL_TOKEN
• managed tunnel auth env: AGENT_HELM_AUTH
• launcher override env: AGENT_HELM_LAUNCHER_CONFIG_JSON

DSH

For direct work plus DSH delegation, use:

dsh plugin --profile web add @beforewave/dsh-with-chatgpt

That package is the user-facing DSH entry and manages the Core lifecycle while registering DSH as a native agent adapter.

macOS PKG release

On macOS, the installer artifact is built and checked with:

npm run verify:macos-pkg
npm run build:macos-pkg
npm run release:macos-pkg

release:macos-pkg produces dist/Agent-Helm-<version>.pkg plus its SHA-256 file for the matching BeforeWave/agent-helm release. release:oss:agent-helm invokes the same artifact preparation automatically when it runs on macOS.

The unsigned package is the current supported artifact. Future Developer ID signing does not change the installer architecture: set AGENT_HELM_PKG_SIGN_IDENTITY (or pass --sign-identity) so productsign signs the final flat PKG, then notarize/staple that same final artifact. The component package is not wrapped with productbuild, preserving the Extension-ID filename handoff.