@ch4acko3/frontal-lobe

Frontal Lobe npm package.

This package contains the Node.js Gateway, Codex and Claude Code adapters, skills, workflow templates, debug dashboard, and native frontal-core binary.

The current npm package target is Apple Silicon macOS only (darwin-arm64). Install it from npm with the latest dist-tag unless you are testing a local tarball.

Install From npm

npm install -g @ch4acko3/frontal-lobe --foreground-scripts

--foreground-scripts is recommended because npm 7+ runs successful lifecycle scripts in the background by default, which can hide frontal start, frontal status, and the client refresh reminder printed by postinstall. Visible postinstall script lines are prefixed with [Frontal Install]:; forwarded backend command output is prefixed with [Frontal Backend]:. Important success and restart guidance is highlighted green. Bold is reserved for the two user actions, Restart or refresh Codex or Claude Code and enable the Frontal Codex Adapter plugin, plus the final status word: Enabled is blue and bold, while Unavailable is red and bold. Startup failures and recovery suggestions are highlighted red.

Update From npm

For normal updates after the package is installed, run:

frontal update

This runs npm update -g @ch4acko3/frontal-lobe --foreground-scripts. If the local npm installation needs repair, use:

frontal update --force

Package updates refresh local Frontal plugin and backend assets without running the first-install setup prompts again. Before refreshing an installed Codex plugin cache, update snapshots the active Frontal Hooks through Codex hooks/list. If the refreshed plugin adds a Hook key or changes the trusted hash for an existing key, update shows the affected event and command and asks Trust these new or changed Codex Hooks? [Y/n]. Pressing Enter approves the reviewed Hooks; entering n or no declines. Approval trusts only the exact reviewed key/hash pairs. Declining, running non-interactively, or failing to inspect the delta does not fail the package update; the affected Hooks remain untrusted and can be reviewed later with frontal codex-plugin trust-hooks. Unchanged Hooks that were previously left untrusted are not prompted again.

Codex provider takeover is transactional: the replacement Gateway must pass its strict health check before Codex config is committed. An interrupted update is recovered by the next frontal start or Codex session-start hook.

Human-readable frontal start, frontal stop, frontal status, frontal restart, and frontal uninstall output is also prefixed with [Frontal Backend]: and ends with short guidance explaining whether Frontal is usable and what to do next. Use --json when scripts need the raw machine report instead.

Install From A Local Tarball

For local package validation, install a generated tarball:

npm install -g ./ch4acko3-frontal-lobe-0.1.11.tgz --force --foreground-scripts

Smoke Test

After installation, confirm the bundled commands start:

frontal --version
frontal --help
frontal-core --help
frontal-gateway --help
frontal-codex --help
frontal-claude --help

Included Docs

The local tarball includes a focused docs set for teammate testing. After installation, find it under the global npm package root:

export FRONTAL_NPM_ROOT="$(npm root -g)/@ch4acko3/frontal-lobe"
ls "$FRONTAL_NPM_ROOT/docs"

Start with:

• docs/npm-getting-started.zh.md
• docs/npm-local-install.zh.md
• docs/direct-native-memory-quickstart.zh.md
• docs/direct-native-memory-e2e-test.zh.md

The package also includes the direct/native memory env template:

cp "$FRONTAL_NPM_ROOT/examples/direct-native-memory.env.example" .env.direct-native-memory.local

Register Client Adapters

npm postinstall starts the local Frontal backend, checks frontal status, and prints a reminder to restart or refresh Codex or Claude Code before opening a new Frontal session. Install with --foreground-scripts to see the startup steps, command output, and status check result. At the beginning, postinstall runs independent preflight checks only for the selected clients. Codex-only setup does not invoke Claude CLI or read Claude settings, and Claude-only setup does not invoke Codex CLI or read Codex config. If an explicitly selected client CLI is unavailable, setup reports Unavailable instead of silently falling back to another mode.

When Codex is selected, postinstall exposes the bundled Codex plugin in your personal Codex marketplace. It resolves CODEX_HOME when set, otherwise defaults to ~/.codex, stages the plugin under $CODEX_HOME/.frontal-lobe/plugins/frontal-codex-adapter, and updates ~/.agents/plugins/marketplace.json. The staging source is intentionally kept outside $CODEX_HOME/plugins/ so Codex does not index both the source and its installed cache as duplicate skills. If Codex already has the plugin installed in its local plugin cache, postinstall also refreshes that cache with codex plugin remove/add so upgraded hooks and skills are picked up by new Codex sessions. In provider/API key mode, frontal start can take over the Codex provider config and route model traffic through the local Gateway. It first stores a private real-upstream restore point, prepares the takeover without changing Codex config, restarts and validates Gateway, and only then commits Codex config. During a restart, failure to stop an already-active Gateway discards only the new prepare and preserves the previous committed route; once the old Gateway has stopped, replacement start, health, or commit failure aborts back to the real upstream. Gateway runtime reads that upstream from adapter state and does not watch managed Codex config or copy it back into state. A verified direct provider edit in Codex config is captured on the next start, stop, or SessionStart reconcile. In official OpenAI login mode, including provider tables that use requires_openai_auth = true, postinstall keeps the Codex provider config unchanged and starts Codex in memory-only mode with --no-provider-takeover; hooks and skills still use the local Gateway as the memory/control-plane backend.

On macOS, loopback Codex provider takeover also checks the active SystemConfiguration proxy before pending takeover recovery or config prepare. If a system HTTP, HTTPS, SOCKS, PAC, or auto-discovery proxy is active and the launchd environment for future GUI apps lacks complete loopback bypass, Frontal preserves existing entries, adds 127.0.0.1, localhost, ::1, and the exact selected loopback Gateway host to both NO_PROXY and no_proxy, verifies them, and installs a one-shot user LaunchAgent for login/reboot persistence. No active proxy, memory-only mode, non-loopback Gateway, and complete user-managed bypass cases remain unchanged. After a reported repair, fully quit and reopen Codex; an already-running app cannot inherit the new launchd environment. Frontal does not edit macOS proxy settings or ExceptionsList.

When Claude Code is selected, Frontal uses the official Claude CLI to add the bundled local marketplace and install frontal-claude-adapter@frontal-lobe-local at user scope. The plugin, hooks, and bundled skills are therefore available immediately after installation; they do not depend on a later lazy settings sync. In provider/API key mode, Claude Code setup also updates CLAUDE_CONFIG_DIR, CLAUDE_HOME, or ~/.claude settings for provider takeover. With built-in/official login, Frontal leaves the native provider path untouched and manages only the plugin, hooks, and skills without provider takeover.

During an interactive postinstall, first choose which clients Frontal should configure: all, claude, codex, or none. Choosing claude leaves Codex plugin/config untouched; choosing codex leaves Claude settings untouched; choosing none starts the shared Gateway without probing or configuring either client. The selection is saved in $FRONTAL_HOME/config.toml:

[clients]
codex = true
claude = false

When both managed clients expose compatible provider settings, postinstall also persists the selected shared Gateway upstream:

[model]
client_provider = "claude"

Later bare frontal start and frontal restart commands read this value again; the selection does not depend on postinstall-only environment flags. A complete local [model] provider (base_url plus api_key) still takes precedence.

Unqualified frontal start, frontal status, frontal stop, and frontal uninstall use this persisted selection. The postinstall skip environment variables skip only that installation action and do not rewrite the persisted selection.

When one selected client provider config is available, confirm whether to reuse that provider or answer n to enter a local Frontal provider. When both selected client provider configs are available, choose codex or claude to select the Frontal Gateway upstream, or choose n to enter a local Frontal provider instead. If Codex is selected while it is using official OpenAI login, there is no Codex upstream provider to reuse; Codex still gets plugin assets and memory hooks, but provider traffic stays on the official login path.

After frontal status completes, postinstall prints Frontal Lobe status: Enabled or Frontal Lobe status: Unavailable. The normal usage reminders are printed only when the status is Enabled; otherwise it prints red diagnostics and suggested checks. The end of the visible output includes a short common-command list for frontal status, frontal start, frontal stop, frontal-codex sessions, and frontal-claude sessions. If backend startup fails, postinstall tries a best-effort recovery with frontal stop followed by another frontal start, then prints diagnostics and manual recovery suggestions if the retry still fails.

If postinstall scripts are disabled or you want to refresh the registration and hook trust manually, run:

frontal codex-plugin install
frontal codex-plugin activate --yes

To skip automatic Codex marketplace registration and Codex postinstall takeover while keeping backend and Claude Code setup enabled, set:

FRONTAL_SKIP_CODEX_PLUGIN_INSTALL=1 npm install -g ./ch4acko3-frontal-lobe-0.1.11.tgz --foreground-scripts

To explicitly skip Claude Code adapter setup while keeping backend and Codex setup enabled, set:

FRONTAL_SKIP_CLAUDE_ADAPTER_INSTALL=1 npm install -g ./ch4acko3-frontal-lobe-0.1.11.tgz --foreground-scripts

To keep marketplace registration but skip installed-cache refresh, set:

FRONTAL_SKIP_CODEX_PLUGIN_CACHE_REFRESH=1 npm install -g ./ch4acko3-frontal-lobe-0.1.11.tgz --foreground-scripts

After registration, postinstall can activate the plugin and write hook trust when you answer y to Activate and trust Frontal Codex Adapter hooks now?. If you skip that step, restart Codex, open Plugins or /plugins, then install/enable Frontal Codex Adapter from the Personal marketplace. Hook approval prompts only appear after the plugin is activated in Codex. After activation and hook trust, the SessionStart hook checks the local Frontal Gateway. If the backend is unavailable, it silently runs frontal start so config takeover or memory-only reconcile happens only after the plugin is active. The hook does not inject status messages into the conversation; use frontal status or frontal-codex status to inspect the backend and adapter state.

If the Codex App plugin UI does not show hook approval prompts, activate from a terminal instead:

frontal codex-plugin activate

This explicitly installs/enables the plugin through the local Codex CLI, shows the Frontal hooks, asks for confirmation, and writes Codex hook trust. It does not need to start the backend when npm postinstall already did so. For automation after reviewing the hooks, pass --yes.

To review and trust the currently loaded Frontal Hooks without reinstalling, enabling, or migrating the plugin marketplace entry, run:

frontal codex-plugin trust-hooks

This is also the recovery command printed when an update cannot request Hook authorization interactively.

When the current Codex config uses official OpenAI login (either no explicit provider with auth.json, model_provider = "openai" without a model_providers.openai table, or a selected provider table with requires_openai_auth = true), postinstall uses --no-provider-takeover and leaves Codex config.toml untouched. Codex still gets Frontal plugin assets, hooks, $frontal-memory, and hook-driven memory writeback. If you later switch Codex to a regular provider/API key profile, the SessionStart hook can reconcile Codex back to provider takeover without reinstalling hooks or skills.

During an interactive npm postinstall, Frontal asks which clients to configure and, when needed, which selected client provider config the Gateway should use. Answer n at the provider prompt, or choose none at the client prompt, to use a local Frontal provider instead; the script prompts for provider API key and base URL, then writes them to $FRONTAL_HOME/config.toml under [model]. Gateway prefers that local provider over adapter upstreams, while any selected client config is still temporarily pointed at the Gateway and restored to its original contents on frontal stop or frontal uninstall.

The same interactive postinstall also asks whether to configure Memorax memory. Answer y to write [memorax].endpoint, [memorax].api_key, and [memorax].user_id to $FRONTAL_HOME/config.toml; the endpoint is written as http://test-code.beta.memorax.net by default and can be changed later in config.toml or with FRONTAL_MEMORAX_ENDPOINT. API key input is masked during interactive install, and scripted installs log only <provided>. Keep config.toml local because it can contain the Memorax API key. If you do not have a Memorax account/API key yet, register at http://test-code.beta.memorax.net before filling the prompt.

[memorax].user_id is the base user ID. Frontal derives a readable workspace-scoped ID for every real search/add request. Git worktrees of the same repository share memory, sessions in the same non-Git directory share memory, and different repositories/directories remain isolated. Codex tasks created without a project share the Codex-General scope. The postinstall does not issue an unscoped network probe; credentials are first checked by a scoped memory request made from a trusted workspace.

If frontal start detects that the Codex plugin is not prepared, interactive runs ask whether to install it now. Answer y to stage the Personal marketplace plugin; after installation, restart or refresh Codex and enable Frontal Codex Adapter from Plugins or /plugins.

Managed client lifecycle

Use --clients to override the persisted selection for one lifecycle command:

frontal start --clients claude
frontal status
frontal stop

Accepted values are codex, claude, codex,claude, all, and none. --clients takes precedence over the legacy --no-codex-adapter and --no-claude-adapter flags. When [model].client_provider is the active Gateway upstream because no explicit environment or complete local provider is configured, a start override must include that provider client; an incompatible start fails before changing either adapter or the Gateway. Stop and uninstall can still target an independent partial client scope. Start records a conservative cleanup scope before changing integrations, so later unqualified status, stop, and uninstall commands clean up every client touched by the attempt even if Gateway startup fails.

An explicit partial stop or uninstall touches only the selected client. If another managed client remains active, the Gateway stays running. A partial uninstall also preserves the shared npm package so the remaining client's plugin does not point at removed package assets:

frontal stop --clients codex
frontal uninstall --clients codex

Uninstall enters plugin and npm-package cleanup only after every selected client config has been restored and the Gateway stop phase succeeds. A failed stop keeps the active cleanup marker and plugin assets for retry. Claude plugin removal uses the official CLI keep-data mode, so plugin data is retained.

Codex provider recovery

Normal API/provider routing is Codex -> Gateway -> real upstream. If status reports a stale takeover or Gateway startup reports recursive provider routing, run:

frontal stop
frontal-codex repair-stale-takeover
frontal start

Repair prefers the authoritative upstream restore point and then a matching plugin recovery snapshot. If neither is available, switch back to the real Codex provider profile or repair $CODEX_HOME/config.toml; a verified current provider supersedes a polluted legacy upstream cache, so do not manually edit $FRONTAL_HOME/adapters/codex/. Advanced FRONTAL_MODEL_BASE_URL or local [model].base_url overrides must also point to a real upstream, never the current, default, or historical Gateway origin.

Isolated Codex Test

Use an isolated Codex home while testing provider takeover. This avoids changing the default Codex login/config used by your normal Codex app or CLI sessions.

export CODEX_HOME="$HOME/.codex-frontal-test"

frontal start \
  --provider-mode isolated \
  --session-mode direct \
  --codex-home "$CODEX_HOME"

frontal status

Then start Codex from the same shell when you want to test through that isolated home:

CODEX_HOME="$CODEX_HOME" codex

Stop Frontal when done:

frontal stop --codex-home "$CODEX_HOME"

Isolated Claude Code Test

Use an isolated Claude Code home while testing provider takeover:

export CLAUDE_CONFIG_DIR="$HOME/.claude-frontal-test"
export FRONTAL_HOME="$HOME/.frontal_lobe-claude-test"
export FRONTAL_GATEWAY_PORT=18787

frontal start \
  --home "$FRONTAL_HOME" \
  --clients claude \
  --session-mode direct \
  --force

frontal-claude status --claude-home "$CLAUDE_CONFIG_DIR" --frontal-home "$FRONTAL_HOME"

Then start Claude Code from the same shell:

CLAUDE_CONFIG_DIR="$CLAUDE_CONFIG_DIR" claude

Stop Frontal when done:

frontal stop --home "$FRONTAL_HOME" --clients claude

Memory Setup And End-To-End Tests

For native/direct memory setup, dashboard configuration, automatic search/add, active $frontal-memory skill usage, and end-to-end verification, follow the included guides:

• docs/npm-getting-started.zh.md
• docs/npm-local-install.zh.md
• docs/direct-native-memory-quickstart.zh.md
• docs/direct-native-memory-e2e-test.zh.md

Uninstall

frontal uninstall

Use frontal uninstall as the primary removal path. It stops the backend, restores the selected or active Codex and Claude Code config when Frontal is currently managing them, writes no replacement values into the current launchd environment, removes the Frontal-owned loopback-proxy LaunchAgent/helper when Codex is selected, writes a backend-removed marker, disables the staged Codex plugin entry, removes the Codex personal marketplace entry, asks Codex CLI to remove frontal-codex-adapter@personal when available, clears the installed Codex plugin cache, removes old $CODEX_HOME/plugins/frontal-codex-adapter staging left by earlier versions, removes the local Claude Code marketplace/plugin registration, and removes the global npm package when the command is running from the packaged npm install and the uninstall covers all managed clients. A partial client uninstall preserves the shared package and any Gateway still needed by another active client. Frontal user state is intentionally left in place.

Modern npm does not run uninstall lifecycle scripts. Running npm uninstall -g @ch4acko3/frontal-lobe directly removes the package files but cannot run the full Frontal cleanup first. If you already removed the package directly and still see the Codex plugin, remove it manually:

codex plugin remove frontal-codex-adapter@personal

The packaged Gateway also watches its npm package files while it is running. If the package is removed before frontal uninstall runs, active Gateway streams are interrupted with a frontal_backend_uninstalled failure event, provider requests are aborted, Codex recovery markers are written for installed Frontal plugin copies, and the Gateway process exits after best-effort config restore. This is only a safety net; frontal uninstall remains the recommended path because it can report cleanup details before the package files disappear.

For local validation from this repository, build and install the generated tarball:

make npm-package-check