agent-boosters

English · 한국어

Cross-platform CLI that installs and configures three AI-agent boosters in one shot: Caveman (prompt compression), Engram (persistent memory on your own Supabase), and lean-ctx (file read / grep / shell output compression). Memory syncs across every machine you install this on.

Not published on npm. Run directly from GitHub via npx.

Quick start

npx giljae/agent-boosters              # install (interactive)
npx giljae/agent-boosters --uninstall  # remove
npx giljae/agent-boosters --help
npx giljae/agent-boosters --lang ko    # force Korean output (auto-detected from $LANG)

If you do not already have a Supabase project and OpenAI API key, prepare those first. The installer will ask for them.

5-minute setup flow

Create a Supabase project.
Copy your Project URL, backend secret key, database password, Session pooler URI, and OpenAI API key.
Run npx giljae/agent-boosters (installs files only).
Let the installer bootstrap the Supabase schema when prompted.
Activate: source ~/.zshrc (or open a new terminal), then restart any agents the installer configured. See Activate for the full per-agent restart matrix.
Verify: ask your agent what MCP tools are available. Engram is connected if you see memory_recall, memory_ingest, etc.

What you get

Tool	What it does	Installed as
Caveman	Compresses your prompt style so each request uses fewer input tokens. Useful when you want concise agent replies by default.	`npx skills add JuliusBrussee/caveman --global --agent '*' -y`
Engram MCP	Gives your agents long-term memory stored in your Supabase project. Decisions and preferences can carry across sessions and PCs.	`npm i -g @engram-mem/mcp` (repo)
lean-ctx	Compresses what your agent reads — file contents, grep results, directory listings, and shell output — via MCP tools (`ctx_read`, `ctx_search`, `ctx_tree`, `ctx_shell`) plus optional shell hooks. Local-first, no API keys, cross-platform.	`npm i -g lean-ctx-bin` (repo)

Before you run the installer

You'll need one Supabase project and these values. Keep them ready before running npx giljae/agent-boosters.

What you need	Installer name	Where to get it
Supabase project	-	Create one at supabase.com. The free tier is enough.
Project URL (`https://<ref>.supabase.co`)	`SUPABASE_URL`	Project home page, right under the project name. Click Copy. The installer stores this as the PostgREST endpoint (`https://<ref>.supabase.co/rest/v1`) because `@engram-mem/mcp` expects the REST URL.
Backend secret key	`SUPABASE_KEY`	Settings -> API Keys -> Legacy API keys tab. Copy the `service_role` JWT (long `eyJ...` string, ~220 chars). *The new-format `sb_secret_` key does not work — PostgREST validates the JWT signature and rejects non-JWT tokens with `PostgREST connection failed: undefined`. You must use the legacy `service_role` JWT. Never use the `anon` / `publishable` key.**
Database password	Used inside the pooler URI	The password you set when creating the project. Forgot it? Use Settings -> Database -> Reset database password. This is not your Supabase account password.
Session pooler URI	Schema bootstrap URI	Project home -> Get connected -> Session pooler. Copy the URI and replace `[YOUR-PASSWORD]` with your database password.
OpenAI API key	`OPENAI_API_KEY`	platform.openai.com/api-keys. ChatGPT subscriptions do not include API usage; add API billing/credits under Billing. Engram uses `text-embedding-3-small` for embeddings and `gpt-4o-mini` for low-cost summarization/reranking.

Treat the backend secret key and database password like passwords. They bypass Row Level Security. Never commit them or paste them outside trusted tools.

Want to reduce OpenAI cost further? Set ENGRAM_RERANK_LOCAL=true in your environment to use a local reranker. Embeddings still call OpenAI; reranking becomes free.

What the installer does

Asks for your Supabase Project URL, backend secret key, and OpenAI API key.
Installs the tools you selected. macOS, Linux, WSL, and native Windows (PowerShell) are all fully supported. See Platform support.
On macOS/Linux/WSL, adds an idempotent config block to ~/.zshrc or ~/.bashrc:
```
# >>> AI Agent Boosters Configuration >>>
export SUPABASE_URL="..."
export SUPABASE_KEY="..."
export OPENAI_API_KEY="..."
# <<< AI Agent Boosters Configuration <<<
```
On native Windows, the installer calls [Environment]::SetEnvironmentVariable(..., 'User') directly so the same three variables are persisted for your user — no $PROFILE editing required.
Offers to bootstrap the Supabase schema for you. You paste a Session pooler URI with your password substituted, and the installer downloads and applies schema.sql against your project. This is needed once per Supabase project and is shared across all PCs.
Detects installed agents and auto-registers Engram MCP into each one's config. Agents that require manual setup are listed at the end with a copy-paste snippet.
If Codex CLI or Pi is detected and Caveman is selected, adds a managed block to ~/.codex/AGENTS.md or ~/.pi/agent/AGENTS.md so that agent uses Caveman mode by default.
If lean-ctx is selected, runs lean-ctx setup once installed — it auto-detects supported agents (Cursor, Claude Code, Codex, Gemini, Windsurf, Copilot, and more) and wires up MCP plus optional shell hooks.

Nothing is hardcoded. Your secrets never leave your machine. The installer only talks to your Supabase project, your OpenAI account, and the npm registry.

If you'd rather bootstrap the schema by hand

You can skip the installer's bootstrap prompt and apply schema.sql yourself. Two paths:

Path A — psql with the Session pooler URI (cleanest, handles pg_dump v17 meta-commands natively):

curl -O https://raw.githubusercontent.com/muhammadkh4n/engram/main/packages/postgrest/schema.sql
psql "<your Session pooler URI with password>" -f schema.sql

Why Session pooler? IPv4 (works everywhere) + supports DDL. Avoid the Transaction pooler (:6543) — it cannot run schema commands. Direct connections are IPv6-only by default.

No psql? macOS: brew install libpq && brew link --force libpq. Ubuntu/Debian: sudo apt install postgresql-client. Windows: install PostgreSQL or use WSL.

Path B — Supabase SQL Editor (no psql needed, but you must strip two pg_dump v17 artifacts first). The full recipe lives under Supabase schema not applied in Troubleshooting below — it has the ready-to-paste Windows / Unix one-liner that fetches schema.sql, removes \restrict / \unrestrict, patches the empty search_path, and copies the result to your clipboard.

The schema is idempotent, so re-running is safe.

Activate (required after install)

Installation only puts files in place. The three tools become active only after these steps. Do them once per machine.

1. Refresh your shell environment (macOS / Linux / WSL)

The installer wrote SUPABASE_URL / SUPABASE_KEY / OPENAI_API_KEY into ~/.zshrc (or ~/.bashrc), but your current terminal session predates that change.

source ~/.zshrc      # or: source ~/.bashrc
# or just open a new terminal window

Engram MCP for Claude Code does not depend on this — claude mcp add -e ... baked the env into ~/.claude.json already. But Codex CLI and any tool you launch from this terminal will rely on the shell env.

Windows users: see Windows: env vars not showing in the current PowerShell? below.

2. Restart every agent the installer configured

MCP servers and skills are loaded at agent startup. Each agent the installer touched needs one restart:

Agent	How to restart
Claude Code	Quit and relaunch the `claude` session (or run `/reload` if your build supports it)
Claude Desktop	Quit the app from the menu bar / system tray, then relaunch
Cursor (IDE)	Quit and relaunch Cursor
Cursor CLI	New terminal session
Windsurf	Quit and relaunch
Gemini CLI	New terminal session
Codex CLI	New terminal session
Pi	Restart Pi or run `/reload`

3. Verify each tool

Open your agent and paste these prompts one by one. No personal data needed — each prompt just checks whether the tool is wired up.

Caveman

/caveman
Is caveman active?

Expected: response in compressed caveman style (short fragments, articles dropped).

lean-ctx

Is lean-ctx active?

Expected: agent confirms ctx_read / ctx_search / ctx_tree / ctx_shell tools are loaded. You can also run lean-ctx status in a terminal.

Engram

Is Engram active? Run a quick test.

Expected: agent calls memory_ingest with a test marker, then memory_recall to fetch it back. If both succeed, Engram is reading and writing your Supabase project.

If any tool does not respond as above, restart that agent one more time and re-run the prompt.

Notes

If env-var expansion does not work in a GUI agent, hard-code the values into that agent's config file.
Keep config files containing SUPABASE_KEY out of version control.

Verify after install

(See the Activate section above for the full restart and verification flow. The Windows-specific note below handles a common gotcha for native PowerShell users.)

Windows: env vars not showing in the current PowerShell?

The installer registers SUPABASE_URL / SUPABASE_KEY / OPENAI_API_KEY at User scope via [Environment]::SetEnvironmentVariable. PowerShell's $env: only reflects variables inherited at process start, so the window the installer ran in won't see them until you do one of:

Open a new PowerShell window — the simplest path. New windows inherit User-scope variables automatically.

Load them into the current window without restarting:

$env:SUPABASE_URL    = [Environment]::GetEnvironmentVariable("SUPABASE_URL","User")
$env:SUPABASE_KEY    = [Environment]::GetEnvironmentVariable("SUPABASE_KEY","User")
$env:OPENAI_API_KEY  = [Environment]::GetEnvironmentVariable("OPENAI_API_KEY","User")

Verify the User-scope value directly (works in any window):
```
[Environment]::GetEnvironmentVariable("SUPABASE_URL","User")
```
If this returns the value, registration succeeded — the current $env: just hasn't picked it up yet.

Either way, always launch your agent (Claude Code, Codex, Cursor, etc.) from a new terminal so it inherits the variables.

Connecting Engram to your agent

The installer detects agents on your machine and offers to register Engram automatically. Agents that cannot be auto-configured are listed at the end with a snippet to copy.

Auto-registered

The installer registers Engram for each of these if detected. Re-run the installer any time to update env vars.

Agent	What the installer touches
Claude Code (CLI)	Runs `claude mcp add engram engram-mcp -e SUPABASE_URL=... -e SUPABASE_KEY=... -e OPENAI_API_KEY=...`
Cursor (IDE + CLI, shared config)	Merges into `~/.cursor/mcp.json`
Windsurf	Merges into `~/.codeium/windsurf/mcp_config.json`
Claude Desktop	Merges into `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) · `%APPDATA%\Claude\claude_desktop_config.json` (Windows) · `~/.config/Claude/claude_desktop_config.json` (Linux). Restart Claude Desktop after.
OpenAI Codex (CLI)	Adds a managed Engram block to `~/.codex/config.toml`. Restart Codex after.
Gemini CLI	Merges into `~/.gemini/settings.json`
Google Antigravity (2.0 / CLI / IDE)	Merges into `~/.gemini/antigravity/mcp_config.json` and `~/.gemini/antigravity-cli/mcp_config.json`. Restart Antigravity after.
Pi	Writes an Engram bridge extension to `~/.pi/agent/extensions/agent-boosters-engram.ts`. Pi does not need MCP config; the extension exposes Engram as native Pi tools. Restart Pi or run `/reload`.
Reasonix Code	Adds an Engram entry to the `mcp` array in `~/.reasonix/config.json`. Environment variables are inherited from the shell. Start a new session to load the new MCP server.

Existing mcpServers entries are preserved. For Codex, only the engram server block is replaced. For Pi, only the managed agent-boosters-engram.ts extension is written/removed. The original file is backed up to *.bak.agent-boosters before writes.

Manual registration

These agents require you to paste the config yourself. The installer detects them and prints the snippet at the end of the run.

Agent	Where to paste
GitHub Copilot (VS Code)	`.vscode/mcp.json` in each workspace (docs)
Cline / Roo Code	VS Code extension settings -> "MCP Servers" -> Add server
OpenCode	`opencode.json` in your project root
Continue, Aider, etc.	Use the JSON snippet below; check the agent's MCP docs for the config path

Not applicable (cannot be supported)

These surfaces do not accept user-defined MCP servers — Anthropic / OpenAI control their connector lists centrally, so neither this installer nor any third-party tool can add Engram to them. Desktop/CLI apps that read ~/.codex/config.toml are covered by the OpenAI Codex (CLI) entry above.

Codex Cloud / Web / Slack / Chrome extension. These use centrally managed connectors rather than a local user MCP config.
Claude apps inside chat surfaces that don't expose MCP settings (rare; the desktop Claude apps listed above do expose MCP and are auto-configured).

JSON snippet

Works for Cursor, Windsurf, Claude Desktop, Antigravity, Gemini CLI, OpenCode, and most other GUI agents:

{
  "mcpServers": {
    "engram": {
      "command": "npx",
      "args": ["-y", "-p", "@engram-mem/mcp", "engram-mcp"],
      "env": {
        "SUPABASE_URL": "https://<ref>.supabase.co/rest/v1",
        "SUPABASE_KEY": "eyJhbGciOi...",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

GUI agents often do not see your shell's PATH, so the npx form is more reliable for them.

TOML snippet (Codex CLI fallback)

The installer writes this automatically when Codex CLI is detected. Use this only if you need to configure Codex by hand.

[mcp_servers.engram]
command = "npx"
args = ["-y", "-p", "@engram-mem/mcp", "engram-mcp"]
env = { SUPABASE_URL = "https://<ref>.supabase.co/rest/v1", SUPABASE_KEY = "eyJhbGciOi...", OPENAI_API_KEY = "sk-..." }

Caveman

Caveman ships as a vercel-labs/skills package, an open skill format supported by 40+ agents. The installer registers it into every agent on your machine in one shot.

When Codex CLI, Pi, or Google Antigravity is detected, the installer also enables Caveman as the default response mode by adding a managed block to ~/.codex/AGENTS.md, ~/.pi/agent/AGENTS.md, or ~/.gemini/GEMINI.md. Existing global instructions are preserved, and the block is removed by --uninstall.

Manage installed skills:

npx skills list
npx skills update

lean-ctx

The installer runs lean-ctx setup once lean-ctx-bin is installed. That command auto-detects supported agents and wires up the MCP server (and optional shell hooks where applicable). To configure additional agents later:

lean-ctx setup                  # auto-detect everything
lean-ctx init --agent cursor    # specific agent
lean-ctx init --agent claude-code
lean-ctx init --agent codex
lean-ctx init --agent windsurf
lean-ctx status                 # show what's configured

See yvgude/lean-ctx for the full list of supported agents.

Tool and agent compatibility

	Claude Code	Cursor	Windsurf	Pi	Reasonix Code	Codex / Gemini / Cline / Copilot / 20+
Caveman	auto	auto	auto	auto (`AGENTS.md`)	auto (via shared `~/.claude/CLAUDE.md`)	auto
Engram	MCP	MCP	MCP	native Pi extension bridge	MCP (via `~/.reasonix/config.json`)	wherever MCP is supported
lean-ctx	MCP + hook	MCP + hook	MCP + hook	MCP	MCP	MCP (hybrid hook where supported)

Platform support

Platform	Caveman	Engram MCP	lean-ctx
macOS	Yes	Yes	Yes
Linux	Yes	Yes	Yes
Windows (WSL)	Yes	Yes	Yes
Windows (PowerShell/cmd)	Yes	Yes	Yes

All three tools run natively on every platform. On native Windows the installer registers the env vars as User-scope environment variables via PowerShell, so a new terminal picks them up automatically without editing $PROFILE.

Troubleshooting

Problem	What to try
`engram-mcp` is "command not found"	Use the `npx` command form shown in JSON snippet, or make sure the global npm bin directory is on the agent's `PATH`.
MCP tools do not appear after install	Restart the agent fully (close the application, not just the window — GUI apps often keep child MCP processes alive in the background). Then ask the agent to list MCP tools.
Engram returns `PostgREST connection failed` or `PGRST205 Could not find the table`	First confirm `SUPABASE_URL` ends with `/rest/v1`; `@engram-mem/mcp` expects the PostgREST endpoint, not only the project home URL. If it already does, the Supabase project probably does not have Engram's schema applied yet. See Supabase schema not applied below.
Supabase schema bootstrap fails	Check that you used the Session pooler URI, replaced `[YOUR-PASSWORD]`, and avoided the Transaction pooler on port 6543. You can also run the schema in the Supabase SQL Editor.
Wrong Supabase project	If you have multiple Supabase projects, the schema must be applied to the same project that `SUPABASE_URL` points to. Run `[Environment]::GetEnvironmentVariable("SUPABASE_URL","User")` (Windows) or `echo $SUPABASE_URL` (Unix) to confirm. The project ref is the subdomain (`https://<ref>.supabase.co`).
Engram works on one machine but not another	Both machines must point to the same Supabase project (same `SUPABASE_URL`, same `SUPABASE_KEY`). Re-run the installer on the failing machine and paste the same Supabase Project URL you used elsewhere.
`PostgREST connection failed: undefined` with schema applied	You're using the new-format `sb_secret_` key. PostgREST validates JWT signatures and rejects non-JWT tokens. Switch to the legacy `service_role`* JWT (`Settings → API Keys → Legacy API keys` tab, ~220-char `eyJ...` string).
`429 You exceeded your current quota`	This is OpenAI API billing/quota, not ChatGPT Plus/Pro. Check Usage, Billing, Credit grants, and Limits.
lean-ctx tools missing in an agent	Run `lean-ctx status` to see what was configured, then `lean-ctx init --agent <name>` for any that need to be added manually.
OpenAI cost concerns	Use `ENGRAM_RERANK_LOCAL=true` to make reranking local. Embeddings still use OpenAI.

Supabase schema not applied

If memory_recall / memory_ingest return PostgREST connection failed or a PGRST205 error, Engram's tables don't exist in the Supabase project that SUPABASE_URL points to. Even if you bootstrapped the schema "previously" on another machine, that only counts if it was the same project.

Step 1 — Verify which project you're hitting:

# Windows
[Environment]::GetEnvironmentVariable("SUPABASE_URL","User")

# macOS / Linux
echo $SUPABASE_URL

Compare the <ref> in https://<ref>.supabase.co to the project name in your Supabase dashboard.

Step 2 — Apply the schema via SQL Editor (recommended; the installer's auto-bootstrap also works if you have a Session pooler URI. It uses Node's Postgres client, so psql is not required for the installer path).

Engram's schema.sql is generated by pg_dump v17 and includes two artifacts that Supabase's SQL Editor cannot parse, so we patch them before pasting:

\restrict / \unrestrict — psql-only meta commands. Strip them.
set_config('search_path', '', false) — empties the search path so unqualified CREATE TABLE statements have nowhere to go (ERROR 3F000: no schema has been selected to create in). Replace with public, pg_catalog.

Windows PowerShell — copy-paste this entire block:

# 1. Download fresh schema.sql
Invoke-WebRequest "https://raw.githubusercontent.com/muhammadkh4n/engram/main/packages/postgrest/schema.sql" `
  -OutFile $env:TEMP\schema.sql -UseBasicParsing

# 2. Strip psql meta commands + patch empty search_path
$src = "$env:TEMP\schema.sql"
$dst = "$env:TEMP\schema-clean.sql"
(Get-Content $src) |
  Where-Object { $_ -notmatch '^\\(restrict|unrestrict)\b' } |
  ForEach-Object {
    $_ -replace "set_config\('search_path', '', false\)", "set_config('search_path', 'public, pg_catalog', false)"
  } |
  Set-Content $dst -Encoding utf8

# 3. Copy cleaned SQL to clipboard
Get-Content $dst -Raw | Set-Clipboard
Write-Output "Cleaned schema copied to clipboard ($((Get-Item $dst).Length) bytes)"

macOS / Linux:

curl -sSL https://raw.githubusercontent.com/muhammadkh4n/engram/main/packages/postgrest/schema.sql \
  | grep -vE '^\\(restrict|unrestrict)\b' \
  | sed "s/set_config('search_path', '', false)/set_config('search_path', 'public, pg_catalog', false)/" \
  | pbcopy   # macOS  (Linux: replace pbcopy with `xclip -selection clipboard` or `xsel -b`)

Step 3 — Paste and run:

Open the SQL Editor for this project: https://supabase.com/dashboard/project/<ref>/sql/new
Click in the empty editor → Ctrl+A → Delete (in case there's a template) → Ctrl+V
Click Run (or Ctrl+Enter). The bottom result panel should show set_config = public, pg_catalog (the last statement's return value) and no red error box.

Step 4 — Verify the tables exist:

$url = [Environment]::GetEnvironmentVariable("SUPABASE_URL","User")
$key = [Environment]::GetEnvironmentVariable("SUPABASE_KEY","User")
$restUrl = $url.TrimEnd('/')
if ($restUrl -notmatch '/rest/v1$') { $restUrl = "$restUrl/rest/v1" }
Invoke-WebRequest "$restUrl/memories?select=count" `
  -Headers @{ apikey=$key; Authorization="Bearer $key"; Prefer="count=exact" } `
  -UseBasicParsing | Select-Object StatusCode, @{n='Range';e={$_.Headers.'Content-Range'}}

url="${SUPABASE_URL%/}"
case "$url" in */rest/v1) rest_url="$url" ;; *) rest_url="$url/rest/v1" ;; esac
curl -i "$rest_url/memories?select=count" \
  -H "apikey: ${SUPABASE_KEY}" \
  -H "Authorization: Bearer ${SUPABASE_KEY}" \
  -H "Prefer: count=exact"

StatusCode 200 and Range */0 means the schema is applied and memories table is empty. (Note: it's memories, not messages — Engram v0.4.x renamed.)

Step 5 — Quit your agent fully and relaunch. For GUI apps:

Close all windows
Quit from the system tray icon if present
Verify via Task Manager (Windows) / Activity Monitor (macOS) that no Claude.exe / Claude Code.exe / etc. process is left
Relaunch

Then in a new session: Remember that my name is Foo. → What was my name again? — memory_recall should return the stored answer.

Uninstalling

npx giljae/agent-boosters --uninstall

This removes:

The lean-ctx-bin global npm package
The @engram-mem/mcp global npm package
The Caveman skill from every agent it was installed in
Auto-registered Engram MCP entries, including the managed Codex block
The agent-boosters config block from your shell rc. A .bak.agent-boosters backup is kept.

This does not remove:

Your Supabase project or its tables. They are shared across your machines, so the uninstaller leaves them alone.
Manual-only MCP registrations. Delete the engram entry from those agent config files yourself.

Issues

If you hit a bug, have an install problem, or want to request support for another agent, please open an issue:

https://github.com/giljae/agent-boosters/issues

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 51 Commits
.gitignore		.gitignore
LICENSE		LICENSE
README.ko.md		README.ko.md
README.md		README.md
STRATEGY.md		STRATEGY.md
agents.js		agents.js
i18n.js		i18n.js
index.js		index.js
package-lock.json		package-lock.json
package.json		package.json
schema.js		schema.js
test-smoke.mjs		test-smoke.mjs

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

agent-boosters

Quick start

5-minute setup flow

What you get

Before you run the installer

What the installer does

Activate (required after install)

1. Refresh your shell environment (macOS / Linux / WSL)

2. Restart every agent the installer configured

3. Verify each tool

Notes

Verify after install

Windows: env vars not showing in the current PowerShell?

Connecting Engram to your agent

Auto-registered

Manual registration

Not applicable (cannot be supported)

JSON snippet

TOML snippet (Codex CLI fallback)

Caveman

lean-ctx

Tool and agent compatibility

Platform support

Troubleshooting

Supabase schema not applied

Uninstalling

Issues

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

agent-boosters

Quick start

5-minute setup flow

What you get

Before you run the installer

What the installer does

Activate (required after install)

1. Refresh your shell environment (macOS / Linux / WSL)

2. Restart every agent the installer configured

3. Verify each tool

Notes

Verify after install

Windows: env vars not showing in the current PowerShell?

Connecting Engram to your agent

Auto-registered

Manual registration

Not applicable (cannot be supported)

JSON snippet

TOML snippet (Codex CLI fallback)

Caveman

lean-ctx

Tool and agent compatibility

Platform support

Troubleshooting

Supabase schema not applied

Uninstalling

Issues

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages