ScaleSense

Model the demand. Find the constraint. Choose the technology.

An evidence-driven system design and capacity-planning methodology for Codex that turns product demand into production-safe decisions.

ScaleSense turns demand into workload, latency, Resource Footprint, cost, failure, and evolution decisions before implementation. It recommends the simplest production-safe option for the current context, then names the evidence that should justify the next step.

Quickstart

Codex CLI: stable v0.2.0

ScaleSense is installed directly from the public umit/scalesense GitHub repository. Its .agents/plugins/marketplace.json lets Codex add the repository as a personal marketplace source, while the immutable v0.2.0 tag pins the install to the released version. Acceptance into or listing in an official Codex marketplace is optional and is not an installation prerequisite.

Add the pinned public repository, then install ScaleSense from the marketplace it declares:

codex plugin marketplace add umit/scalesense --ref v0.2.0
codex plugin add scalesense@scalesense

Codex fetches the marketplace and plugin from GitHub. Users do not need a Git clone, ZIP download, manual file copy, custom installer, hosted package registry, or ScaleSense backend.

Verify the installed plugin:

codex plugin list --json

Then start a new Codex session and ask in normal language:

Review this design before we implement it. Estimate the peak workload,
resource needs, failure behavior, and evidence required for approval.

Or select a ScaleSense workflow explicitly:

$scalesense estimate Size this workload and identify the benchmark inputs still missing.

Skills load into new chats and sessions, not retroactively into one that is already open.

Codex app

After adding the same marketplace source, restart the Codex app. Open Plugins, select the ScaleSense marketplace, install or enable ScaleSense, and start a new Codex chat.

Local development

This contributor workflow is separate from the public installation path above. From an existing repository checkout:

codex plugin marketplace add .
codex plugin add scalesense@scalesense

After local changes, rerun codex plugin add scalesense@scalesense and start a new session.

Use ScaleSense

ScaleSense can activate when a normal architecture, capacity, latency, cost, or complexity question matches its scope. $scalesense is the explicit Codex skill mention syntax, not a shell command. Use it when you want to select a workflow deliberately:

Mode	Use it to
$scalesense review	Review an existing proposal or change
$scalesense design	Design a system from product and operating constraints
$scalesense estimate	Estimate demand, latency, resources, connections, and cost drivers
$scalesense challenge	Test whether a technology or boundary is justified now

Implicit activation is intentionally narrow: technology definitions, tutorials, and implementation of an already approved choice should not invoke ScaleSense.

Decision Loop

ScaleSense is one instruction-only Codex skill. It follows this chain:

product demand
  -> average, peak, burst, concurrency, and data growth
  -> latency and availability budgets
  -> CPU, memory, storage, IOPS, bandwidth, replicas, connections, and cost
  -> technology decision
  -> benchmark, production signal, and evolution trigger

1. Define the product need.
2. Estimate traffic, concurrency, and data growth.
3. Set latency and availability budgets.
4. Build a Resource Footprint across every relevant dimension.
5. Model operating cost and failure behavior.
6. Choose the simplest production-safe design in the existing context.
7. Define the evidence that makes it stop being enough.

The result is a verdict such as adopt, defer, reject, or measure first, backed by known facts, labeled assumptions, confidence, visible units, and measurable validation. When a missing input can change the verdict, ScaleSense asks for it. Otherwise it proceeds with explicit assumptions. Complexity is recommended when replay, throughput, isolation, ownership, compliance, or another concrete constraint earns it.

Exact CPU, RAM, instance, partition, or replica allocations do not follow from registered-user counts or QPS alone. They require profiling, a representative benchmark, or production measurements.

Evidence acquisition

ScaleSense uses user-supplied context first. Implicit activation never queries connected company telemetry, billing, dashboards, repositories, or production systems merely because read-only access exists. It may collect connected evidence only when the user explicitly requests that collection and host/workspace policy permits it. Otherwise it returns a measurement contract: the metric or query, representative workload, pass/fail threshold, and condition for rerunning the decision. The plugin does not bundle a telemetry connector or claim measurements it cannot see.

Decision Snapshots

Interactive API capacity

An endpoint must sustain 900 peak requests/second inside a 250 ms p95 budget. If production-shaped profiling measures 12 ms of CPU per request, peak CPU demand is 900 x 0.012 = 10.8 core-seconds/second. A 65% utilization target raises that to 16.6 cores before N+1 and rollout headroom. ScaleSense combines this with measured working set, concurrency, connection budgets, dependency latency, and failure tolerance before recommending replica count or shape.

Durable user uploads

At 40,000 uploads/day and 6 MB each, new data is 40,000 x 6 MB = 240 GB/day, or about 7.2 TB per 30-day month before versions and redundancy. Retention, object count, peak ingress, download egress, durability, restore behavior, and lifecycle policy determine the storage design and cost. Local disk, shared storage, and object storage are choices made after those requirements, not defaults inferred from user count.

Deadline-bound processing

Processing 12 million records at a measured 3 ms of CPU each requires 12,000,000 x 0.003 = 36,000 CPU-seconds, or 10 core-hours. A 30-minute deadline therefore needs at least 20 continuously busy cores before overhead and failure headroom. Measured I/O, memory, batching, retry amplification, and downstream limits then determine safe concurrency, worker count, backpressure, and the benchmark that approves production sizing.

For complete calculations and responses, see the example conversations. The separate Black Friday capacity review uses Shopify's published BFCM scale figures and engineering practices to show how observed peaks become a capacity plan and go/no-go record without inventing CPU, memory, or replica allocations. The skill's detailed methods live in napkin-math.md, latency-numbers.md, database-decisions.md, and production-reality.md.

What's Inside

• One scalesense skill with four focused mode workflows.
• Capacity, latency, database, and production knowledge loaded only when relevant.
• Codex install metadata and a square icon.
• Repository tests and eval tooling used for development and release review.

The plugin bundles no MCP server, connector, app, hook, executable, or external service.

Update And Remove

The command shapes in this README were checked with Codex CLI 0.146.0 on macOS. A marketplace pinned to v0.2.0 remains pinned when refreshed.

Refresh the configured marketplace and reinstall its plugin snapshot:

codex plugin marketplace upgrade scalesense
codex plugin add scalesense@scalesense

To move to another available tag, remove the current plugin and marketplace, then add the repository with that tag and install it again. Start a new Codex chat or CLI session after every install or update.

Remove ScaleSense and its marketplace source:

codex plugin remove scalesense@scalesense
codex plugin marketplace remove scalesense

The Codex app provides the equivalent uninstall action in plugin details when workspace policy permits it.

Trust And Limitations

ScaleSense v0.2.0 is skills-only and instruction-only. It has no external endpoint, account, authentication flow, credential store, telemetry, analytics, or background process. It creates no independent data plane and does not bypass Codex sandbox or approval policy.

The plugin itself neither transmits nor retains prompts, files, or outputs. Codex and employer or workspace controls still govern supplied context, tool access, model processing, logs, retention, and output. See SECURITY.md, PRIVACY.md, and TERMS.md for the full boundary.

• Estimates are models built from supplied facts and labeled assumptions, not production measurements.
• ScaleSense does not replace telemetry, profiling, load tests, security or compliance review, or accountable engineering ownership.
• Output quality depends on the completeness and accuracy of the supplied context.
• Hardware, service, and latency reference numbers age and do not become guarantees in another environment.
• Public v0.2.0 behavior and evaluations are English.
• Initial command-shape verification covers Codex CLI 0.146.0 on macOS. Other Codex clients, operating systems, and multilingual behavior are not yet claimed as verified.

Codex packaging uses .codex-plugin/plugin.json. The repository also carries plugins/scalesense/plugin.json for the Agent Plugins v1 Working Draft. That manifest is a packaging boundary, not a supported non-Codex surface or a claim of universal client compatibility.

Evaluation

The repository includes 28 versioned behavior cases covering direct and implicit decisions, negative activation, incomplete requirements, pressure toward premature complexity, and justified complexity. Live model evaluations run in fresh, read-only Codex sessions and require authentication and model usage. They are a manual release gate, not deterministic CI.

Development tooling requires Node.js 22 or newer:

npm test
npm run check
npm run check:release
npm run eval -- --model gpt-5.6-sol

Official Codex plugin and Agent Skill validators remain maintainer merge gates for manifest or skill changes. Eval transcripts are local, ignored artifacts that may contain prompts and responses; review failures manually and never commit raw .eval-results/ content.

Contributing And Support

Read CONTRIBUTING.md before proposing changes and CODE_OF_CONDUCT.md for participation expectations. Open non-sensitive support requests at GitHub Issues. Report security issues privately as described in SECURITY.md.

Acknowledgements

ScaleSense is inspired by Superpowers, especially its workflow-first and progressive-disclosure approach to agent skills. ScaleSense is an independent project focused on system-design math, capacity planning, and need-driven architecture decisions.

ScaleSense's first-principles estimation method is inspired by sirupsen/napkin-math. Google's SRE Latency Numbers Everyone Should Know is a classic historical orientation sheet. Numbers from either source are anchors, not SLOs or allocations: source date, hardware, benchmark environment, and workload all matter.

License

ScaleSense is licensed under the MIT License.