@llmforagents/agent-helper

Configure llm4agents in popular AI tools and coding agents — and revert them safely.

Quick start

npx @llmforagents/agent-helper

The interactive UI walks you through:

1. Sign in — paste an existing sk-proxy-... key, or register a new agent (the CLI generates a deposit wallet and watches for the deposit)
2. Pick a tool — 17 bundled, plus any third-party adapters you have installed
3. Preview the diff — exact key-by-key changes that will be made to the tool's config
4. Apply — atomic write with both per-key diff manifest and a raw .bak of every file touched

To revert: pick Restore a tool to original in the main menu, or run agent-helper restore <toolId>.

Bundled adapters (17)

Coding agents (CLI) — 8

| Tool | Config | LLM | MCP | |---|---|---|---| | Claude Code (Anthropic) | ~/.claude/settings.json (jsonc) | ✓ | ✓ | | Codex (OpenAI) | ~/.codex/config.toml (toml) | ✓ | — | | Aider | ~/.aider.conf.yml (yaml) | ✓ | — | | Gemini CLI | ~/.gemini/settings.json (jsonc) | ✓ | ✓ | | Qwen Code | ~/.qwen/settings.json (jsonc) | ✓ | ✓ | | OpenCode (Charm) | ~/.config/opencode/opencode.json (jsonc) | ✓ | ✓ | | Crush (Charm) | ~/.config/crush/crush.json (jsonc) | ✓ | ✓ | | Goose (Block) | ~/.config/goose/config.yaml (yaml) | ✓ | ✓ |

Editor extensions — 6

| Tool | Config | LLM | MCP | |---|---|---|---| | Cursor | ~/.cursor/... settings.json (jsonc) | ✓ | ✓ | | Continue.dev | ~/.continue/config.json (jsonc) | ✓ | ✓ | | Windsurf | ~/.codeium/windsurf/settings.json (jsonc) | ✓ | ✓ | | Zed | ~/.config/zed/settings.json (jsonc) | ✓ | — | | Cline (VS Code) | cline_mcp_settings.json (jsonc) | ⚠️ manual | ✓ | | Roo Cline | cline_mcp_settings.json (jsonc) | ⚠️ manual | ✓ |

Clawbots (Claude-API-compatible) — 3

| Tool | Config | |---|---| | OpenClaw | ~/.config/openclaw/config.json (jsonc) | | ZeroClaw | ~/.config/zeroclaw/config.json (jsonc) | | Claudia (Asterisk) | ~/.claudia/config.json (jsonc) |

Notes:

• Some adapters are tagged (experimental — config format pending verification) in their meta.description. They're shipped on a best-effort basis and may need adjustment as upstream tools stabilize.
• Cline / Roo Cline: the MCP servers file is writable, but the LLM endpoint lives in VS Code's globalState (SQLite) which the adapter cannot edit. Apply prints a postApplyHints line with the exact value to paste into VS Code Settings → Cline.
• Windsurf currently writes both LLM and MCP entries into one settings.json. Multi-file MCP via mcp_config.json is a future enhancement.

Non-interactive flags (CI / scripting)

agent-helper apply <toolId>         [--scope global|project] [--api-key sk-proxy-...] [--yes]
agent-helper apply-all              [--category coding|editor|clawbot] [--installed-only] [--yes]
agent-helper restore <toolId>       [--scope global|project] [--yes]
agent-helper status                 [--json]
agent-helper register --name <n>    [--chain polygon|solana] [--token USDC|USDT] [--no-watch]
agent-helper list-adapters          [--installed-only]
agent-helper init-adapter <toolId>  [--scope @org] [--target <dir>]

When stdin is not a TTY (CI), --yes is required (the CLI refuses to apply silently without consent).

Authoring your own adapter

agent-helper init-adapter my-tool scaffolds a fully-typed adapter package (package.json with the required agentHelper marker, strict tsconfig.json, tsup.config.ts, source stubs, and a contract test wired to the public test kit).

Once published as agent-helper-adapter-my-tool (or @scope/agent-helper-adapter-my-tool) on npm and installed in node_modules, the host CLI auto-discovers it at startup — no registration step needed.

For the full guide:

• Quick start — your first adapter in 10 minutes
• Anatomy of an adapter — the ToolAdapter contract
• Detect & plan patterns
• Config formats — JSON / JSONC / TOML / YAML / env
• MCP integration
• Testing — using the contract test kit
• Publishing
• Troubleshooting
• Reference API — every export of @llmforagents/agent-helper/adapter-api
• Community adapters — share yours via PR

The public surface for adapter authors is exported as @llmforagents/agent-helper/adapter-api (types) and @llmforagents/agent-helper/test-kit (runContractTests). Internal modules are not part of the SemVer contract.

Plugin discovery

At startup the CLI builds the adapter registry from three sources, in this precedence:

1. Bundled — the 17 listed above, compiled into the published package
2. npm — packages matching agent-helper-adapter-* or @*/agent-helper-adapter-* in node_modules, auto-loaded when their package.json declares agentHelper.adapterId and a compatible apiVersion
3. Manual — paths listed in ~/.config/llm4agents/adapters.json (escape hatch for local development)

Conflicts between sources are silently shadowed — bundled wins over npm wins over manual. Warnings are written to ~/.config/llm4agents/logs/agent-helper.log.

Backups & restore

Every apply writes two artifacts under ~/.config/llm4agents/backups/<adapterId>/<scope>/:

1. Diff manifest (manifest.json) — Zod-validated record of every key path the adapter touched, with both old and new values + sha256 of the raw file
2. Raw .bak — a literal copy of the original file before any change (the unconditional safety net)

restore uses the diff to revert only the keys we changed; the .bak is verified against the recorded sha and applied if the diff is corrupt. Both are removed when restore succeeds.

The atomic transaction passes a property-based test (25 random JSON shapes per run) that exercises the round-trip. Concurrent apply invocations are serialized via proper-lockfile.

Release process (maintainers)

Releases are run interactively via scripts/release.sh. Autonomous CI does not publish.

./scripts/release.sh check       # typecheck + tests + integration + build
./scripts/release.sh bump        # interactive: patch|minor|major
./scripts/release.sh changelog   # opens $EDITOR on CHANGELOG.md
./scripts/release.sh build
./scripts/release.sh dry-run
NPM_TOKEN=npm_... ./scripts/release.sh publish
./scripts/release.sh tag         # creates agent-helper@v<version> (idempotent)
./scripts/release.sh smoke       # installs from npm in tempdir + verifies
./scripts/release.sh all         # all of the above with [y/N] between phases

Each phase prints === <Phase> === to stderr — parseable in agent logs.

License

MIT