Getting started

Set up one Node.js or TypeScript operation, then compare its cost per successful operation across two revisions. You supply the test cases, success checks and provider rates.

MarginCI is proprietary software, available by invitation. Request access with a brief description of your operation and paid APIs. Your invitation includes evaluation permission and terms.

Set up with your coding agent

Give your agent the setup prompt, your authorized package, its independently supplied expected checksum and your repository. The agent inspects compatibility and prepares an operation for your review. You approve paid comparisons and CI separately.

Prefer to do it yourself? Continue with manual installation below.

Install the private alpha

Invited testers receive marginci-0.3.0-alpha.16.tgz, SHA256SUMS and release notes directly. No source-repository access or registry account is needed.

1. Check prerequisites

Use Node.js 24.21.0, Git and a supported npm configuration: 11.6.2 on the hosted runners or 11.7.0 on the documented local macOS configuration. Check node --version, npm --version and the runtime and repository requirements. Installing Node does not necessarily supply the required npm version. For pnpm applications, provision the exact application pin separately.

2. Verify and install the package

In the delivery directory, paste the independently supplied 64-character SHA-256 into EXPECTED_SHA256. Run the installation block as a whole: either failed checksum check stops installation.

Ubuntu: replace the two macOS shasum commands in the installation block with:

printf '%s  %s\n' "$EXPECTED_SHA256" "$ARCHIVE" | sha256sum -c -
sha256sum -c SHA256SUMS

Install into a new tooling directory outside your application repository. MarginCI rejects an application-local file: dependency. If the versioned destination already exists, inspect it before retrying; these commands will not replace it.

(
  set -eu
  EXPECTED_SHA256='PASTE_SEPARATELY_SUPPLIED_SHA256_HERE'
  ARCHIVE='marginci-0.3.0-alpha.16.tgz'
  printf '%s  %s\n' "$EXPECTED_SHA256" "$ARCHIVE" | shasum -a 256 -c -
  shasum -a 256 -c SHA256SUMS
  ALPHA_TOOLS="$HOME/.local/share/marginci/0.3.0-alpha.16"
  mkdir -p "$HOME/.local/share/marginci"
  mkdir "$ALPHA_TOOLS"
  printf '{"private":true}\n' > "$ALPHA_TOOLS/package.json"
  npm install --prefix "$ALPHA_TOOLS" --save-dev --save-exact --ignore-scripts --no-audit --no-fund "$PWD/$ARCHIVE"
)

3. Add the CLI to your shell

Add this line once to ~/.zshrc on macOS or ~/.bashrc on Ubuntu to make the separately installed CLI available in new terminals:

export PATH="$HOME/.local/share/marginci/0.3.0-alpha.16/node_modules/.bin:$PATH"

4. Initialize your repository

Open a new terminal, confirm node --version is v24.21.0, and run from your application Git repository:

cd "/path/to/your/application"
marginci init

Use this separately installed CLI for both npm and pnpm applications.

init inspects the repository, creates marginci.yml and adds .marginci/ and node_modules/ ignore rules. It preserves existing configuration on repeat runs. It does not import application code, install dependencies or call providers. Fix any reported lockfile, package-manager or path conflict before retrying.

Define one operation

An operation must run in one Node.js process and await all paid work before exiting. Create marginci/research.cjs, replacing the import and success check with your application’s own:

async function main() {
  const { research } = await import('../src/research.js');
  const input = JSON.parse(process.env.MARGINCI_CASE_JSON);
  const result = await research(input);
  if (!result || !Array.isArray(result.sources) || result.sources.length === 0) {
    process.exitCode = 1;
  }
}
main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

The wrapper reads the current test case, calls your application and exits nonzero on failure. It needs no accounting code or MarginCI imports. A nonempty source list is an example, not a quality guarantee: choose a success check that verifies the result your users need.

Complete marginci.yml using the configuration reference:

Configure your application to use the same endpoint and model. MarginCI does not change your SDK settings or look up prices. Replace illustrative rates with your own. Export credentials through your normal environment: MarginCI neither loads .env files nor copies ignored files into revision snapshots. Never put credentials in configuration or test inputs.

Commit setup and run a comparison

Follow Repository setup to commit the wrapper, configuration and shared test inputs. Check setup first:

marginci doctor research --against HEAD

doctor checks both revisions without installing dependencies or making paid calls. It validates repository and configuration prerequisites; it cannot check every application import or fields constructed by application code. For Gemini, review the admitted request fields.

The next command makes paid API calls. Review the cases, success checks, rates and request/spend limits first. Supply credentials through your approved environment.

marginci test research --against HEAD --json

test installs each revision’s locked dependencies and checks supported request shapes before dispatch. Comparing the same commit can still produce different costs when provider responses vary.

A completed test returns PASS (0), FAIL (1), INCONCLUSIVE (2) or ERROR (3). A successful init or doctor is not an economic PASS. Use the report’s reasons and result guide to resolve failures.

Land the shared setup before comparing later application changes. Then use marginci test research --against <base-commit> with a baseline that contains it. For CI, continue to GitHub Actions.

Reports and application logs remain under .marginci/runs/ until you delete them. Keep that directory private; see Security and data handling before sharing files. For setup problems, email support@marginci.com with the error and runtime versions, without credentials or unreviewed logs.

Resolve setup problems

Existing configuration: init preserves marginci.yml and .gitignore. If .marginci/ is not effectively ignored, follow the corrective command from your repository root:

printf '\n.marginci/\n' >> .gitignore

Review negated ignore rules, rerun init and doctor, and commit the reviewed change. doctor refuses tracked or unignored retained-run files.

Incomplete lockfile: follow lockfile requirements to review and regenerate missing registry metadata. MarginCI does not rewrite your dependency graph.

Imports that fail at runtime: see committed JavaScript guidance. A successful doctor check does not prove that every application import can execute.