CostLayers CLI

CostLayers is a cost-optimization layer for coding-agent teams. It starts with a local repo scan, gives Codex a compact context pack, labels every savings number by evidence source, and gives API users invoice-mode savings proof.

Quick Start

ChatGPT-login Codex, no API key required:

cd your-repo
npx -y costlayers@latest codex --email [email protected] --chatgpt

This one command scans the repo, writes .agentspend/repo-pack.md and .agentspend/runtime-plan.md, installs ~/.codex/costlayers.config.toml, prints the private dashboard URL, and launches Codex as codex --profile costlayers. Codex keeps its native ChatGPT-login auth. This mode measures local repeated-context reduction and Codex usage stretch; it does not claim a ChatGPT subscription invoice reduction.

OpenAI Platform API invoice mode:

cd your-repo
export CODEX_API_KEY=sk-proj-...
npx -y costlayers@latest codex --email [email protected] --api

This routes API-billed Codex model calls through the CostLayers gateway. API invoice savings are counted only after OpenAI Platform traffic is actually routed through CostLayers and provider usage is observed.

Run a free AI spend audit before changing a workflow:

cd your-repo
npx -y costlayers@latest audit --monthly-spend 10000

Use your real monthly AI spend if you have it. Omit --monthly-spend to get a repo-only audit. The audit writes .agentspend/ai-spend-audit.md and labels scan estimates separately from verified invoice savings. A plain audit/scan stays local unless you pass --email, already have a hosted connection, or opt into telemetry.

Run a one-command API savings test:

export CODEX_API_KEY=sk-proj-...
npx -y costlayers@latest test --email [email protected]

costlayers test sends the read-only Codex prompt on stdin so quoted prompts work consistently on Windows and Unix shells. If your Codex CLI rejects the newer explicit stdin form, CostLayers retries the compatible stdin form without dropping read-only sandboxing.

Usage

Inside a repo:

npx -y costlayers@latest audit --monthly-spend 10000

Then run Codex with CostLayers:

npx -y costlayers@latest codex --email [email protected] --chatgpt

This gives Codex .agentspend/repo-pack.md and .agentspend/runtime-plan.md so it can avoid repeated broad repo exploration. It also writes ~/.codex/costlayers.config.toml and runs Codex as codex --profile costlayers, enabling redacted Codex telemetry for ChatGPT-login sessions while preserving Codex's native model provider.

This mode is for getting more useful work out of the same ChatGPT/Codex plan. It does not reduce a flat ChatGPT subscription invoice.

Invoice Savings Mode

To reduce an OpenAI Platform invoice, route API-key billed model calls through the CostLayers gateway. This requires an OpenAI Platform API key with Responses API write permission:

export CODEX_API_KEY=sk-proj-...
npx -y costlayers@latest codex --email [email protected] --api

ChatGPT-login Codex can be metered, but it does not create per-request OpenAI Platform invoice savings because it is not billed through your Platform API key.

Which Mode Should I Use?

• ChatGPT-login Codex: use costlayers codex --email [email protected] --chatgpt to reduce repeated repo context and stretch usage limits.
• OpenAI Platform API billing with Codex: set CODEX_API_KEY, then use costlayers codex --email [email protected] --api for invoice-backed savings.
• Savings proof with Codex: set CODEX_API_KEY, then run costlayers test --email [email protected].
• Full-potential local protocol: run costlayers optimize --task "..." before repeated workflows.
• Local replay cache: run costlayers replay --task "architecture overview" --check before repeating broad analysis.
• Privacy-safe proof export: run costlayers proof --refresh.
• Local code-memory bridge: run costlayers memory to detect codebase-memory-mcp, CodeGraph, or the built-in CostLayers semantic-slice fallback; use costlayers memory --query "login flow" for an active local query and costlayers memory --doctor for install and verification commands.
• Free audit: run costlayers audit --monthly-spend <usd> before changing a workflow.
• Other OpenAI-compatible clients: point the client at the CostLayers gateway URL and check costlayers gateway report.

Trust Labels

CostLayers separates the measurements it prints:

• Local context estimate: visible immediately from the repo scan.
• Local replay candidate: visible from costlayers replay or costlayers cache; this is a local hash match, not provider invoice proof.
• Local code-memory routing: visible from costlayers memory; this is a source-free route receipt for codebase-memory-mcp, CodeGraph, or CostLayers semantic slices, not invoice proof.
• Full-potential plan: visible from costlayers optimize; this is a local execution plan plus receipts for seven optimization components, not provider invoice proof.
• ChatGPT-login usage stretch: appears after Codex profile token events; this is not a provider invoice claim.
• API invoice savings: appears only after API-billed traffic is routed through the CostLayers gateway.

Local Replay Cache

costlayers scan and costlayers start refresh .agentspend/replay-summary.md so agents can check whether a broad analysis has an exact local candidate before repeating it:

npx -y costlayers@latest replay --task "architecture overview" --check
npx -y costlayers@latest cache --task "architecture overview"

replay and cache hash the repo state, task or prompt, and optional --tool-output files. They do not store source code, prompt text, or tool-output content in the replay summary or ledger. .agentspend/.gitignore excludes the local replay ledger.

Workflow Capture

Use costlayers workflow around repeated commands, tests, search jobs, evals, or build/log analysis you expect the agent to rerun:

npx -y costlayers@latest workflow --task "run unit tests" -- npm test

The command runs normally, prints stdout/stderr, writes local output receipts under .agentspend/workflow-runs/, and updates replay, tool-cache, workflow compression, and full-potential certificates. Those receipts are local evidence only; they are not provider invoice proof.

For more privacy-sensitive runs, keep only hashes and the local manifest:

npx -y costlayers@latest workflow --task "run unit tests" --no-store-output -- npm test

Full-Potential Local Protocol

costlayers optimize writes a local plan for reducing repeated agent work without shipping private internals, storing raw prompts, or claiming provider invoice savings from local-only evidence:

npx -y costlayers@latest optimize --task "fix the login flow"

The plan has seven components:

• Local code-memory routing: active when codebase-memory-mcp or CodeGraph is detected; otherwise the built-in CostLayers semantic-slice fallback is active.
• Prompt-delta execution: active local rules that send the changed task intent plus references to stable .agentspend artifacts instead of repeating broad context.
• Cross-session reuse: advisory until hashes match a prior replay row; exact matches can guide reuse, stale rows must be treated as hints.
• Tool-result caching: advisory unless current --tool-output hashes match stored receipts; stale or missing outputs should be rerun.
• Agent workflow compression: advisory rules for repeated analysis/test loops; they never replace required verification.
• Model routing: active policy guidance for local memory or cheaper summarization on lookup/planning, with the strong coding model kept for edits and final judgment.
• API invoice gateway: active only after API-billed traffic is routed through the CostLayers gateway; this is the only path for provider-dollar savings proof.

Operational reuse candidates:

• Use .agentspend/memory-bridge.md, .agentspend/memory-routing-summary.md, and .agentspend/semantic-slices.md before broad repo reads for architecture, ownership, dependency, and entrypoint questions.
• Use .agentspend/prompt-delta.md when only the task intent changed and stable repo context can be referenced instead of resent.
• Use .agentspend/replay-summary.md and .agentspend/replay-ledger.jsonl only when the repo hash and task or prompt hash match the current work.
• Use .agentspend/tool-cache-index.md and .agentspend/workflow-runs/ only when command inputs and output hashes match.
• Use .agentspend/workflow-compression.md for repeated scan, search, test, build, lint, eval, or log-review loops; it does not replace required verification.
• Use .agentspend/model-routing-plan.md for lookup and planning, while keeping the strong coding model for edits and final review.
• Use costlayers gateway report rows for provider-dollar proof only after API-billed traffic is routed through the CostLayers gateway.

Quality boundary: CostLayers should not degrade or rewrite opaque prompts just to save tokens. It uses local graph/slice lookup, stable artifact references, hash receipts, and guarded compaction boundaries. When the boundary is not clear, the agent should read the source, rerun the tool, or use the strong model rather than treating an estimate as proof.

Do not skip source review for edits, security-sensitive behavior, public API changes, migrations, production configuration, or precise user-facing claims. Do not skip tools when inputs changed, hashes are missing, dependency state changed, or the receipt is stale. Local stage estimates can overlap, so do not add structural lookup, prompt delta, replay, workflow compression, and tool-cache numbers into one dollar claim.

These artifacts are local context/reuse estimates unless the API invoice gateway component is connected and gateway rows exist. Provider-dollar proof still requires API-mode traffic through the CostLayers gateway.

To test the repeated-workflow target on a real external repo, prove or reject it in sequence:

1. Pick one repeated workflow and define the quality gate before optimizing.
2. Run the local precheck: costlayers audit, costlayers memory, and costlayers optimize --task "<workflow name>".
3. Capture a baseline for the same workflow, model class, repo state window, and quality gate.
4. Stage receipts with costlayers workflow --task "<workflow name>" -- <command> and costlayers replay --task "<workflow name>" --check.
5. Run the optimized workflow using exact reuse only; rerun stale or missing receipts and keep strong-model review where correctness depends on it.
6. Save costlayers gateway report, run costlayers proof --refresh, and run the proof harness with the saved gateway report.

Count a 2x-5x repeated-workflow result only when gateway-routed API rows show that reduction against the baseline and the agreed quality gate still passes. If rows are missing, hashes are stale, or quality fails, report the gap instead of claiming the target.

Public Benchmark Suite

Use bench-suite to run the same command-based tasks across one or more repos and write a hash-only public report:

npx -y costlayers@latest bench-suite \
  --repos repos.json \
  --tasks tasks.json \
  --baselines plain,costlayers \
  --runs 1 \
  --out proof_artifacts/bench-suite

repos.json can be an array or an object with a repos array. Paths are resolved relative to the config file:

{
  "repos": [
    { "id": "example", "path": "." }
  ]
}

tasks.json can be an array or an object with a tasks array. Command arrays are preferred; strings are run through the platform shell.

{
  "tasks": [
    {
      "id": "unit-tests",
      "task": "run unit tests",
      "command": ["npm", "test"],
      "runs": 1,
      "baselines": {
        "plain": { "command": ["npm", "test"] },
        "costlayers": {
          "command": ["npm", "test"],
          "baseline-runs": 1,
          "optimized-runs": 1
        }
      }
    }
  ]
}

The plain baseline runs the configured command directly. The costlayers baseline invokes the existing costlayers benchmark command for that repo and task, so it also writes .agentspend/full-potential-benchmark.json and .agentspend/full-potential-benchmark.md in the repo being tested.

The suite writes:

• <out>/bench-suite-report.json
• <out>/bench-suite-report.md

Those reports include repo and task identifiers, task hashes, command hashes, exit statuses, wall time, byte counts, stdout/stderr hashes, and CostLayers benchmark artifact hashes. They do not include source code, task text, command text, raw command output, prompts, API keys, or provider responses.

Claim boundary: bench-suite is local command timing and receipt evidence. It does not run Codex by itself, does not prove provider-dollar savings, and does not claim reduction of a flat ChatGPT subscription invoice. Provider-dollar claims require API-mode gateway rows or a proof report generated from those rows.

To install only the Codex profile after signup:

npx -y costlayers@latest codex-profile
codex --profile costlayers

API-mode proof run:

export CODEX_API_KEY=sk-proj-...
npx -y costlayers@latest test --email [email protected]
npx -y costlayers@latest gateway report
npx -y costlayers@latest proof --refresh

costlayers test is API invoice-mode only. It starts a read-only Codex task through the gateway and then prints the gateway report. If CODEX_API_KEY is missing, the command exits with setup instructions instead of producing an invoice-savings claim.

Metered gateway savings increase only when model API traffic is routed through the CostLayers gateway URL with a provider API key. Codex-metered dashboard savings for ChatGPT-login Codex are usage-stretch measurements from observed Codex token events; they are not OpenAI Platform invoice reductions.

The hosted reducer uses guarded, labeled reductions:

• exact cache hits may skip repeated upstream calls
• certified compaction preserves the current user request
• prior context is compacted only when there is a safe structural boundary
• opaque single-message prompts are forwarded unchanged
• hosted raw provider-response caching is off by default; receipts use hashes, token counts, costs, timestamps, and quality labels

To opt into exact hosted response replay for a repo key:

npx -y costlayers@latest gateway cache status
npx -y costlayers@latest gateway cache enable --yes
npx -y costlayers@latest gateway cache disable

Enable this only for workflows where storing provider response bodies is acceptable. Disabling purges hosted cache rows for that repo key. Without this opt-in, CostLayers can still shorten safe API payloads, but repeated upstream calls cannot be skipped by hosted response replay.

The repository also includes docs/full-potential.md with the public runbook and claim boundaries.

Output:

• .agentspend/full-potential-plan.md
• .agentspend/full-potential-plan.json
• .agentspend/prompt-delta.md
• .agentspend/prompt-delta.json
• .agentspend/tool-cache-index.md
• .agentspend/tool-cache-index.json
• .agentspend/workflow-compression.md
• .agentspend/workflow-compression.json
• .agentspend/model-routing-plan.md
• .agentspend/model-routing-plan.json
• .agentspend/memory-bridge.md
• .agentspend/memory-bridge.json
• .agentspend/memory-routing-summary.md
• .agentspend/memory-routing-summary.json
• .agentspend/memory-verification.md after costlayers memory --verify
• .agentspend/memory-verification.json after costlayers memory --verify
• .agentspend/semantic-slices.md
• .agentspend/semantic-slices.json
• .agentspend/ai-spend-audit.md
• .agentspend/ai-spend-audit.json
• .agentspend/replay-summary.md
• .agentspend/replay-ledger.jsonl
• .agentspend/workflow-runs/ after costlayers workflow
• .agentspend/repo-pack.md
• .agentspend/savings-report.md
• .agentspend/savings-report.json
• .agentspend/agent-instructions.md
• .agentspend/AGENTS_SNIPPET.md when AGENTS.md already exists
• .agentspend/config.json
• .agentspend/local-cache.json
• .agentspend/proof-bundle.md after costlayers proof
• <out>/bench-suite-report.md after costlayers bench-suite --out <out>
• <out>/bench-suite-report.json after costlayers bench-suite --out <out>
• AGENTS.md when the repo does not already have one

Then tell your coding agent, or let AGENTS.md do it:

Before reading the repo broadly, read .agentspend/full-potential-plan.md, .agentspend/prompt-delta.md, .agentspend/memory-bridge.md, .agentspend/repo-pack.md, and .agentspend/agent-instructions.md.

Local Code-Memory Backends

CostLayers can use local graph tools instead of competing with them. If codebase-memory-mcp or codegraph is installed, costlayers memory writes a bridge that tells the agent to use that local backend for structural questions before opening source files. If neither is installed, CostLayers falls back to its built-in semantic slices.

npx -y costlayers@latest memory
npx -y costlayers@latest memory --query "where is login handled?"
npx -y costlayers@latest memory query "trace the CLI entrypoint"
npx -y costlayers@latest memory --doctor
npx -y costlayers@latest memory --install-help
npx -y costlayers@latest memory --verify

The bridge does not bundle or copy third-party engines. It records local availability, query examples, a receipt hash, and the evidence boundary: code-memory savings are context-routing estimates; API invoice savings still require API-mode receipts.

Routing preference is explicit: use codebase-memory-mcp when available, then CodeGraph when available, then CostLayers semantic slices. The bridge is a read-first instruction for structural lookup; it is not permission to skip source review before edits or final judgment.

Active queries keep the same selection preference, but query both graph backends when their local CLIs are present. memory --query records skipped graph backends when absent, merges and dedupes backend outputs by hash, selects codebase-memory-mcp before CodeGraph when both return results, then falls back to semantic slices. It writes deterministic hash-only receipts under .agentspend/memory-queries/ with query hashes, repo-state hashes, backend attribution, stdout byte counts, output token estimates, output hashes, fresh/stale status when detectable, and the selected route. Receipts do not store source code, prompt text, raw graph output, file paths, symbols, or invoice savings claims. By default graph backend output is hashed only; pass --show-results when you explicitly want the local backend output printed to your terminal.

memory also writes .agentspend/memory-routing-summary.md and JSON with source-free route-token counters, graph verification counters, latest-query backend attribution, and output hash digests. These summaries do not store source paths, symbols, prompts, raw graph output, or graph result text.

--verify runs small local graph-backend checks when a supported backend is installed and writes only statuses, byte counts, token estimates, and hashes. It does not store raw graph output. Add --index only when you explicitly want CostLayers to ask the local backend to index the repo first.

What It Saves

The first public version reduces waste by making agents start from a compact repo map instead of repeatedly rediscovering the same project structure.

The report estimates:

• baseline broad-read tokens
• CostLayers context-pack tokens
• tokens avoided per repeated task
• estimated cost avoided per 100 repeated tasks
• projected weekly and monthly savings at the chosen runs/week assumption
• before/after token reduction for the first scan

No private internals are included in this package.

Closed Engine

The npm package is a controller for the CostLayers optimization layer. The stronger reduction engine and cost gateway run separately and are not shipped in the public package.

Privacy Default

The CLI scans source locally. A plain audit/scan stays local unless you pass --email, already have a hosted connection, or pass --allow-telemetry. When connected, CostLayers sends savings reports, artifact hashes, and usage metadata so the dashboard can show found waste and metered savings. It does not send the repo-pack preview by default. ChatGPT-login Codex mode does not route model calls through CostLayers. API invoice mode routes requests through the hosted optimization layer only when you pass --api.

Useful privacy commands:

npx -y costlayers@latest privacy
npx -y costlayers@latest privacy delete-local
npx -y costlayers@latest privacy delete-hosted --yes

The Codex profile also installs a small SessionStart reminder hook that tells Codex to read .agentspend/repo-pack.md and .agentspend/semantic-slices.md before broad repo exploration.