Theseus-shell

Theseus-shell is a rust shell wrapper with an embedded LLM agent.

It runs regular shell commands through a PTY, keeps command input/output history, and can switch from shell mode into agent-assisted workflows.

If you are wondering why another agent should exist, the short motivation is described in docs/MOTIVATION.md.

Install

curl -fsSL https://raw.githubusercontent.com/tttzof351/theseus-shell/master/install.sh | bash

Shell usage

Regular input is executed as a shell command. Natural-language input is routed to the agent when it does not look like a shell command. Use /ask ... to explicitly talk to the agent.

Natural-language shell workflow:

Fixing the last failed command:

MCP servers

Theseus reads MCP server configuration from ~/.theseus/config.jsonc. Add servers under the top-level mcp_servers object. Each server id becomes part of the public tool name exposed to the agent.

For example, Tavily (around 1,000 free requests per month) can be added as a remote MCP server for web search, together with a local pdf-mcp server:

{
  ...
  "mcp_servers": {
    "tavily-remote-mcp": {
      "type": "http",
      "url": "https://mcp.tavily.com/mcp/?tavilyApiKey=<TAVILY_API_KEY>"
    },
    "pdf-mcp": {
      "command": "uvx",
      "args": ["pdf-mcp@1.14.0"],
      "env": {
        "PDF_MCP_CACHE_DIR": "~/.cache/pdf-mcp",
        "PDF_MCP_CACHE_TTL": "24"
      }
    }
  }
}

After updating the config, restart Theseus and run /mcp to check server status and see the public tool names available to the agent.