toil is the token-efficient alternative to MCP: the same commands as a CLI, each
returning one compact envelope, with this skill read a file at a time rather than
every tool schema up front. Keep it lean: --select the fields you need, and
toil wait rather than polling.
If toil version doesn’t print an envelope, toil isn’t installed yet: install.md,
beside this file, says how.
Every call
- Output. Every command prints one JSON envelope on stdout:
{ ok, data, error, meta }. Checkok; on failure,error.codesays what kind of failure it was anderror.fixwhat to do about it.meta.warningslists what’s worth knowing that isn’t a failure, andmeta.page.nextCursorthe next page, when there is one. - Two front doors, one command.
toil <area> <command>on the command line, or the MCP tool named after its path (db_query) fromtoil mcp --areas <area>, with identical inputs and output. - Writes. Reads are always allowed. A command that changes data needs
writes: trueon the connection, set by a person, and--allow-writeon the call (allowWrite: trueover MCP). Only make a write the user asked for. Four writes differ, each listed incore.mdunder Writes. - Connections. Environment variables always win over
~/.toil/config.json.--connection <name>picks one when an area has several;toil connections listnames them, never a secret. Setting one up is for a person: a baretoilin a terminal opens a menu for them. - Files a command reads or writes stay inside the workspace (
--workspace <dir>, else the working directory). - Feedback to Imagile (
toil feedback) only when the user asks, scrubbed of company data, shown to them in full with its disclaimer, and sent with--consentonly after their yes to that exact report:core.md, Feedback. - Less output.
--select <expression>keeps only the fields you name, andtoil wait --until <expression> -- <read>repeats a read until it’s true, instead of polling yourself. For any search or listing that may return more than a page, add--summary-file <file>(summaryFile): the full result goes to the file and you get a sample with stats;--output-format toonmakes tables smaller still.
Where to look
Open only the file the task needs; each sits beside this one.
| File | When |
|---|---|
core.md | --select, big results (--summary-file, --output-format toon), toil wait, paging and progress, errors, writes and their exceptions, global flags, files, configuration, the raw api passthrough, dossiers, the audit log, calling toil from a program (@imagile-dev/toil/api), sending feedback, certificates and proxies |
<area>.md | One per area, named after it: jira.md for toil jira …. Its frontmatter says what the area covers; the file gives the oldest version it supports, its credential, its configuration keys and every command |
dossiers.md | What a dossier is: one body of work mapped to your connections, its file, and how to build and share one |
db.md | Databases: toil db … on every engine |
util.md | Local utilities with no connection or network: toil util … |
skills.md | Skills marketplaces, and keeping this skill installed |
mcp.md | Running toil as an MCP server and registering it with an agent |
install.md | Installing toil, and this skill |
toil --help lists the areas this install has.
Every page
- Using toil
What every toil command shares, in detail - the envelope and errors, the contract version, --select, big results (--summary-file and --output-format toon), toil wait, paging and progress, writes and their exceptions, global flags, files and the workspace, configuration, the raw API passthrough, dossiers, the audit log, using toil from a program (@imagile-dev/toil/api), sending feedback, certificates and proxies
- Databases
Schemas, tables, describe, row previews, read-only queries with paging, and gated writes on databases (SQLite, PostgreSQL, MySQL/MariaDB, SQL Server, Oracle)
- What is a dossier?
One body of work, its repositories, tracker, pipelines and environments, mapped to the connections that reach them. Why dossiers exist, where they live, one field by field, and how to create, check, use and share one
- Installing toil
Installing toil from npm or from a clone with no npm install, the toil alias for a clone, and installing this skill for Codex, GitHub Copilot or Claude Code
- toil as an MCP server
Running toil as an MCP server over stdio, the tools and resources it serves, and registering it with Claude Code, Codex, VS Code and other clients
- Skills marketplaces
Agent skills from git-hosted marketplaces, installed into the folders Codex, GitHub Copilot and Claude Code read, and switched on and off
- Local utilities
Local utilities with no connection or network, decoding a JWT, inventorying dependencies from manifests and lockfiles, checked encoding and hashing, decoding certificates and checking a chain, summarising test, SARIF and coverage reports, triaging a large log, scanning for secrets before a commit or post, sizing files and folders before reading them, time zone, duration, business-day and cron arithmetic, comparing versions and ranges for npm, NuGet and Maven, converting Markdown to and from Jira and Confluence formats, reading OpenAPI documents, drawing C4 architecture diagrams from a JSON model, mapping Jira, Azure DevOps and GitHub work items to Open Work Items, and finding likely duplicates among them
- The welcome menu
- Toil UI
Toil UI: a local web app to see and reason about work across Jira, Azure DevOps and GitHub, on toil. Alpha, local only.
- Toil UI themes
Toil UI's five themes, themed wording and the agent's voice, the two checkboxes that set how far a theme goes, and how the agent's prompt is composed.