Repository avatar
Multimedia
v0.1.0
active

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.

HarnessDeliveryPinned by
OpenCode V2native plugin (npm package, with skills)the version in the package
OpenCode V1native plugin (npm package, no skills)the version in the package
Claude Codeplugin: MCP server and skillsthe release tag, as the ref
Codexplugin: MCP server and skillsthe release tag, as the ref
Grok Buildplugin: MCP server and skillsthe release tag, as @ref
Antigravityplugin: MCP server and skillsthe release tag's tree URL
Hermes Agentnative plugin (Python, calls the command line)the release commit, as the SHA
other MCP hostMCP server from npmthe 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.

ToolWhat it doesClass
x_account_readthe engine, each reading account's cookies, X's remembered verdicts and reads used, and what to run next; FxTwitter's reads used and cooldownread

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.

ToolWhat it doesClass
x_post_readview: 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 tabread

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.

ToolWhat it doesClass
x_user_readview: 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 mostread

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.

ToolWhat it doesClass
x_list_readposts: 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 cursorread

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.

ToolWhat it doesClass
x_community_readview: 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 viewread

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.

ToolWhat it doesClass
x_trend_readexplore: a page of trends in a category, trending (the default), news, sports or entertainment, with the words to search eachread

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.

ToolWhat it doesClass
x_media_downloadsave a post's photos at original size and its videos and GIFs as MP4 into <download_dir>/<post id>/, with quotedadd

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.

ToolWhat it doesClass
x_grant_createask a person to delegate one tool's writes within limitsadministrative
x_grant_readlist grants and their use, or read the usage logread
x_grant_revokeremove a grant so no more calls run under itoverwrite

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

  1. Write the spec in src/core/<domain>/<verb>.ts with defineTool: an ID <prefix>_<domain>_<verb>, a title and description, the Zod argument and output schemas, its toolset and write class, and execute(args, context). A write tool also gives targets(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 gives gate(args, context), which throws for such a call; it is refused before anyone is asked, and before execute.
  2. Test it beside the spec (<verb>.test.ts), calling it through invoke as the entry points do. A tool that runs a program is tested against a fake of that program on PATH; no test reaches a real service.
  3. List it in src/tools.ts. A new toolset goes into toolsets in src/project.ts (and defaultToolsets when it is on by default), a setting of the package's own into options (and OPTIONS in project.py with config_schema in plugin.yaml), and a variable the tool reads besides the settings into toolVariables.
  4. Add or update the toolset's skill, skills/<prefix>-<toolset>/SKILL.md, whose frontmatter names the toolset under metadata.
  5. Run pnpm run build && pnpm run manifests to list the tool in plugin.yaml and 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.

HarnessReads without asking
OpenCodealways; the plugin asks only before a write
Claude Codethe rule mcp__plugin_x-tools_x-tools__*_read in permissions.allow of ~/.claude/settings.json
Codexalways; Codex runs tools that declare readOnlyHint unasked, as the read tools do
Grok Buildgrok --allow 'MCPTool(x-tools__*_read)' --allow 'MCPTool(x_*_read)' (both rules; see below)
Antigravitythe rule mcp(x-tools_x-tools/<tool id>) in permissions.allow, one for each read tool
Hermesalways; 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 exec it 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 -p refuses a write it cannot ask about, unless it is allowed beforehand.
  • Grok Build calls the plugin's tools through its use_tool tool, 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 -p refuses a tool it cannot ask about.
  • Hermes hermes chat -q refuses a write it cannot ask about; hermes -z and --yolo skip 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.

  1. In a session where a person answers, supply the key described under Settings, turn on the grants toolset alongside the job's toolset, and ask the agent to delegate. It calls x_grant_create; the prompt shows the tool, targets, rate, days, every bound the tool declares (no limit for one left out) and the reason. Approve once.
  2. Set the same key and unattended for the job only, for example X_TOOLS_UNATTENDED=true. Otherwise grants are not checked.
  3. Let the host allow the write tool in that run, as below. The grant still bounds each call.
  4. Revoke with x_grant_revoke, or list grants and their use with x_grant_read.

What lets a write reach the package when no one can answer:

  • OpenCode opencode run rejects every question unless an allow rule names the tool ("permission": { "x_note_create": "allow" }) or the run starts with --auto.
  • Claude Code claude -p needs the tool in --allowedTools, as mcp__plugin_x-tools_x-tools__x_note_create.
  • Codex codex exec needs approval_mode = "approve" for that tool under the plugin's MCP server in config.toml ([mcp_servers.<server>.tools.<tool>]), since the plugin's default asks before every write.
  • Grok Build grok -p needs 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 -p needs mcp(x-tools_x-tools/x_note_create) in permissions.allow.
  • Hermes hermes chat -q denies by approvals.single_query_mode unless allowed. -z and --yolo skip approvals and run the write; the grant is then the only bound.

Limits

  • A run with every approval skipped (Hermes -z or --yolo, an always-approve mode, an explicit allow for x_grant_create, or a global OpenCode V1 allow) 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_create through 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.

SettingFlagVariableMeaning
toolsets--toolsetsX_TOOLS_TOOLSETSthe toolsets that are on, or all; default those src/project.ts names
read_only--read-onlyX_TOOLS_READ_ONLYregisters no tool that writes; wins over every other setting
unattended--unattendedX_TOOLS_UNATTENDEDno person can answer: a write runs only under a grant that covers it; off by default
grants_dir--grants-dirX_TOOLS_GRANTS_DIRwhere grants and their use are kept; default $XDG_STATE_HOME/x-tools/grants, else ~/.local/state/x-tools/grants
tools--toolsX_TOOLS_TOOLSsingle tools to add by ID, whatever their toolset
exclude_tools--exclude-toolsX_TOOLS_EXCLUDE_TOOLSsingle tools to remove by ID; wins over tools and toolsets
confirm--confirmX_TOOLS_CONFIRMMCP server only: harness (default) or elicitation, as the conventions say
language--languageX_TOOLS_LANGUAGEnative 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-dirX_TOOLS_STATE_DIRevery reading account's state and the engine; default $XDG_STATE_HOME/x-tools, else ~/.local/state/x-tools
read_gap_seconds--read-gap-secondsX_TOOLS_READ_GAP_SECONDSthe least time between two reads of X by one account; default 5, 1 to 3600
reads_per_hour--reads-per-hourX_TOOLS_READS_PER_HOURthe most reads of X by one account in an hour; default 30, 1 to 60
reads_per_day--reads-per-dayX_TOOLS_READS_PER_DAYthe most reads of X by one account in 24 hours; default 200, 1 to 500
fxtwitter_gap_ms--fxtwitter-gap-msX_TOOLS_FXTWITTER_GAP_MSthe least time between two requests to FxTwitter, in milliseconds; default 500, 100 to 60000
fxtwitter_reads_per_day--fxtwitter-reads-per-dayX_TOOLS_FXTWITTER_READS_PER_DAYthe most requests to FxTwitter in 24 hours; default 1000, 1 to 5000
fxtwitter_cooldown_seconds--fxtwitter-cooldown-secondsX_TOOLS_FXTWITTER_COOLDOWN_SECONDShow long FxTwitter is left alone after it answers 429 without a Retry-After; default 900, 60 to 21600
account_only--account-onlyX_TOOLS_ACCOUNT_ONLYreads go only to the reading account, never to FxTwitter; off by default
download_dir--download-dirX_TOOLS_DOWNLOAD_DIRwhere 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 options shown above, with lists as arrays and read_only as 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 where opencode run starts 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.settings in config.yaml:

    plugins:
      entries:
        x-tools:
          settings:
            read_only: false
            exclude_tools: []
    

    Without a language setting, the approval card follows Hermes's own display.language (or HERMES_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 PATH and HOME) 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 in toolVariables in src/project.ts; pnpm run manifests adds 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's config.toml instead of using the plugin: flags go in args, env_vars names the variables to forward from Codex's environment, and env sets 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 to dist/mcp.js and run by x-tools.
  • src/opencode/ — the OpenCode plugin, built to dist/opencode.js.
  • src/cli/ — the command line the Hermes plugin calls, built to dist/cli.js and run by x-tools-cli.
  • src/hermes/, plugin.yaml and __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/ and mcp_config.json — the plugin manifests of the other harnesses. Codex reads .codex-plugin/plugin.json; a root plugin.json would make it load the plugin as an Agent Plugin, whose tool budget hides tools past a fixed size. The root .mcp.json is 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

AGPL-3.0 with Commons Clause