The Tiebreaker

The Tiebreaker helps people make clearer decisions with AI-generated analysis. Provide a decision you need to make, choose an analysis framework, and receive a structured response as a pros and cons list, a comparison table, or a SWOT analysis.

It is designed for everyday and professional decisions: career moves, product choices, architecture tradeoffs, launch plans, vendor selection, relocation, and other situations where the tradeoffs are not obvious.

The project ships as:

• Web app: a React decision dashboard served by Express.
• CLI: a terminal tool for fast decision analysis.
• SDK: a small Node.js API for integrating decision analysis into other tools.

Gemini API calls run server-side or in Node.js. Browser users interact with a local API proxy, so GEMINI_API_KEY is not exposed in the client bundle.

What It Does

The Tiebreaker accepts a decision prompt such as:

Should I accept this new job offer?
Should our team move from a monolith to microservices?
Should I relocate to Amsterdam or stay in my current city?

Then it can produce:

• Pros and cons: balanced advantages and disadvantages, including short-term and long-term considerations.
• Comparison table: side-by-side evaluation of options or "do it" vs "do not do it".
• SWOT analysis: strengths, weaknesses, opportunities, and threats with practical decision checkpoints.

The output is meant to support judgment, not replace it. The assistant surfaces tradeoffs, assumptions, risks, and questions that deserve more information.

Installation

The Tiebreaker is distributed through npm and GitHub Packages:

npmjs.com:        @nayannath/the-tiebreaker
GitHub Packages: @nayan07cse/the-tiebreaker

Install globally from npm:

npm install -g @nayannath/the-tiebreaker

Set your Gemini API key:

export GEMINI_API_KEY="your-gemini-api-key"

Run the CLI:

the-tiebreaker "Should I accept the new role?" --pros-cons
the-tiebreaker "Postgres vs MongoDB for this product" --compare
the-tiebreaker "Should we launch in Europe this quarter?" --swot

Run the packaged web app:

the-tiebreaker-web

Open:

http://localhost:3000

Use a different port:

PORT=4000 the-tiebreaker-web

GitHub Packages users can install the GitHub-scoped package after authenticating npm for GitHub's registry:

npm login --scope=@nayan07cse --auth-type=legacy --registry=https://npm.pkg.github.com
npm install -g @nayan07cse/the-tiebreaker --registry=https://npm.pkg.github.com

CLI Options

the-tiebreaker "Your decision here" [options]

Options:

--pros-cons    Balanced pros and cons list. Default.
--compare      Markdown comparison table.
--swot         SWOT analysis.
--help, -h     Show CLI help.

Examples:

the-tiebreaker "Should I buy or lease a car?"
the-tiebreaker "AWS vs GCP for this project" --compare
the-tiebreaker "Should we open a second location?" --swot

SDK Usage

import { analyzeDecision } from "@nayannath/the-tiebreaker";

const result = await analyzeDecision(
  "Should we rewrite the dashboard in React?",
  "swot"
);

console.log(result);

Supported analysis types:

type AnalysisType = "pros-cons" | "comparison" | "swot";

The SDK requires GEMINI_API_KEY in the Node.js environment.

Local Development

Prerequisites:

• Node.js 20+
• npm
• Gemini API key

Install dependencies:

npm install

Create a local environment file:

cp .env.example .env

Set:

GEMINI_API_KEY="your_api_key_here"

Run the development server:

npm run dev

Open:

http://localhost:3000

Build the full package:

npm run build

Run the built web app:

npm start

Validate the workspace:

npm run lint
npm audit --audit-level=moderate
npm pack --dry-run --ignore-scripts

Environment Variables

GEMINI_API_KEY   Required for Gemini analysis calls.
PORT             Optional web server port. Defaults to 3000.
HOST             Optional web server host. Defaults to 0.0.0.0.

Do not commit .env; it is ignored by .gitignore.

Distribution

Release builds are published to both npmjs.com and GitHub Packages. Package versions are immutable in each registry, so a new release requires a version bump:

npm version patch
git push --follow-tags

Automation is handled by GitHub Actions:

• .github/workflows/ci.yml: validates pushes and pull requests.
• .github/workflows/npm-publish.yml: publishes @nayannath/the-tiebreaker to npmjs.com.
• .github/workflows/github-packages.yml: publishes @nayan07cse/the-tiebreaker to GitHub Packages.

Troubleshooting

GEMINI_API_KEY environment variable is required

Set the key before running the CLI, SDK, or web server:

export GEMINI_API_KEY="your-gemini-api-key"

Architecture

• Server (server.ts): Express API for /api/analyze, static web serving, and production runtime.
• Client (src/App.tsx): React decision dashboard with framework selection and Markdown rendering.
• Gemini service (src/services/geminiService.ts): Shared analysis function for browser proxy, CLI, and SDK usage.
• CLI (src/cli.ts): Terminal interface for direct decision analysis.
• Package server (bin/serve.js): Starts the compiled web app after global npm installation.

License

Apache-2.0