XActions AGENTS.md

XActions for agents

X/Twitter automation with no X API key: a 56-command CLI, a Node library, 152 MCP tools, 50 agent skills, 95 browser console scripts, and a web dashboard. Apache-2.0, by nichxbt.

This file is for the agent, not the human. It answers one question first, because getting it wrong costs the whole session: do you shell out to the CLI, or do you load the MCP server?

---

Two lanes into the same engine

XActions ships both lanes from one install, and they call the same code. The difference is what each costs you before you have read a single tweet.

	CLI lane	MCP lane
How you call it	one Bash call, xactions <cmd> --compact	a tool call, after the client connects the server
What loads into context up front	nothing	the whole tool list
What comes back	the rows you asked for, one per line	a JSON result object
Writes	reads, plus engage and bulk	every write tool, with an approval gate
Usable without client configuration	yes, it is just a process	no, the client must be configured first

The tool list is not small. The server advertises 152 tools, and the tools/list payload it serves is about 60 KB of JSON before you have done any work at all. Measure it yourself:

node -e "import('./src/mcp/server.js').then(m => console.log(JSON.stringify(m.TOOLS).length, 'bytes,', m.TOOLS.length, 'tools'))"

That cost is worth paying when you are going to make many calls in a session, keep state between them, or write. It is not worth paying to answer "how many followers does this account have."

The rule

Reading a handful of things? Shell out. Working a long session, or writing? Load the server.

Concretely, prefer the CLI when:

• You need one or two facts and then you are done.
• You are inside a larger task where X is a detail, not the subject.
• You want to pipe, filter, or count the result with jq, grep, sort, wc, or feed it to another command in the same Bash call.
• The client has no MCP configuration and you are not going to add one.