TIMEBOMB documentation

Overview

Most tests run against "now". Many real bugs don't appear until later: a trial ends, a month rolls over, a job runs late, or a user returns with old data in their browser. TIMEBOMB gives your agent a structured way to look for those bugs in your own code and prove them with repeatable tests.

The agent maps where your app reads and stores time, works out what the correct behavior should be, then writes small tests that control the clock instead of waiting for real time to pass.

Kinds of failures it looks for

These are examples of what the agent checks for. They are not findings about your app until the agent shows them with evidence.

• A trial that starts on January 31 and runs into March instead of ending at the end of February.
• Access that is still granted at the exact instant it should expire.
• A late "activated" webhook that overwrites a newer cancellation.
• A refresh job that fails, while the dashboard still says "updated".
• A daily reminder that shifts by an hour after a daylight-saving change.
• A returning user whose old local storage breaks the app after an update.

JavaScript and TypeScript projects get the most attention. The agent may adapt the approach to other languages when its tools can inspect and test them reliably.

Requirements

• A coding agent with access to your repository. It needs to read files to build the inventory of time-related code.
• Permission to run commands, for tests. Without it, the agent falls back to reading source code and proposing tests. Every result it could not run is labeled as unexecuted.
• Node.js, for the bundled demo. We ran it on Node.js 22.23.2. The demo only uses the built-in node:assert module, so there is nothing to install.
• Playwright, only for browser-clock tests. If your app's time behavior lives entirely in backend code, you don't need it.

Installation

Buyers receive timebomb-v1.0.1.zip from the marketplace listing where they bought it. Unzipping it gives you one folder:

timebomb/
  SKILL.md
  LICENSE.txt
  references/scenarios.md
  examples/temporal-demo.mjs

SKILL.md holds the instructions the agent follows. references/scenarios.md is a menu of time scenarios to choose from. examples/temporal-demo.mjs is a small self-checking demo.

unzip timebomb-v1.0.1.zip

Unzipping the archive and getting the folder above was verified. Below is what happened when we pointed real agents at it. We checked three separate things, because "it loaded" is not the same as "it followed every rule":

• Install and discovery: the agent found and loaded the skill.
• Demo run: on the synthetic subscription demo, it reproduced the seeded failures, fixed them, and the tests passed when we reran them ourselves.
• Full report compliance: its final answer contained the required report (an evidence class on every item, an execution summary with a count per class, a scenario ledger with Result and Evidence columns, and remaining exposure).

Each row is one run on one Linux machine with Node.js v22.23.2. The Claude Code sessions ran with the tester's usual plugins and hooks loaded. Version 1.0.1 made the report mandatory in the skill's completion rules. That improved Codex's answer, but no agent has yet produced a fully compliant report from the installed skill folder without being asked.

mkdir -p ~/.claude/skills && cp -R timebomb ~/.claude/skills/timebomb

mkdir -p ~/.codex/skills && cp -R timebomb ~/.codex/skills/timebomb

Make sure SKILL.md ends up directly inside the timebomb folder, not one level deeper. Start a new session after copying. Claude Code's per-project location, .claude/skills/timebomb/, wasn't tested.

Quick start

Start with an audit. It doesn't change your source code, so it's a safe first run. Paste this into your agent from your project's root, and adjust the path if you put the folder somewhere else.

Read timebomb/SKILL.md and follow it to audit this repository for time-related bugs. Audit only: do not change any source files. Do not change the system clock and do not contact live services. Focus on the highest-impact time-dependent features you find, run isolated tests where you can, and give me the report in the format the skill describes.

You'll get better results when you name the feature and the rules you expect. For example:

Read timebomb/SKILL.md and follow it to audit our trial and subscription code. Rules: a trial lasts one calendar month in UTC, ends on the last day of the month when the next month is shorter, and access is allowed only strictly before the expiry time. Check month ends (including leap years), the exact expiry instant, and what happens if a late "activated" webhook arrives after a cancellation. Audit only, no source changes.

Audit and fix workflows

You choose the mode in your request. If you don't say, the agent should treat it as an audit and leave your source code alone.

Audit only

1. Inventory: find where time is read, stored, compared, and shown.
2. Expectations: base "correct" on your requirements, docs, or existing tests. When the rule is unclear, it is reported as a policy gap, not a bug.
3. Scenarios: pick a focused set, usually testing just before, exactly at, and just after each boundary, plus a normal control case.
4. Isolated tests: use injected clocks, fake timers, and throwaway fixtures.
5. Report: every result is tied to evidence and labeled with how sure it is.

Read timebomb/SKILL.md and follow it in audit-only mode for [feature or folder]. Do not modify production source. You may add temporary tests in a scratch location and remove them afterwards. Report each scenario as CONFIRMED, SUPPORTED, POLICY GAP, BLOCKED, PASS, or NOT APPLICABLE.

Authorized fix

1. Show the original failure with a test, when that's possible.
2. Keep that test as a regression test.
3. Apply the smallest fix consistent with the agreed rule.
4. Rerun the regression test and nearby tests.
5. Clean up fake timers, environment changes, and fixtures.

Read timebomb/SKILL.md and follow it for [feature]. You are authorized to fix confirmed bugs. For each one: show the failing test first, keep it as a regression test, make the smallest fix, then rerun it and the related tests. Do not weaken or delete assertions to make tests pass. Do not change the system clock or touch live data. List every file you changed.

Clocks

An app usually has several clocks, and they don't move together. Faking the time in a browser does not change the time your server, database, or billing provider sees. The agent records which clocks each test controls, so you can tell what a passing test actually covers.

The report

The agent finishes with a report in these sections:

1. Scope: the app, components, runtime, mode, and source revision.
2. Execution summary: how many scenarios were selected and run, and how many landed in each evidence class.
3. Temporal inventory: each feature, its clock, its stored state, and how it was controlled.
4. Findings: each issue with its evidence, severity, timeline, reproduction command, and fix status.
5. Scenario ledger: one row per scenario with its result.
6. Changes: source edits and new tests, if any.
7. Remaining exposure: what was not or could not be tested.
8. Next action: the most useful next step.

Evidence classes

Severity is separate from confidence. A SUPPORTED item can be high severity, and a CONFIRMED one can be minor. Scenario counts are also kept separate from assertion counts, so ten assertions inside one scenario still count as one scenario.

Bundled demo

The package includes a small demo that shows the method on three deliberately broken functions: an expiry check, a month-end renewal, and handling of late or duplicate events. It checks that each broken version fails and each corrected version passes.

It has no dependencies, uses no network, and never changes your system clock. Run it from the folder that contains timebomb:

cd timebomb && node examples/temporal-demo.mjs

Success looks like three PASS lines, a final 3/3 demo cases line, and exit status 0. The demo's results are about its own fixtures, not about your app.

Verified results

Bundled demo

Run on Node.js v22.23.2 on Linux. Exit status 0.

PASS: access expires at the exact boundary
PASS: January 31 clamps to February 28
PASS: late and duplicate events preserve newer state
3/3 demo cases: broken fixtures rejected; corrected fixtures passed.

Synthetic subscription demonstration

We ran the full audit-and-fix workflow in Claude Code against a tiny trial service with two defects we planted on purpose and named in the request. Tests used Node.js v22.23.2, the built-in node:test runner, and an injected clock.

Scenarios covered: January 30 and 31 into February in 2028 (leap year) and 2027 (non-leap year); access 1 ms before, exactly at, and 1 ms after expiry; a mid-trial control; a March 15 to April 15 control; and a January 31 start checked on March 1.

Seeded defect 1: the month was advanced with an unclamped setUTCMonth(+1), so a trial starting 2027-01-31 expired on 2027-03-03 instead of 2027-02-28.

Seeded defect 2: the access check used <=, which allowed access at the exact expiry instant.

Follow-up runs in other setups

We gave the same request, naming only "the timebomb skill", to fresh sessions with the package installed in each agent's skill folder. Each ran against a fresh copy of the seeded service. Each time, we reran the tests ourselves afterwards, outside the agent.

• Codex CLI 0.153.2, v1.0.0: loaded the skill and reproduced the same 6 failures. It changed only src/subscription.js, and our rerun passed 10/10. Its final answer was a short summary, with no report.
• Codex CLI 0.153.2, v1.0.1: the same 6 failures, and only src/subscription.js changed. Our rerun passed 10/10, with the test file unchanged. This time it ended with the structured report, but with no NOT APPLICABLE count, and it didn't say the defects were seeded.
• Claude Code 2.1.304, v1.0.1: loaded the skill through its Skill tool, reproduced the same 6 failures, and fixed both defects. It added 3 tests of its own, so its own run had 13 tests and our rerun passed 13/13. The original 10 tests also passed against its fix. Its report said the defects were seeded, but the scenario ledger lacked the required Result and Evidence columns.

Inside Codex's sandbox, npm test sometimes showed only a file-level result. Our reruns outside the sandbox showed each case.

Permissions and safety

TIMEBOMB is written to keep testing away from anything real. The agent is told to leave these alone:

• Your machine's clock. Time is controlled inside tests, never by resetting the system time.
• Real data. No editing of genuine customer records.
• Real-world side effects. No live payments, refunds, emails, or notifications.
• Production access. Real logins and tokens aren't expired, and production jobs aren't switched off.
• Outside services. No calls that would change anything in a live external system.
• Secrets. Nothing like keys, cookies, or saved login state gets committed.

Instead it uses test accounts, throwaway fixtures, sandboxes, and local stand-ins.

Limitations

• No continuous monitoring. It's a one-time audit you run when you ask for it.
• No guaranteed discovery. The agent can miss bugs, and the results depend on what it can inspect and run.
• Passing scenarios are not proof. They show the tested cases worked under stated conditions, nothing more.
• Scheduler tests have limits. Fake-timer tests show a job's timing logic is right, not that your deployment actually invokes the job.
• Tested in two agents, one run each. Claude Code 2.1.304 and Codex CLI 0.153.2. Other agents, other versions, and Claude Code's per-project skill folder haven't been tried.
• Report compliance is partial from installed skill folders. Both agents loaded the skill and fixed the demo defects. Neither produced every required report element without being asked: Claude Code left out the ledger's Result and Evidence columns, and Codex left out the NOT APPLICABLE count. If you need the exact format, ask for "the report in the format the skill describes". That wording hasn't been tested from the skill folder.
• JavaScript and TypeScript come first. Other languages get a best-effort adaptation.

Troubleshooting

node: command not found

Node.js isn't installed or isn't on your PATH. Install a current Node.js release (we ran the demo on 22.23.2; other versions were not tested), then run the demo again.

Cannot find module '.../test' when running node --test test/

We hit this ourselves on Node 22: it doesn't accept a bare directory there. Run node --test with no directory so it finds test files on its own, or pass file paths or a glob instead.

node --test

In Codex, npm test shows only one file-level result

We saw this inside Codex CLI's workspace-write sandbox: node --test reported one failing file instead of each test case. Running the test file directly with node test/your.test.js showed the individual results. Outside the sandbox, npm test reported each case normally. We haven't established the cause.

Codex doesn't list the skill

Check that the file is at ~/.codex/skills/timebomb/SKILL.md and not one folder deeper (for example ~/.codex/skills/timebomb/timebomb/), then start a new session.

Playwright isn't installed

Browser-clock scenarios are reported as BLOCKED. Backend tests still run. Install Playwright in the project if you want the browser scenarios covered.

The agent can't run commands

It falls back to reading the source. Anything it finds that way is reported as SUPPORTED, not CONFIRMED, with proposed tests you can run yourself.

Tests pass, but the bug still happens in production

Check which clock the test controlled. A test that fakes the backend clock doesn't cover the browser, database, scheduler, or provider. See Clocks.

FAQ

Is TIMEBOMB an MCP server?

No. It is an agent skill: a folder of instructions, a scenario reference, and a demo that your agent reads. There is no server to install or configure.

Does it change my system clock?

No. Tests control time through injected clocks, fake timers, the browser test clock, or fixtures. The instructions forbid changing the operating system's clock.

Does it need internet access?

The skill itself doesn't. The bundled demo uses no network. Your agent may need a connection to work, and provider sandbox tests need whatever that provider requires.

Will it edit my code?

Only if you ask for fixes. In audit-only mode it leaves production source unchanged. Your agent's own permission settings still apply either way.

Which agents does it work with?

Two have been tried, one run per setup. In both Claude Code 2.1.304 and Codex CLI 0.153.2, installing the folder in the agent's skill directory worked: the agent found the skill, reproduced and fixed the seeded demo defects, and the tests passed when we reran them. Full report compliance was partial in both. See the compatibility table for details. Other agents that can read files and run commands may work, but they are untested.

Does it guarantee finding bugs?

No. It gives the agent a careful method and requires evidence for every claim, but it can't promise to find every time-related bug.

Can I see a real run?

Yes. The demo evidence page has the captured test logs and audit report from the synthetic subscription demonstration (stack frames omitted; raw agent transcripts are kept private).