shmakk

AI-supervised terminal wrapper — command correction, tool-driven task execution, safety confirmations, and profile-based runtime modes.

Your terminal, supercharged by AI. Optionally: talk to it.

Live demo →

Requirements

• Node.js 18+
• Linux or macOS shell environment

Install

npm install -g shmakk

That's it. Once installed, use shmakk anywhere:

shmakk --help

Quick start

1. Set up an AI provider

export SHMAKK_BASE_URL="https://your-provider.example/v1"
export SHMAKK_API_KEY="your-api-key"
export SHMAKK_MODEL="gpt-4o-mini"

Or configure multiple native model providers in ~/.config/shmakk/endpoints.json:

{
  "main": "gpt5-codex",
  "models": {
    "gpt5-codex": {
      "provider": "codex",
      "model": "gpt-5-codex",
      "api_key": "OPENAI_API_KEY"
    },
    "local": {
      "provider": "openai-compatible",
      "base_url": "http://127.0.0.1:1234/v1",
      "model": "qwen/qwen3.5-9b"
    },
    "claude": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-5-20250929",
      "api_key": "ANTHROPIC_API_KEY"
    }
  }
}

shmakk --endpoint claude
shmakk --model-recommendation

2. Launch

shmakk

You're now in an AI-supervised terminal. Type commands as normal. shmakk will:

• Correct mistakes — typo in gti status? shmakk suggests git status. If the correction succeeds, shmakk follows up with the agent using your original intent, not just the fixed command.
• Execute tasks — ask "set up a new React project" and shmakk handles the steps
• Keep you safe — confirms risky commands before running them

Voice (optional)

speak naturally — shmakk listens, transcribes, responds, and reads its answer aloud. No push-to-talk.

# Install system dependency
sudo pacman -S sox        # Arch/EndeavourOS
sudo apt install sox      # Debian/Ubuntu
brew install sox          # macOS

# Install voice deps and run preflight check
npm run setup:voice

# Launch in speech-to-speech mode
shmakk --sts

Say "stop" or "quiet" to interrupt TTS mid-sentence.

→ Full voice documentation: docs/voice.md

Profiles

Choose a profile to match your workflow:

| Profile | Use case | |---------|----------| | tiny | Minimal context, fastest responses | | balanced | Default — good for daily work | | deep | Larger investigations, multi-step tasks | | builder / large-app | Editing and building large projects |

shmakk --profile builder

Switch profiles mid-session:

shmakk --profile-set deep

Skills

Skills are task-specific markdown files loaded into the agent's context on demand. The skills/ directory contains 32 built-in skills covering areas like code-review, research, backend, devops, sysmon, logs, and more.

shmakk --install-skill <name>   # install a skill from the built-in library
shmakk --load-skill <name>      # load an installed skill for this session
shmakk --list-skills            # show currently loaded skills

Coordinator & Multi-step workflows

The coordinator system enables complex, multi-step task execution with plan-first workflows. When tackling large projects or intricate tasks, shmakk breaks them into manageable steps, validates each stage, and maintains context across the entire workflow.

Environment variables

| Variable | Description | |----------|-------------| | SHMAKK_BASE_URL | OpenAI-compatible base URL | | SHMAKK_API_KEY | API key | | SHMAKK_MODEL | Default model | | SHMAKK_PROVIDER | openai-compatible, codex, or anthropic | | SHMAKK_HEADERS | Extra headers (k=v,k=v) | | SHMAKK_MODEL_RECOMMENDATION | Set to 1 to let the configured main model route each call |

Useful commands

| Command | What it does | |---------|-------------| | shmakk --help | Show help | | shmakk --status | Check if inside shmakk | | shmakk --stats | Session statistics | | shmakk --compact | Clear conversation history | | shmakk --install-skill <name> | Install a skill from the built-in library | | shmakk --load-skill <name> | Load an installed skill for this session | | shmakk --list-skills | List loaded skills | | shmakk --reset | Reset conversation + task journal | | shmakk --restart | Restart the inner shell | | shmakk --exit | Exit shmakk | | shmakk --review | Confirm every AI action | | shmakk --yes-files | Auto-accept file writes | | shmakk --no-correction | Disable command correction | | shmakk --colors true\|false | Toggle colored output | | shmakk --sts | Speech-to-speech mode | | shmakk --stt | Mic input, text responses | | shmakk --tts | Text input, spoken responses |

Safety

• shmakk prompts you before running commands flagged as risky (writes, deletes, network, installs)
• Secrets (.env, keys, tokens) are never sent to the AI
• Workspace root is enforced — tools can't access files outside it

Remote SSH

The agent can run commands and transfer files on remote hosts via SSH. Configure hosts in .shmakk/hosts.json (per-project) or ~/.config/shmakk/hosts.json (global):

{
  "hosts": {
    "devbox": {
      "host": "[email protected]",
      "port": 22,
      "auto_approve": false,
      "timeout_sec": 30
    },
    "staging": {
      "host": "[email protected]",
      "port": 2247
    }
  },
  "allow_ssh_config": false,
  "default_timeout_sec": 30
}

| Tool | Description | |------|-------------| | ssh_run | Run a shell command on a remote host | | ssh_push | Copy a local workspace file to a remote host | | ssh_pull | Copy a remote file into the local workspace |

SSH key auth via ~/.ssh is assumed. For persistent connections (avoid re-auth on every call), add to ~/.ssh/config:

Host *
  ControlMaster auto
  ControlPath ~/.ssh/controlmasters/%r@%h:%p
  ControlPersist 600

Then mkdir -p ~/.ssh/controlmasters once.

How it works

shmakk wraps your shell in a PTY (pseudo-terminal). Every command that fails is checked against a deterministic correction engine (no LLM, no API call). If a correction matches and the fixed command succeeds, shmakk feeds the agent your original input (not the fixed command) so the agent can address your full intent — not just the typo. You can also give task instructions in natural language — shmakk uses tools to read files, write code, list directories, and run commands, all constrained to your workspace.

License

MIT