maskshift

A general-purpose agent harness for any model, in one terminal application with no runtime dependencies.
Give a model controlled access to your files, shell, browser, documents and services, and let it carry a task through to a verified result.

MaskShift connects a language model to the tools it needs to get real work done — reading and writing files, running commands, browsing the web, working with PDFs and notebooks, querying databases, calling MCP servers, remembering what matters and delegating to sub-agents — and keeps a person in control with checkpoints, an audit log and optional approvals.

It works for software engineering, but nothing about it is specific to code: summarize a folder of invoices into a spreadsheet, research a topic and write up the findings, reorganize files, run a recurring report. The model is a line of configuration; the tools are the same whichever one you use.

Highlights

• Any model. Ollama, LM Studio, vLLM, OpenAI, Anthropic, Gemini, OpenRouter and any OpenAI-compatible server. A model with no native tool API still gets the full tool surface through an in-prompt protocol. → providers
• Adapts to the model. Each model gets a help level from 0 to 3 — measured by maskshift model calibrate, refined by how it actually performs, and raised mid-run if it keeps stumbling. A strong model is left alone; a small local one gets a compact prompt, a short tool menu and tight output budgets. → adaptive harness
• Reliable tool use. Near-miss tool names and arguments are repaired in code, edits tolerate whitespace and indentation drift, tool output is cleaned and fitted to the model's window, and every file edit is checked immediately. → run guardrails
• Loaded on demand. 201 native tools, 50 skills and any number of MCP servers are available, but only what the current step needs enters the model's context. → tools · skills
• Controlled by design. Automatic checkpoints before each run, an append-only audit log, and three permission modes from fully autonomous to approve-everything. → permissions
• Web tasks from the terminal. A browser runs in the background while options (restaurants, products, results) are put to you as a picker, sign-ins are typed in the terminal without the model ever seeing them, and CAPTCHAs are handed to you in the live Browser view. → web tasks
• Remembers and improves. Persistent memory that notices when its sources change, reusable skills, and skill upgrades promoted only after measured A/B trials.
• Learns from its own runs. Routes tasks to the model or agent with the best record on that kind of work (and moves a stuck run up to the next candidate), remembers what failed and what fixed it, notices how you want things done, turns repeated workflows into skills, asks before irreversible commands, and stops a run that is going nowhere with a plain report. Local, visible and removable. → learning
• Keeps its disk use in check. Indexing, checkpoints, logs and the database stay inside a budget worked out from your machine's disk and memory, shrinking retention as free space gets scarce, and never touching your chats, memory or files. → disk use
• Works unattended. Schedule agent runs, tool calls or shell commands by interval, cron expression or timestamp. → automations
• A fleet of agents. Run Claude Code, Codex, OpenCode, Hermes, Copilot CLI, Aider, custom CLIs and MaskShift's own engine as one team — several of each if you like — that message each other to get a task done, controlled from one view, one command or by the model itself. → agent fleet
• Open on both sides. Use MCP servers, plugins and external coding agents; or run maskshift mcp serve to expose MaskShift's own tools to Claude Desktop, an IDE or another agent.
• Measurable. maskshift bench run scores a model on self-checking tasks — pass rate, turns, tokens per solved task — and can switch individual helpers off to show what each one is worth.

How MaskShift differs

Other agent harnesses are strong at what they were built for. This table lists only the things MaskShift adds that those tools do not ship as built-in features.

	MaskShift	Claude Code	Codex CLI	OpenCode	Gemini CLI	Aider
Measures each model with probes and sizes its help to what it can do	✅	—	—	—	—	—
Raises the level of help mid-run when a model keeps stumbling	✅	—	—	—	—	—
Built-in benchmark that switches individual harness helpers off to measure their value	✅	—	—	—	—	—
Token usage split by cause: turns, repairs, verification retries, compaction, hand-offs	✅	—	—	—	—	—
Skill changes promoted only after recorded A/B trials show uplift without regressions	✅	—	—	—	—	—
Memory that cites files by content hash and goes stale when they change	✅	—	—	—	—	—
Full tool use on models with no native tool-calling API	✅	—	—	—	—	—
Live, clickable browser view rendered inside the terminal	✅	—	—	—	—	—
Drives other agent CLIs (Claude Code, Codex, Hermes, OpenCode…) as a team that messages itself, from one interface	✅	—	—	—	—	—

Based on each project's public documentation as of October 2026. "—" means not a built-in, documented feature; plugins, hooks, MCP servers or third-party wrappers may add something similar. The table is deliberately limited to MaskShift's differences — the other tools have strengths of their own, such as IDE and desktop integration, that are not listed here. If a row is out of date, please open an issue.

Install

Requires Node.js 22 or newer and a terminal of at least 80×24 (UTF-8 and truecolor are used when available and degrade cleanly when not). Git and ripgrep are recommended.

npm install -g maskshift
cd ~/Documents && maskshift

Or run it without installing: npx maskshift --workspace ~/Documents.

From source (there is no npm install step, because there is nothing to install):

git clone https://github.com/nafeeur/MaskShift.git
cd MaskShift
./start.sh --workspace ~/Documents      # or ./install.sh to link ~/.local/bin/maskshift

Quick start

Choose a model. The default, ollama:auto, discovers your installed Ollama models and picks the strongest one it finds; cloud providers read their keys from the environment.

ollama pull qwen3:8b                    # a local model
export ANTHROPIC_API_KEY=...            # or OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY
export MASKSHIFT_MODEL=anthropic:<model-id>   # provider:model, e.g. ollama:qwen3:8b

Open the interface in a folder and type a request, or run one task headlessly:

maskshift --workspace ~/Documents
maskshift run "Total the Q3 invoices in ./Invoices by vendor and write q3-by-vendor.xlsx" \
  --workspace ~/Documents --model anthropic:<model-id>

Press ctrl+k for the command palette and f2 for settings. Settings live in ~/.maskshift/config.json. → configuration reference

The interface

maskshift opens a full-screen terminal application, driven equally by keyboard and mouse. Seven views switch with 1–7; ctrl+b toggles the sidebar.

View	Holds
Chat	The conversation and composer — markdown, syntax-highlighted code, coloured diffs and live tool calls
Files	The workspace tree with a preview; images render inline
Capabilities	Every tool, skill, MCP server, plugin in one searchable catalogue
Runtime	A host shell, automations, background processes and browser instances
Browser	A live, clickable view of a running browser tab
Git	Changes, history, branches, stash, checkpoints and worktrees
Fleet	A team of Claude Code, Codex, OpenCode, Hermes and other agents: members, their messages, relays and installed harnesses

Capabilities — see what a run can reach before it uses it	Approvals — review a command before it runs, in balanced or review mode
Files — the workspace tree with a preview	Command palette — every action, searchable

Below 108 columns the sidebar hides itself so the same views work in a narrow split pane. NO_COLOR, MASKSHIFT_COLOR=off and MASKSHIFT_ASCII=1 each produce a clean, aligned fallback, and MASKSHIFT_MOUSE=off hands text selection back to the terminal. → keys and views

Command line

Everything the interface does is also a subcommand, and every subcommand accepts --json:

maskshift run "Draft an agenda for a two-day offsite"          # one headless run, streamed
maskshift automation create weekly --schedule "every 7d" --prompt "Summarize this week's notes"
maskshift tools run web_search '{"query":"node 22 release notes"}'
maskshift model calibrate --model ollama:qwen3:8b               # measure a model, then size help to it
maskshift bench run --model ollama:qwen3:8b                     # score it on the benchmark tasks
maskshift mcp serve                                             # MaskShift as an MCP server
maskshift doctor                                                # environment and provider checks

Global flags: --workspace PATH, --model REF, --config PATH, --json, --no-color. → full command reference

Permissions and safety

MaskShift runs with the authority of your account. The default autonomous mode never prompts, so recovery relies on automatic checkpoints, the audit log and the stop control; balanced asks before high-risk actions (shell execution, installs, destructive operations, outbound actions); review asks before anything that is not read-only. Content from files, web pages and tool results is treated as data, never as instructions. A container limits MaskShift to what is mounted into it. → permissions · security policy

Documentation

Document	Covers
Configuration	Settings, providers, MCP, hooks, automations and data locations
Tools · Skills	The native tool inventory and bundled skills
Interface	Keys, views and the design system
Command line	Every subcommand and flag
Architecture	The agent loop, the adaptive harness, persistence and extension points
Web tasks	Page options, pickers, terminal sign-in, hand-offs and what stays private
Permissions	The three modes, what stays observable and where the limits are
Verification · Release checks	What the automated suite covers

Development

npm run verify      # syntax check + unit/integration tests + end-to-end smoke test
npm run docs        # regenerate the tool and skill inventories
npm run capture     # regenerate docs/screenshots from the real renderer

CONTRIBUTING.md lists what changes are held to. The plugin in examples/plugins/telemetry-pack is a complete worked example, and the bundled plugin-authoring and skill-creator skills cover the rest of the extension surface.

To run the scheduler without an interface, use deploy/maskshift.service (a user-level systemd unit) or the Dockerfile / compose.yaml (docker run -it; mount /workspace and /data).

License

GNU General Public License v3.0.