# 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 →](https://marbad1994.github.io/shmakk/)**

## Requirements

- **Node.js 18+**
- **Linux or macOS** shell environment

## Install

```bash
npm install -g shmakk
```

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

```bash
shmakk --help
```

## Quick start

### 1. Set up an AI provider

```bash
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`:

```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"
    }
  }
}
```

```bash
shmakk --endpoint claude
shmakk --model-recommendation
```

### 2. Launch

```bash
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.

```bash
# 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](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 |

```bash
shmakk --profile builder
```

Switch profiles mid-session:

```bash
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.

```bash
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):

```json
{
  "hosts": {
    "devbox": {
      "host": "marcus@192.168.1.100",
      "port": 22,
      "auto_approve": false,
      "timeout_sec": 30
    },
    "staging": {
      "host": "deploy@10.0.0.5",
      "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
