Gremlin in the Machine

A small, clever AI agent that lives in your terminal and gets things done.

An AI agent by Milan Kazarka. Gremlin runs in your terminal and lets you give goals to an AI (Claude) which then plans, executes shell commands, tracks progress, and reports back — all within a single terminal window. No desktop needed. Works on macOS and Linux.

Built on the AIKISS philosophy — Artificial Intelligence Keep It Small and Simple — which extends the Unix principle of small, composable, self-describing components into the AI era.

Licensed under the MIT License.

---

How it works

You type a goal. Gremlin builds a checklist, executes commands one by one, and tracks where it is in the task. The AI always sees the terminal history and current checklist, so it knows exactly what step it's on and what to do next.

~/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

Note: After each command completes, you need to press Enter (or type continue) to move to the next step. Gremlin executes one command at a time and waits for you — this keeps you in control and lets you redirect it at any point.

---

Requirements

• Python 3.8 or newer
• An Anthropic API key — console.anthropic.com/settings/keys
• Anthropic API credits — console.anthropic.com/settings/billing ($5 is enough to start)

---

Installation

1. Get the code

git clone https://github.com/milankazarka/gremlin
cd gremlin

2. Install the Anthropic library

pip3 install anthropic

If pip3 is not found, try:

python3 -m pip install anthropic

On newer Linux systems that block system-wide installs:

python3 -m pip install anthropic --break-system-packages

Or use a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
pip install anthropic

3. Get your API key

• Go to console.anthropic.com and sign up or log in (this is separate from claude.ai)
• Add credits: Settings → Billing → Buy Credits
• Create a key: Settings → API Keys → Create Key
• The key starts with sk-ant-

4. Set your API key

Option A — environment variable (recommended):

export ANTHROPIC_API_KEY=sk-ant-your-key-here

Add that line to your ~/.zshrc or ~/.bashrc to make it permanent.

Option B — config file, paste your key into config.json:

{
  "api_key": "sk-ant-your-key-here"
}

---

Running Gremlin

python3 gitm.py

Type a goal at the prompt and press Enter:

~/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 runs, type continue or press Enter to move to the next step in the checklist. You can also redirect Gremlin at any point by typing a new instruction.

Built-in commands

Command	Description
continue	Proceed to the next step in the checklist
checklist	Show the current task plan and status
history	Show recent terminal output
quit	Exit and save the session

---

Configuration

Edit config.json to adjust behaviour:

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

Option	Default	Description
api_key	""	Anthropic API key (or use env variable)
model	claude-sonnet-4-6	Claude model to use
max_tokens	1024	Max tokens per LLM response
max_history_lines	80	Lines of terminal history sent to the LLM
confirm_destructive	true	Ask before risky commands like rm -rf
command_timeout	600	Seconds before a command times out

Set command_timeout high for commands like brew install or apt upgrade that can take several minutes.

---

Cost

Each turn uses roughly 2,000–4,000 input tokens and ~300 output tokens. At Sonnet 4.6 pricing that is around $0.01–0.02 per turn. A $5 credit load covers hundreds of interactions.

---

Notes

• Gremlin runs commands with your current user permissions. Do not run as root unless you know what you are doing.
• Destructive commands (rm -rf, mkfs, etc.) always ask for confirmation before running.
• On macOS, Gremlin is aware it is running on Darwin and uses macOS-correct commands.
• If the LLM makes a mistake, just tell it what went wrong and it will adjust its plan.
• session.json is saved after each turn and records the goal, checklist, and history. It does not store your API key.

---

Architecture

Gremlin is built on the AIKISS philosophy — Artificial Intelligence Keep It Small and Simple. AIKISS extends the Unix principle of small, composable, self-describing components into the AI era: each piece does one thing, describes itself explicitly, and can be reasoned about by both humans and machines.

gitm.py        # everything: session, LLM loop, command execution, display
config.json    # your settings and API key
session.json   # auto-generated, current session state

---

Gremlin in the Machine — An AI agent by Milan Kazarka Built on the AIKISS philosophy — github.com/milankazarka/aikiss MIT License