Other Agents

Any agent that can run a command in a terminal can use Filestar. It does not need a skill or an MCP entry: it needs filestarcli on the PATH and the readme.

Next release. filestarcli agent install, agent readme and mcp are not in the released CLI (npm filestar 30.5.1); they arrive with the next release. Until then this page describes what is coming. See Use Filestar With AI Agents.

Point the agent at the readme

Tell your agent, or add to its instructions file (AGENTS.md, .cursorrules, a system prompt):

To convert, resize, compress or inspect files, use the Filestar CLI. Run filestarcli agent readme first and follow it.

filestarcli agent readme prints the whole guide as markdown, versioned with the CLI: the commands, the JSON results, the exit codes and what to do about each error. filestarcli agent readme --format json gives the same as JSON. The same text is at filestar.com/agents.md.

If the agent cannot install anything, it can run Filestar through npx:

npx -y filestar -i photo.heic -c "convert to jpg" --json

Say who is driving: --user-agent

Pass --user-agent with the agent's name and version on every command:

filestarcli -i photo.heic -c "convert to jpg" --json --user-agent my-agent/1.2

or set it once in the environment:

FILESTAR_USER_AGENT=my-agent/1.2

Filestar uses the name to count which agents use it and to fix problems that affect one agent. Without it, the CLI makes a guess from the environment. See Privacy.

opencode

filestarcli agent install --agent opencode

adds the MCP server to ~/.config/opencode/opencode.json. By hand:

{
  "mcp": {
    "filestar": {
      "type": "local",
      "command": ["filestarcli", "mcp"],
      "enabled": true
    }
  }
}

Windsurf

filestarcli agent install --agent windsurf

adds the MCP server to ~/.codeium/windsurf/mcp_config.json. By hand:

{
  "mcpServers": {
    "filestar": {
      "command": "filestarcli",
      "args": ["mcp"]
    }
  }
}

Restart Windsurf after changing the file.

Any other MCP client

Run filestarcli mcp as a local (stdio) MCP server. The tools are described on MCP Server.