MaskShift

A maximalist, model-agnostic coding harness for the terminal.
Every tool at the model's disposal — only the ones it needs in its context.

MaskShift gives a coding model one control plane for repository understanding, file edits, the host shell, Git recovery, language servers, browsers, containers, databases, remote machines, memory, scheduled work, plugins, external coding agents, skills and MCP servers. The full catalog is always available to the harness; only the capabilities relevant to the current step are inserted into model context.

It runs on Node.js 22 using only built-in modules — the interface renderer included. No npm runtime dependency tree, no HTTP server, no browser, no listening socket.

---

Contents

Features · Install · Run it with Ollama · Configure · The interface · The command line · Documentation · Development · Deployment

Features

Install

Requirements

• Node.js 22 or newer
• A terminal at least 80×24 (UTF-8 and truecolour are used when available, and degraded cleanly when not)
• Git and ripgrep recommended
• Any instruction-following model through Ollama or another configured provider

Install from npm

npm install -g maskshift
cd /path/to/repository && maskshift

Or run it without installing anything:

npx maskshift --workspace /path/to/repository

Or run from the source directory

git clone https://github.com/nafeeur/MaskShift.git
cd MaskShift
./start.sh --workspace /path/to/repository

Or install to your user account from source

./install.sh
cd /path/to/repository && maskshift

The installer copies MaskShift to ~/.local/lib/maskshift and links ~/.local/bin/maskshift. It does not run npm install, because there is nothing to install — MaskShift has zero runtime dependencies.

Run it with Ollama

MaskShift's default model reference is ollama:auto: it discovers your installed Ollama models and prefers the strongest coding-oriented one it finds.

# 1. Pull a coding model
ollama pull qwen3-coder:latest

# 2. Point MaskShift at Ollama and pick the model
export OLLAMA_BASE_URL=http://127.0.0.1:11434
export MASKSHIFT_MODEL=ollama:qwen3-coder:latest

# 3. Open the interface on a repository
./start.sh --workspace ~/code/my-project

Type a task into the composer and press ↵. To run one task headlessly instead:

./start.sh run "Map this repository, repair the highest-impact defect, add tests, and verify." \
  --workspace ~/code/my-project \
  --model ollama:qwen3-coder:latest

A remote Ollama host works the same way — set OLLAMA_BASE_URL=http://model-host:11434.

If a model has no native tool API, MaskShift detects it on the first request and switches to an in-prompt text protocol, so the whole harness still works. → models without native tool calling

Configure

Model references are provider:model:

ollama:auto                 openai:<model-id>            anthropic:<model-id>
lmstudio:auto               openrouter:provider/model    gemini:<model-id>
vllm:auto

Cloud providers read their keys from the environment:

export OPENAI_API_KEY=...      export ANTHROPIC_API_KEY=...
export OPENROUTER_API_KEY=...  export GEMINI_API_KEY=...

Everything else lives in ~/.maskshift/config.json — providers, MCP servers, agent bridges, hooks, indexing, memory ranking, automations and interface preferences. Press f2 in the interface to edit the core settings without touching the file, or use maskshift config set.

→ full configuration reference · environment variables · data locations

The interface

maskshift opens a full-screen terminal application built on a bespoke, zero-dependency renderer, driven equally by keyboard and mouse. Six views switch with 1–6, ctrl+b toggles the right rail, and ctrl+k opens a fuzzy command palette over every action.

Below 108 columns the rail hides itself and the header sheds telemetry, so the same six views work in a narrow split pane. MASKSHIFT_MOUSE=off (or f2) hands text selection back to the terminal, and NO_COLOR, MASKSHIFT_COLOR=off and MASKSHIFT_ASCII=1 each produce a clean, aligned fallback.

→ keys, views and the design system

The command line

Everything the interface can do is also a subcommand, and every subcommand takes --json:

maskshift run "make the failing tests pass"      # one headless run, streamed
maskshift tools run shell_exec '{"command":"npm test"}'
maskshift mcp registry playwright && maskshift mcp install io.github.microsoft/playwright-mcp
maskshift automation create nightly --schedule "every 6h" --prompt "Review the diff and fix regressions"
maskshift workspace search "checkpoint restore" --json | jq -r '.[].path'
maskshift doctor

maskshift [tui] [PROMPT]     open the interface (the default command)
maskshift run "PROMPT"       one headless run, streamed to stdout
maskshift daemon             resident automation scheduler, no interface
maskshift doctor             environment and provider diagnostics
maskshift <workspace|session|tools|skills|mcp|plugins|automation|browser|config> ...

Global flags: --workspace PATH, --model REF, --config PATH, --json, --no-color.

→ full command reference

Documentation

Development

npm run check       # syntax validation across every source module
npm test            # unit and integration suite, including renderer tests
npm run test:tools  # all-native-tool scenarios and edge-case regressions
npm run smoke       # end-to-end agent run plus a full interface paint
npm run verify      # check + tests + smoke
npm run docs        # regenerate the tool and skill inventories
npm run capture     # regenerate docs/screenshots from the real renderer

The screenshots above are produced by npm run capture through the same code path the terminal uses, so they cannot drift from the product.

Deployment

• deploy/maskshift.service — user-level systemd unit running maskshift daemon for scheduled automations, with no interface.
• Dockerfile / compose.yaml — /workspace and /data volumes. MaskShift is a terminal application, so attach a TTY: docker run -it, or docker compose run --rm maskshift.

A container limits MaskShift to the files, sockets, devices and credentials mounted into it. For full host authority, run the user service directly instead.

License

GNU General Public License v3.0.