Gremlin in the Machine is a sophisticated AI agent designed to enhance terminal productivity by executing shell tasks efficiently. By utilizing Claude, a large language model, Gremlin allows users to set goals, plans and executes commands, tracks progress, and provides updates—all within the confines of a single terminal window, making it a versatile tool for both macOS and Linux.

Key Features

• Terminal-based AI Assistant: Gremlin operates directly in the terminal, allowing users to interact seamlessly with the AI without the need for a graphical interface.
• Task Planning and Execution: Simply enter a goal, and Gremlin constructs a detailed checklist of required actions, executes commands sequentially, and waits for user input to proceed. This functionality ensures users maintain control over the process, enhancing their command over the system.

~/your/folder > install nginx and check if it's running

Task plan:
  ▶ Check if nginx is installed
  ○ Install nginx
  ○ Verify nginx is running

Agent: Checking if nginx is already installed...

$ which nginx
  /usr/bin/nginx

• Built on the AIKISS Philosophy: Rooted in the principle of "Artificial Intelligence Keep It Small and Simple", Gremlin extends the Unix philosophy of modular and composable components into the AI domain, creating an intuitive and efficient environment for task management.

Usage

To interact with Gremlin, enter your desired task at the command prompt:

python3 gitm.py

Example interactions:

~/your/folder > show me how much disk space is free and which folders are largest
~/your/folder > install qemu via homebrew
~/your/folder > check if port 8080 is in use and what process is using it
~/your/folder > create a python virtual environment and install requests and flask

After each command successfully executes, simply type continue or press Enter to advance to the next item in the checklist.

Configuration Options

Users can adjust behavior and settings via the config.json file, including:

• API Key: Store your Anthropic API key for seamless interaction with the service.
• Model Selection: Choose between different Claude models to suit specific task needs.
• Timeout Settings: Modify the command timeout for lengthy operations such as installations or upgrades.

{
  "api_key": "",
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "max_history_lines": 80,
  "confirm_destructive": true,
  "command_timeout": 600
}

Efficient Cost Structure

Users can expect minimal costs associated with Gremlin’s operations, with each turn utilizing approximately 2,000 to 4,000 input tokens and around 300 output tokens. With a $5 Anthropic credit load, hundreds of interactions can be facilitated, making Gremlin an economical choice for task management.

Gremlin not only empowers users to maintain control over shell commands but also embraces the future of AI-driven terminal operations, adhering to the AIKISS principles for an efficient and effective user experience.