documentation

marshall is a terminal coding agent. It plans, reads, edits and runs your project, while keeping you in control of every mutation.

install & first run

Install the CLI globally from npm, then run marshall from the workspace you want it to change. Node.js 22 or newer is required:

npm install --global @agentionai/marshall-cli
cd /path/to/project
marshall

Use marshall --workspace /path/to/project to select a project explicitly from any directory. Local providers such as llama.cpp and Ollama need no account or API key. Hosted providers can be configured when you need them.

configuration

Configuration has a deliberate security boundary:

• ~/.config/marshall/config.json is private, mode 0600, and may contain credentials. Honours $XDG_CONFIG_HOME.
• <workspace>/.marshall/config.json is project configuration and may be committed. It must never contain tokens, API keys or other secrets.

The project file is merged on top of the global one, key by key, so a repo can pin its model or provider without repeating anything else. An apiKey in the project file is ignored, wherever it appears, and marshall says so at startup. That file gets committed, and a key in it leaks to everyone who clones the repo.

API keys

Keys are resolved in this order, and the first one that exists wins:

1. the --api-key flag;
2. the key stored for that provider in the global config, which is what /model writes when you complete the setup wizard;
3. the provider's environment variable;
4. for the claude provider only, the OAuth token from marshall login, stored in ~/.marshall/credentials.json.

The global config holds one key per provider, so switching between providers keeps each one's key and host. Marshall loads .env files before resolving anything: the workspace root first, then every directory from where you ran it up to the git root. Real shell variables beat .env.

Note: a key saved in the global config takes precedence over an environment variable. If you want a per-project key in .env to apply, that provider must not already have a key saved globally. Keeping one provider for global work and another for the project is the simplest way to run two different accounts.

settings

Non-secret runtime settings live under a versioned settings key in either file, and marshall is the only thing that needs to write them:

{
  "settings": {
    "version": 1,
    "mode": "light",
    "safetyLevel": 3,
    "safetyAgent": { "provider": "openrouter", "model": "..." }
  }
}

/runtime light pins the mode for the current workspace; /runtime light --global pins it for every workspace, and a workspace that pins its own still wins. /safety records levels 2 and 3 the same way, with the judge's provider and model but never its key. Level 1 (yolo) is never written. A settings block from a version marshall does not recognise is ignored rather than half-read, and anything invalid is reported at startup instead of silently changing what you configured.

privacy

--private runs a session that writes nothing to disk beyond the workspace files you actually asked it to edit: no session log, no history/reasoning/http trace, no scratchpad notes, and no writes to config.json — a setting changed mid-session (model, safety level, …) simply isn't saved. It's session-only by design: there's no /private command and nothing persists it, so it can't quietly outlive the run it was asked for. The header shows private on while it's active.

On OpenRouter, requests are routed with provider.dataCollection: deny, restricting routing to upstreams that don't retain the prompt. llama.cpp and Ollama need no such flag, since nothing leaves the machine. Every other provider has no equivalent request-level option, so marshall warns once, at startup, naming whichever provider isn't enforced rather than assuming the same guarantee applies everywhere.

models & tiering

Marshall supports local and hosted providers. The deep model handles coding, planning and review; the fast model reads files and summarises context. Use /model to choose them, or /model off to use one model for everything.

slash commands

Keyboard: Esc interrupts and enters steering mode; Ctrl-R toggles live reasoning; Ctrl-V attaches a clipboard image; Ctrl-C interrupts or quits; press Esc twice or Ctrl-C twice to force quit.

tools & approval

The agent can inspect files, edit files, run commands, delegate context work and manage background jobs. Operations that can change your project or execute commands pass through the approval gate. Review the command, caller and proposed input before allowing it. Read-only inspection does not mutate files.

background jobs

Long-running shell commands can continue in the background. Use /jobs to see them and /jobs kill <id> or /jobs kill all to stop them. Completed jobs can resume the conversation with their output.

MCP

Use /mcp add to connect an HTTP MCP server, /mcp to list its tools, and /mcp remove <name> or /mcp reconnect <name> to manage it. Project-declared servers may use a URL, but authentication headers are taken only from trusted global configuration.

plugins

Plugins are locally-spawned tool servers marshall manages for you: /plugins add <name> starts one and registers it as an MCP server automatically, /plugins (or /plugins list) shows what's configured and its status, and /plugins disable <name> stops it. A plugin enabled once stays configured, and comes back up on its own the next time you start marshall in that workspace.

browser control

Download the browser extension ZIP — for Chrome and Edge, no source checkout or build needed. You can download before starting Marshall; pairing requires the browser plugin to be running.

1. Extract the ZIP into a permanent folder. Keep it after installation: the browser loads the extension from this folder.
2. Open chrome://extensions in Chrome or edge://extensions in Edge and enable Developer mode.
3. Click Load unpacked and select the extracted folder containing manifest.json, not the ZIP itself.
4. Run /plugins add browser in Marshall. Pin Marshall Browser Control, open its toolbar popup, paste the pairing token from your terminal, and click Save & connect. Check that it says connected.

Keep your pairing token private; the website never needs it. Already installed? No reinstall is needed when re-enabling the plugin. The ZIP above tracks the latest site deployment; the local setup page described below serves the ZIP bundled with the plugin you have installed.

/plugins add browser starts a local server and prints a one-time pairing token. Open the local setup link it prints (http://127.0.0.1:<selected-port>/setup) for an extension download button and guided Chrome/Edge installation steps. Keep Marshall running, extract the ZIP into a permanent folder, and use Developer mode → Load unpacked on your browser's extensions page. Pin the extension, open its toolbar popup, paste the token, and click Save & connect. Once paired, the coder can navigate, click, type, press keys, take screenshots and read pages in your actual browser — useful for driving a dev server, checking a live page's console output, or verifying a UI change visually instead of guessing from source.

Marshall prefers the saved port (8712 initially) and automatically chooses a free loopback port if it is occupied by an older or unrelated server. Use the setup link it prints. Set the popup's Advanced: bridge URL to the printed ws://127.0.0.1:<selected-port>/bridge URL and click Save & connect; update this URL after a port change even if already paired. The pairing token is preserved, and other servers are left running.

A tab marshall is controlling shows a pulsing border and badge, and is grouped in the tab strip, so it's always obvious when automation is active. Reading a page defaults to a structured markdown form — headings, lists, and links with their destination attached — cheaper than raw HTML while still letting the coder act on what it reads.

named agents

/team add opens a wizard that defines a reusable agent: a name, a provider and model, an optional pinned toolset (readonly, edit or full) and a one-line description. /team lists what's configured; /team remove <name> forgets one. The coder can then spawn a named agent instead of a bare tier — a pinned toolset always wins over whatever the coder asks for, so a "tester" agent stays read-only no matter what it's told. Definitions are saved to the project config; credentials are resolved from the same global provider config /model uses, so nothing secret ends up in a committed file.

project memory

AGENTS.md contains durable instructions and project context. Use /memory to inspect the memory visible to the agent. Keep credentials out of it and out of committed project configuration.

benchmarks & evidence

These comparisons are snapshots of specific tasks and configurations, not a universal ranking. Each result used a deterministic verifier rather than an LLM judge. Times and model behaviour can drift by provider and date; the small trial counts below are shown so the claims are not mistaken for broad estimates.

Marshall and Codex on Terminal-Bench

On 10 September 2026, Codex CLI and Marshall ran fix-git and openssl-selfsigned-cert with the same gpt-5.6-luna model, the same ChatGPT Plus account and one attempt per task. Both passed 2/2. Marshall reported 119,224 input tokens, 88,064 cache tokens and 3,955 output tokens; Codex reported 318,778 input tokens, 294,144 cache tokens and 6,259 output tokens. That is 63% fewer reported input tokens for Marshall in this two-task run. Marshall's subscription route did not report a dollar cost, so no cost comparison is claimed.

Marshall and pi on a code migration

A 28-file JavaScript fixture required migrating a deprecated logger and passing all 122 tests. With GPT-5.6 Luna, Marshall's luna-shell-edit configuration passed 3/3 with 5.7 tool calls on average and a 32.4-second median. pi passed 4/4 with 14.8 calls and a 31.1-second median. Marshall therefore used 62% fewer calls in this cell, but was not meaningfully faster. pi led the GLM-5.3 Flash cell: 7 calls and 77.7 seconds versus Marshall's 10 calls and 126.1 seconds.

Prompt caching through OpenRouter

In three consecutive live API turns with an identical 3,746-token prefix, the first cache-writing turn cost $0.00955. The two cache-reading turns cost $0.00096 and $0.00098 — about 90% less after the first turn for this session pattern. This measures a saving in Marshall's OpenRouter path, not an advantage over other harnesses.

Read the benchmark fixtures and runner, the Codex comparison configuration, and the dated competitive findings. The benchmark suite records pass rate, time, token usage, cost and tool calls where each harness exposes them.

troubleshooting

Context window full

Start a fresh task or use /clear. Reduce unnecessary context and use the fast tier for file-reading work.

Local server unreachable

Check that llama.cpp or Ollama is running, its host and port are correct, and the selected model is loaded.

Where are logs?

Session logs are stored under .marshall/logs/session.log in the workspace — unless the session was started with --private, which writes none. See privacy.