scalesense

KO | EN

gitlite — search

#python #hacktoberfest #react #ai #llm #machine-learning #linux #docker #nodejs #java #windows #vue #security #open-source

(★ 1)

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

scalesense Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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`](https://github.com/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:

```bash
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:

```bash
codex plugin list --json
```

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

```text
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:

```text
$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:

```bash
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:

```text
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](plugins/scalesense/examples/conversations.md). The
separate
[Black Friday capacity review](plugins/scalesense/examples/black-friday-capacity-review.md)
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](plugins/scalesense/skills/scalesense/references/napkin-math.md),
[latency-numbers.md](plugins/scalesense/skills/scalesense/references/latency-numbers.md),
[database-decisions.md](plugins/scalesense/skills/scalesense/references/database-decisions.md),
and
[production-reality.md](plugins/scalesense/skills/scalesense/references/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:

```bash
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:

```bash
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](SECURITY.md), [PRIVACY.md](PRIVACY.md), and [TERMS.md](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:

```bash
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](CONTRIBUTING.md) before proposing changes and
[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for participation expectations. Open
non-sensitive support requests at
[GitHub Issues](https://github.com/umit/scalesense/issues). Report security
issues privately as described in [SECURITY.md](SECURITY.md).

## Acknowledgements

ScaleSense is inspired by [Superpowers](https://github.com/obra/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](https://github.com/sirupsen/napkin-math). Google's SRE
[Latency Numbers Everyone Should Know](https://static.googleusercontent.com/media/sre.google/en//static/pdf/rule-of-thumb-latency-numbers-a4.pdf)
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](LICENSE).

scalesense

scalesense Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

scalesense

scalesense Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README