
x-tools
io.github.craft-agent/x-tools
Unofficial X tools for coding agents: read posts and profiles, save post media, never write to X.
Documentation
x-tools
Unofficial X tools for coding agents: read posts and profiles, save post media, never write to X.
[!WARNING] These tools do not use the X API. They read through FxTwitter, a third-party service, and through a reading account that calls X's web app endpoints, signed in with a browser session's cookies. X's terms forbid scraping and its automation rules can end in suspension, read-only use included. Sign in with a separate reading account whose loss you accept, never your main one. The cookies are the account: whoever holds them is signed in as it until X ends the session. Nothing here posts, replies, likes, follows or sends.
| Harness | Delivery | Pinned by |
|---|---|---|
| OpenCode V2 | native plugin (npm package, with skills) | the version in the package |
| OpenCode V1 | native plugin (npm package, no skills) | the version in the package |
| Claude Code | plugin: MCP server and skills | the release tag, as the ref |
| Codex | plugin: MCP server and skills | the release tag, as the ref |
| Grok Build | plugin: MCP server and skills | the release tag, as @ref |
| Antigravity | plugin: MCP server and skills | the release tag's tree URL |
| Hermes Agent | native plugin (Python, calls the command line) | the release commit, as the SHA |
| other MCP host | MCP server from npm | the version in the package |
The tools need Node.js 24 or later.
docs/conventions.md describes how the tools are named
and how they behave.
Install
Install from a release, never from the default branch: a release is a tag whose
commit carries the built dist/, and the default branch does not. In the
commands below, <version> is a release's version (1.2.3) and <sha> is the
commit its tag names:
gh api repos/craft-agent/x-tools/commits/v<version> --jq .sha
OpenCode
OpenCode V2 takes the package and its options in opencode.json:
{
"plugins": [{ "package": "@craftsamo/x-tools@<version>", "options": { "read_only": false } }],
"permissions": [{ "action": "x_*", "resource": "*", "effect": "ask" }]
}
OpenCode V1 takes the package as a string, or as a pair with its options:
{
"plugin": [["@craftsamo/x-tools@<version>", { "read_only": false }]],
"permission": { "x_*": "ask" }
}
OpenCode allows any action no rule names, so the plugin's request is granted
silently unless a rule says ask. Read tools never ask, so the x_* glob
is safe.
V1 registers no skills. Unpack the package and copy its skills/* folders into
~/.config/opencode/skills/:
npm pack @craftsamo/x-tools@<version>
tar -xzf craftsamo-x-tools-<version>.tgz
mkdir -p ~/.config/opencode/skills
cp -r package/skills/* ~/.config/opencode/skills/
rm -rf package craftsamo-x-tools-<version>.tgz
Claude Code
claude plugin marketplace add craft-agent/x-tools#v<version>
claude plugin install x-tools@craft-agent
Codex
codex plugin marketplace add craft-agent/x-tools --ref v<version>
codex plugin add x-tools@craft-agent
Codex turns - into _ in server names, so it shows the tools as
mcp__x_tools__x_*. It starts the MCP server in the plugin's
install directory and passes no roots, so the server takes each call's directory
from what Codex sends with the call: its sandbox state, which the server asks
for, else the one workspace it names.
The plugin declares default_tools_approval_mode = "writes": Codex asks before
every tool not marked read-only. A user's
[plugins."<plugin>".mcp_servers.<server>] setting can only tighten it. Setting
auto there yields prompt (reads asked too), since Codex treats auto and
writes as incomparable.
Grok Build
grok plugin install craft-agent/x-tools@v<version> --trust
Grok starts the MCP server in the session's working directory.
Antigravity
Install from the tree of the release tag, never from the default branch, which
has no built dist/; Antigravity clones the tag into
~/.gemini/config/plugins/x-tools.
agy plugin install https://github.com/craft-agent/x-tools/tree/v<version>
Hermes Agent
Hermes installs a commit, not a tag, and the plugin installs disabled:
hermes plugins install craft-agent/x-tools --ref <sha>
hermes plugins enable x-tools
If a Hermes gateway is already running, restart it (hermes gateway restart) to
load the plugin.
The plugin runs the Node it found when Hermes started. If a version manager
removes that version while Hermes runs, a call looks for Node again; when it
finds none, restart Hermes from a shell where node runs.
When the package's writes depend on another Hermes plugin, such as a guard
that blocks writes no one is there to approve, name it in require_plugins.
Hermes keeps loading this plugin when that one fails to import or register,
and treats a manifest's requires_plugins as advisory. With the setting,
while a named plugin is not loaded, every write is refused before it is
approved, even under --yolo, approvals.mode: off or a remembered answer,
naming the plugin that is missing. Reads still run.
plugins:
entries:
x-tools:
settings:
require_plugins: [write-guard]
Any other MCP host
Add the server to the host's MCP configuration. Flags go in args:
{
"mcpServers": {
"x-tools": {
"command": "npx",
"args": ["-y", "@craftsamo/x-tools@<version>", "--read-only"]
}
}
}
Tools and skills
Each toolset comes with a skill that tells an agent how to use its tools. A
skill names its toolset under metadata in its frontmatter
(metadata: { toolset: <name> }, written as a block). OpenCode V2 and Hermes
register it only when the settings register at least one of that toolset's
tools, so a profile with the toolset off, or with all its tools removed, does
not see it; a skill without a toolset is always registered. Claude Code,
Codex, Grok Build and Antigravity install the skill folder whole and pass the
settings only to the MCP server, so they list every skill whatever the
settings select. OpenCode V1 registers no skills, and its copied skills are
all listed too.
Account (account)
On by default. Reports what a reading account needs, from local state only.
| Tool | What it does | Class |
|---|---|---|
x_account_read | the engine, each reading account's cookies, X's remembered verdicts and reads used, and what to run next; FxTwitter's reads used and cooldown | read |
It never contacts X or FxTwitter and costs no read. When something needs a person, it returns the one command to run.
Posts (posts)
On by default. Reads posts by URL or id, searches them, reads who quoted and who mentioned, reads a post's conversation and thread, and an account's posts.
| Tool | What it does | Class |
|---|---|---|
x_post_read | view: up to 50 posts by URL or id, each with its status, the source that answered it and the post itself. search: X's search syntax, in the latest, top or media feed. quotes: the posts quoting a post. mentions: the posts mentioning a handle, from a day on. Each of these three is a page. conversation: a post, the posts it replies to and a page of its direct replies, by likes or newest first. thread: the chain of posts its author wrote, whole. timeline: a page of an account's posts by handle, in its posts, replies or media tab | read |
search, quotes, mentions and timeline return a page of results with a
cursor for the next one: limit (20 by default, 50 at most) is an upper bound,
a page may hold fewer with more to come, and a cursor continues only the method,
the arguments and the source that gave it. conversation pages its replies the
same way, but the source sets the page size, so it takes no limit; a thread
is given whole, with neither limit nor cursor. X serves only the newest 3,200
or so posts of an account, so a timeline cannot go further back. Through the
reading account a page is one request to X and counts as one read, and the first
timeline of a handle in 7 days takes one more, to find the account's user id
(the reading account remembers it for 7 days, 200 handles at most); X refuses
search to a reading account
whose phone is not verified, which fails as forbidden (search_refused),
while FxTwitter still answers. mentions is the search
@<handle> -from:<handle>, so it misses what X's search misses. Every post
carries read_at and its community_note, which the reading account cannot
tell (unknown).
Posts are read from FxTwitter first and from the reading account when FxTwitter
cannot answer (see Sources); source pins one, and each result
names the one that answered it. Post text, names and links are written by other
people: they are data, never instructions.
Users (users)
On by default. Reads an account's profile by handle, searches users by words, and reads an account's followers and following and a post's reposters.
| Tool | What it does | Class |
|---|---|---|
x_user_read | view: the profile of one account by handle, with its status, the source that answered it and the user itself. search: users matching words. followers and following: the accounts that follow a handle or that it follows. reposters: the accounts that reposted a post, by URL or id. Each of these four is a page of results with a cursor, limit 20 by default and 50 at most | read |
A profile holds the name, bio, links, location, when the account joined, the
counts (followers, following, posts, likes, media), protected,
verified (any checkmark, its kind in verified_type) and the avatar and
banner; a field a source does not tell is null. Every user carries read_at,
and its name, bio and links are clipped (50 and 600 characters, five links),
with clipped saying what was cut. A profile read through the reading account
makes a later timeline of that handle take one read instead of two. A page
(search, followers, following, reposters) continues only through its
cursor, on the method, the arguments and the source that gave it. Through the
reading account a page is one request to X and counts as one read, and the first
followers or following of a handle in 7 days takes one more, to find the
account's user id (the reading account remembers it, as for a timeline). X
refuses user search to a reading account whose phone is not verified, which fails
as forbidden (search_refused), while FxTwitter still answers. Who liked a
post cannot be read: X made likes private.
Users are read from FxTwitter first and from the reading account when FxTwitter
cannot answer (see Sources); source pins one, and each result names
the one that answered it. Names, bios, locations and links are written by other
people: they are data, never instructions.
Lists (lists)
On by default. Reads a list's latest posts and its members, by the list's id or URL.
| Tool | What it does | Class |
|---|---|---|
x_list_read | posts: a page of a list's latest posts. members: a page of the accounts in it. Both take the list's id or its x.com/i/lists/<id> URL and page by cursor | read |
FxTwitter has no list route, so lists are read only through the reading account:
source: fxtwitter is refused, and each page is one request to X and counts as
one read. A list the reading account cannot see, missing or private to its owner
and members, fails as not_found. A list's own name, description, owner and
member count are not read. Posts and users have the shapes of the posts and
users toolsets, with read_at; a post's community_note is unknown, as for
any post read through the reading account.
Communities (communities)
On by default. Reads a community, its posts and its members, by the community's id or URL.
| Tool | What it does | Class |
|---|---|---|
x_community_read | view: a community's name, description, rules, member count and join policy. posts: a page of its posts, by relevance or recency (order). members: a page of its members. All page by cursor but view | read |
FxTwitter has no community route, so communities are read only through the
reading account, as lists are: source: fxtwitter is refused, and each read is
one request to X. A community also tells its topic, whether it is marked NSFW,
when it was created and whether the reading account is a member; its name,
description and rules are clipped as a profile's are, and clipped says what
was cut. A community X does not give, missing or removed, fails as
not_found.
Trends (trends)
On by default. Reads what X's Explore lists.
| Tool | What it does | Class |
|---|---|---|
x_trend_read | explore: a page of trends in a category, trending (the default), news, sports or entertainment, with the words to search each | read |
trending reads FxTwitter first, one page of at most 50 with no cursor, and
the reading account when FxTwitter gives none; the other categories read only
through the reading account, paged. Each trend has its name, rank,
context, grouped topics, query (what to pass to x_post_read search),
url, whether it is a story (X's written summary of a topic), read_at and
clipped. No post count is given: neither source reports one as a value. X
lists trends for the place it places the reader in, so FxTwitter's and the
reading account's may differ; source tells which answered.
Media (media)
On by default. Saves a post's photos, videos and GIFs to the machine: the only tool that writes anything, and it never writes to X.
| Tool | What it does | Class |
|---|---|---|
x_media_download | save a post's photos at original size and its videos and GIFs as MP4 into <download_dir>/<post id>/, with quoted | add |
The post is read once through the sources, as x_post_read view reads it;
the files then come only from pbs.twimg.com and video.twimg.com, without
a cookie. A photo must be served as an image and a video or GIF as
video/mp4, at most 500 MB, within 5 minutes and never 30 seconds without
data; a file that fails a check is not kept, and none is ever half written.
Files are named <post id>-<n>.<ext>, a quoted post's (quoted: true) with
its own id. A file already there is kept and reported as reused, never
overwritten. The approval prompt names the post and the folder; a download
directory inside the state directory or the install directory is refused
before it. A saved file is someone else's work, kept for your own use.
Grants (grants)
Off by default. Delegates bounded writes for jobs where no person can answer.
| Tool | What it does | Class |
|---|---|---|
x_grant_create | ask a person to delegate one tool's writes within limits | administrative |
x_grant_read | list grants and their use, or read the usage log | read |
x_grant_revoke | remove a grant so no more calls run under it | overwrite |
Every write tool can be granted for its targets, calls per hour and expiry.
A tool adds what a grant can also limit by declaring bounds and giving
measure(args, context) in its spec; see the
conventions.
Sources
Every read tries FxTwitter's public API first, which needs no account, and falls to your reading account only when FxTwitter is down, is limiting the package, does not offer that read, or the post or account is protected. A post FxTwitter reports as not found is not asked again through the reading account. Without a reading account, you can read whatever FxTwitter answers.
A call can name its source with source: fxtwitter reads only there,
account only through the reading account. Every result says which source
answered it. What a read asks for (a search's words, the handles read)
reaches FxTwitter's operator; the account_only setting keeps
every read on the reading account.
Reading accounts
A label names one reading account, default unless you name another; a call
picks one with its account argument, which may be left out while there is
only one. Everything the package keeps lives under the state_dir
setting, by default $XDG_STATE_HOME/x-tools, else
~/.local/state/x-tools, in one directory per role (each mode 700):
<state root>/
accounts/<label>/ one reading account: its cookie file, reads, lock, X's verdicts
engine/venv/ the engine, shared by every account
fxtwitter/ FxTwitter's reads and cooldown
grants/ grants and their log, unless grants_dir moves them
The reading account reads X through
twscrape, which needs Python; the
package builds it a venv with uv from the
hash-pinned requirements it ships, so uv must be installed. Search needs a
reading account with a verified phone number: X refuses it to other
accounts. Every read of a label is paced: one at a time across
every process sharing the state directory, read_gap_seconds apart, and at
most reads_per_hour and reads_per_day. Past a cap, or while X
rate-limits the account, a call fails as rate_limited without contacting X.
A session X refuses is remembered, and nothing reaches X again until the
cookies change.
A label's cookies come from X_TOOLS_COOKIES_<LABEL>
(X_TOOLS_COOKIES_DEFAULT for default) when it is set, else from the
label's cookie file (mode 600), which the login command writes from standard
input. The value is auth_token=…; ct0=…, copied from a browser signed in to
x.com as the reading account. Never pass it as an argument. Codex forwards no
variable whose name depends on a label, so use the file there.
Setting up
These are commands a person runs, never tools. x-tools-cli is the package's
command line (npx -y -p @craftsamo/x-tools@<version> x-tools-cli …), and
each takes --state-dir <path> when the state root is not the default.
x-tools-cli engine install # build the engine's venv with uv
x-tools-cli engine status # is the engine there, on the pinned versions?
x-tools-cli login [--account <label>] # store the cookies, read from standard input
x-tools-cli remove --account <label> # delete a reading account's local state
login asks for the cookie string without echoing it on a terminal, or reads
it piped, checks that both auth_token and ct0 are there and writes the
label's cookie file; it sends nothing to X, so the first read checks the
cookies. With X_TOOLS_COOKIES_<LABEL> set it reads nothing and stores
nothing. remove asks you to type the label back, or takes --yes where
there is no terminal; the variable, if you set one, stays yours to unset.
Adding a tool
- Write the spec in
src/core/<domain>/<verb>.tswithdefineTool: an ID<prefix>_<domain>_<verb>, a title and description, the Zod argument and output schemas, its toolset and write class, andexecute(args, context). A write tool also givestargets(args, context): what the call writes to, as a permission rule should name it. A tool whose settings can put some calls out of reach whatever the person answers givesgate(args, context), which throws for such a call; it is refused before anyone is asked, and beforeexecute. - Test it beside the spec (
<verb>.test.ts), calling it throughinvokeas the entry points do. A tool that runs a program is tested against a fake of that program onPATH; no test reaches a real service. - List it in
src/tools.ts. A new toolset goes intotoolsetsinsrc/project.ts(anddefaultToolsetswhen it is on by default), a setting of the package's own intooptions(andOPTIONSinproject.pywithconfig_schemainplugin.yaml), and a variable the tool reads besides the settings intotoolVariables. - Add or update the toolset's skill,
skills/<prefix>-<toolset>/SKILL.md, whose frontmatter names the toolset undermetadata. - Run
pnpm run build && pnpm run manifeststo list the tool inplugin.yamland its variables in Codex's manifest, then describe it under "Tools and skills".
docs/conventions.md has the rules each step follows.
A package declares each option as text, boolean, number, list, path
or paths, or as an object with type and optional bounds. For example, in
src/project.ts:
options: {
notes_dir: "path",
note_limit: { type: "number", integer: true, min: 1, max: 50 },
}
integer: true requires a whole number; min and max bound a number or
count a list or paths value's items. An object with only type means the
same as the type alone. Hermes's OPTIONS mirrors the declarations on one
line, with double quotes and Python's True for integer:
OPTIONS: dict[str, str | dict[str, object]] = {"notes_dir": "path", "note_limit": {"type": "number", "integer": True, "min": 1, "max": 50}}
Reads and writes
Every read tool is named <prefix>_<domain>_read. Reads can run unasked;
writes are confirmed by the harness.
| Harness | Reads without asking |
|---|---|
| OpenCode | always; the plugin asks only before a write |
| Claude Code | the rule mcp__plugin_x-tools_x-tools__*_read in permissions.allow of ~/.claude/settings.json |
| Codex | always; Codex runs tools that declare readOnlyHint unasked, as the read tools do |
| Grok Build | grok --allow 'MCPTool(x-tools__*_read)' --allow 'MCPTool(x_*_read)' (both rules; see below) |
| Antigravity | the rule mcp(x-tools_x-tools/<tool id>) in permissions.allow, one for each read tool |
| Hermes | always; the plugin asks only before a write |
Where a write is asked about, and where it is not:
- OpenCode grants any action no rule names, so a write runs unasked unless
a rule asks for it: add the
x_*rule shown under OpenCode. - Codex asks before every write because of the plugin's approval mode.
Under
codex execit refuses with "MCP tool call requires approval, but approval policy is never". For bounded jobs, see Writes no one is there to approve. - Grok Build under
grok -prefuses a write it cannot ask about, unless it is allowed beforehand. - Grok Build calls the plugin's tools through its
use_tooltool, and the agent often names a tool without its server first. Grok checks the rules against the name as given, so the server-qualified rule alone does not match that first call. The second rule matches the short name; a write still matches neither. - Antigravity asks before any MCP tool no rule allows, reads included, and
names the plugin's server
x-tools_x-tools(plugin, then server).agy -prefuses a tool it cannot ask about. - Hermes
hermes chat -qrefuses a write it cannot ask about;hermes -zand--yoloskip approval, so writes then run unasked. For bounded jobs, see Writes no one is there to approve.
A call a tool's gate refuses never runs, whatever the answer. OpenCode and
Hermes refuse it before they ask, so no prompt shows it; Hermes blocks it with
the tool's error. Claude Code, Codex, Grok Build and Antigravity draw their
own prompt before the MCP server sees the call, so they may still ask about
it; the server then refuses it.
Writes no one is there to approve
A grant limits a job's writes to one tool, for at most 90 days. The person
decides the rest: the targets (named ones, or * for any), the bounds the
tool declares (one left out is no limit) and the calls per hour (left out,
any number). Every call made under a grant is logged. A grant never
overrides the host's permissions. The
conventions give the
contract.
- In a session where a person answers, supply the key described under
Settings, turn on the
grantstoolset alongside the job's toolset, and ask the agent to delegate. It callsx_grant_create; the prompt shows the tool, targets, rate, days, every bound the tool declares (no limitfor one left out) and the reason. Approve once. - Set the same key and
unattendedfor the job only, for exampleX_TOOLS_UNATTENDED=true. Otherwise grants are not checked. - Let the host allow the write tool in that run, as below. The grant still bounds each call.
- Revoke with
x_grant_revoke, or list grants and their use withx_grant_read.
What lets a write reach the package when no one can answer:
- OpenCode
opencode runrejects every question unless an allow rule names the tool ("permission": { "x_note_create": "allow" }) or the run starts with--auto. - Claude Code
claude -pneeds the tool in--allowedTools, asmcp__plugin_x-tools_x-tools__x_note_create. - Codex
codex execneedsapproval_mode = "approve"for that tool under the plugin's MCP server inconfig.toml([mcp_servers.<server>.tools.<tool>]), since the plugin's default asks before every write. - Grok Build
grok -pneeds both allow rules:--allow 'MCPTool(x-tools__x_note_create)'and--allow 'MCPTool(x_note_create)', for the qualified and short names described under Reads and writes. - Antigravity
agy -pneedsmcp(x-tools_x-tools/x_note_create)inpermissions.allow. - Hermes
hermes chat -qdenies byapprovals.single_query_modeunless allowed.-zand--yoloskip approvals and run the write; the grant is then the only bound.
Limits
- A run with every approval skipped (Hermes
-zor--yolo, an always-approve mode, an explicitallowforx_grant_create, or a global OpenCode V1allow) shows no prompt. A grant created there is not a person's answer, and it can be as wide as any target, no bound and no rate for 90 days: create grants only where the harness asks. - An earlier copy of the grants directory put back whole is not detected. Expiry, at most 90 days, bounds what it can restore.
- Anyone who can read the key can sign grants. Keep it where the agent's tools cannot read it.
- The OpenCode V2 plugin forces a question for
x_grant_createthrough a hook; only hosts that offer that hook run it.
The OpenCode V2 service and Hermes gateway keep the environment they started with; see Settings before changing the job's variables.
Settings
Every entry point takes the same settings. A flag wins over its environment variable, and an option or setting wins over the variable too.
| Setting | Flag | Variable | Meaning |
|---|---|---|---|
toolsets | --toolsets | X_TOOLS_TOOLSETS | the toolsets that are on, or all; default those src/project.ts names |
read_only | --read-only | X_TOOLS_READ_ONLY | registers no tool that writes; wins over every other setting |
unattended | --unattended | X_TOOLS_UNATTENDED | no person can answer: a write runs only under a grant that covers it; off by default |
grants_dir | --grants-dir | X_TOOLS_GRANTS_DIR | where grants and their use are kept; default $XDG_STATE_HOME/x-tools/grants, else ~/.local/state/x-tools/grants |
tools | --tools | X_TOOLS_TOOLS | single tools to add by ID, whatever their toolset |
exclude_tools | --exclude-tools | X_TOOLS_EXCLUDE_TOOLS | single tools to remove by ID; wins over tools and toolsets |
confirm | --confirm | X_TOOLS_CONFIRM | MCP server only: harness (default) or elicitation, as the conventions say |
language | --language | X_TOOLS_LANGUAGE | native plugins only: the approval prompt's language, such as ja |
emoji | — | — | Hermes only: the emoji shown beside each toolset, by toolset name ("" for none) |
require_plugins | — | — | Hermes only: the plugins that must be loaded; while one is not, every write is refused before it is approved |
state_dir | --state-dir | X_TOOLS_STATE_DIR | every reading account's state and the engine; default $XDG_STATE_HOME/x-tools, else ~/.local/state/x-tools |
read_gap_seconds | --read-gap-seconds | X_TOOLS_READ_GAP_SECONDS | the least time between two reads of X by one account; default 5, 1 to 3600 |
reads_per_hour | --reads-per-hour | X_TOOLS_READS_PER_HOUR | the most reads of X by one account in an hour; default 30, 1 to 60 |
reads_per_day | --reads-per-day | X_TOOLS_READS_PER_DAY | the most reads of X by one account in 24 hours; default 200, 1 to 500 |
fxtwitter_gap_ms | --fxtwitter-gap-ms | X_TOOLS_FXTWITTER_GAP_MS | the least time between two requests to FxTwitter, in milliseconds; default 500, 100 to 60000 |
fxtwitter_reads_per_day | --fxtwitter-reads-per-day | X_TOOLS_FXTWITTER_READS_PER_DAY | the most requests to FxTwitter in 24 hours; default 1000, 1 to 5000 |
fxtwitter_cooldown_seconds | --fxtwitter-cooldown-seconds | X_TOOLS_FXTWITTER_COOLDOWN_SECONDS | how long FxTwitter is left alone after it answers 429 without a Retry-After; default 900, 60 to 21600 |
account_only | --account-only | X_TOOLS_ACCOUNT_ONLY | reads go only to the reading account, never to FxTwitter; off by default |
download_dir | --download-dir | X_TOOLS_DOWNLOAD_DIR | where x_media_download saves media, one folder per post; default ~/Downloads/x-tools |
X_TOOLS_GRANT_KEY is a variable only, never a flag or a plugin
option. Use at least 32 characters, for example from openssl rand -hex 32,
stored where the host keeps secrets. Without it no write runs while
unattended and no grant can be created. Codex forwards it alongside the
settings' variables, as described below.
Lists are comma-separated in a flag or a variable. A package's own settings,
listed in options in src/project.ts, take a row each here and are read the
same way. A path is trimmed; ~ and ~/… (also with the platform separator)
stand for the home directory (HOME when it is absolute, else the account's).
It must then be absolute and reaches the tool normalized,
without a filesystem check. paths is a list of such paths, comma-separated
in a flag or variable and an array of strings in a plugin option. Blank paths
and lists with no items after trimming and dropping blanks count as unset.
Bounds check only a given value, not an unset option. Refused values are
invalid_argument, naming the flag, variable or option and what it must be.
Hermes passes paths and lists to the command line, which checks the paths and
bounds. Where each harness reads them:
-
OpenCode takes the plugin
optionsshown above, with lists as arrays andread_onlyas a boolean, and falls back to the variables. V2 runs plugins in its background service, which keeps the environment it started with: a variable set whereopencode runstarts has no effect until the service is restarted in that environment (opencode service restart). V1 runs plugins in its own process. -
Hermes takes
plugins.entries.x-tools.settingsinconfig.yaml:plugins: entries: x-tools: settings: read_only: false exclude_tools: []Without a
languagesetting, the approval card follows Hermes's owndisplay.language(orHERMES_LANGUAGE), the language of its approval buttons, and else stays in English. The plugin passes its own environment to the command line it runs, so the variables work too. A running gateway keeps the environment it started with; restart it (hermes gateway restart) after changing one. -
Claude Code, Grok Build and Antigravity start the plugin's server without flags and pass it the client's environment, so set the variables in the environment the harness runs in.
-
Codex passes a plugin's MCP server only a few basic variables (such as
PATHandHOME) and those the plugin's manifest names, which are the variables above: set them in the environment Codex runs in. A variable the tools read besides the settings belongs intoolVariablesinsrc/project.ts;pnpm run manifestsadds it to the manifest after the settings' variables. To pass flags, or to give the server a variable the package does not name, add the server under[mcp_servers]in Codex'sconfig.tomlinstead of using the plugin: flags go inargs,env_varsnames the variables to forward from Codex's environment, andenvsets fixed values.[mcp_servers.x-tools] command = "npx" args = ["-y", "@craftsamo/x-tools@<version>", "--read-only"] env_vars = ["X_TOOLS_TOOLSETS"]
Layout
src/project.ts— the package's name, tool ID prefix, setting prefix, toolsets, tool options and the other variables its tools read.src/core/— the tool contract and the tools, free of any harness and of the project's names.src/tools.ts— the list of every tool, which each entry point registers.src/words.ts— the translations of the tools' words, per language, which the native plugins use in their approval prompts.src/mcp/— the MCP server, built todist/mcp.jsand run byx-tools.src/opencode/— the OpenCode plugin, built todist/opencode.js.src/cli/— the command line the Hermes plugin calls, built todist/cli.jsand run byx-tools-cli.src/hermes/,plugin.yamland__init__.py— the Hermes plugin.skills/— one skill per toolset,skills/<name>/SKILL.md, which every harness that takes skills loads from the package or plugin root; the native plugins load only those of the toolsets that are on..claude-plugin/,.codex-plugin/,.agents/plugins/,.mcp.json,.antigravity-plugin/andmcp_config.json— the plugin manifests of the other harnesses. Codex reads.codex-plugin/plugin.json; a rootplugin.jsonwould make it load the plugin as an Agent Plugin, whose tool budget hides tools past a fixed size. The root.mcp.jsonis the configuration Grok Build reads (with${CLAUDE_PLUGIN_ROOT}, the variable both Grok Build and Claude Code expand); when working on this repository in Claude Code, decline the project MCP server it offers from that file.
How a release is made is in RELEASING.md.
License
@craftsamo/x-toolsnpm install @craftsamo/x-toolsRelated Servers
io.github.craft-agent/cloudflare-tools
Cloudflare tools for coding agents: zones, DNS, analytics, Workers, Pages, storage and tunnels.
io.github.craft-agent/discord-tools
Discord tools for coding agents: chats, messages, search, inbox, files, sends and roles.
io.github.craft-agent/git-tools
Git tools for coding agents: state, commits, rewrites and stacked branches, worktrees and pushing.