by Imagile

How toil is built

Principles first. Rules follow.

Every rule in toil is a consequence of one of these. When a new case comes up, we reason from the principle rather than adding a one-off rule, so the tool stays predictable as it grows.

  1. 01

    Adoptable inside a locked-down enterprise

    Installs from npm, runs on Node, and needs nothing else: no executable, no native library, no other CLI, no browser login.

    For youThe only things your security team approves are Node and one npm package.

  2. 02

    Safe by default when an agent is driving

    Reads are free. Anything that writes — to a database, a ticket, a pull request — needs your standing opt-in in config and an explicit flag on the call.

    For youAn agent cannot discover a write tool you have not turned on.

  3. 03

    One command, one source; you compose

    No command quietly fans out to services you did not ask for. Each source is its own command, and they chain through stdin.

    For youYou always know which system a result came from, and you choose which ones to ask.

  4. 04

    Honest about what is known

    Every result says where it came from and how precise it is. Every integration says how far it has been verified: unit, live or stable.

    For youA green check means something was actually run against a real system.

  5. 05

    The environment wins

    Environment variables override every config file, so pipelines and agents configure toil without editing anything on disk.

    For youThe same install works on your laptop and in CI.

  6. 06

    Stands on its own

    toil is not a wrapper around another tool and does not depend on one being installed.

    For youNothing else to install, upgrade, or get approved.

  7. 07

    Never break you silently

    Config on disk, flags, the JSON envelope and precedence are contracts. Changing one is a declared, documented breaking release.

    For youScripts and pipelines you write against toil keep working.

  8. 08

    Windows, macOS and Linux, equally

    No shell assumptions, no platform-specific paths. A feature that works on one and not the others is not done.

    For youYour instructions are the same whichever machine you are on.

  9. 09

    Talks only to what you point it at

    No telemetry, no update checks, no call home. Network traffic goes to hosts in your config, or to a public API a command names in its own name.

    For youYour firewall logs show exactly what you would expect.

The full engineering rules derived from these live in the repository's CLAUDE.md.