Skip to content
/
Tier B A8 Cross-runtime harness

Marmot

marmot · marmot-sh/marmot · ★ 0 · last commit 2026-05-19

Primitive shape 1 total
Skills 1
00

Summary

Marmot — Summary

Marmot is an open-source (MIT) shell-native CLI that gives agents and scripts a single, pipeable interface to AI generation (text, image, video, speech, transcription), web retrieval (search, scrape, answer, map, crawl, research), and data enrichment (enrich, lookup, verify) across 25+ providers — routing each call to the cheapest/fastest model appropriate for the task without burdening the main agent's context window. The core philosophy is "one shape, many providers": a developer or agent learns one verb set (marmot "prompt", marmot search, marmot enrich) and gains access to OpenRouter, Anthropic, OpenAI, Ollama, Brave, Exa, Tavily, Apollo, and more through consistent flags and deterministic JSON output. Marmot ships an installable agent skill (SKILL.md) for Claude Code, Codex, OpenCode, and similar harnesses, teaching the agent when and how to delegate external calls to the CLI rather than consuming the main context window. The tool supports sessions (persistent chat history across invocations), presets (saved flag bundles), named pipelines (multi-stage workflows), and an optional response cache. Compared to the 11 seeds, Marmot occupies a unique "external-provider delegation" niche — it is not a spec framework or workflow methodology but a multi-provider abstraction layer for agent-external calls, with the agent skill as its integration surface with tools like Claude Code.

01

Overview

Marmot — Overview

Origin

Published by the marmot-sh organization. The marmot.sh website presents it as "shell-native AI and web data" — "One CLI for your agent and scripts for AI, search, scraping, and enrichment."

Philosophy

From the README:

"Claude Code, Codex, OpenCode, OpenClaw, Hermes, and similar agents are strongest when their context stays focused. But agent workflows still need web search, scraping, enrichment data, retries, caching, and small helper prompts."

"Instead of teaching every agent a dozen provider CLIs, or spinning up subagents for routine lookups, you give them one interface for AI providers, search APIs, scraping tools, and enrichment services."

"It also lets each task use the right model. A quick classification, a local or private prompt, and a long synthesis do not need to run through the same model your main agent or subagent is configured with."

Design Principles

  1. One shape, many providers — consistent flags across AI, web, and data provider categories
  2. Agent-friendly output — plain text by default for piping; --json for structured parsing
  3. Composable — built around shell pipes (marmot search ... | marmot "summarize")
  4. Predictable — stable exit codes, stderr/stdout separation, deterministic JSON envelopes
  5. Opt-in skill — the agent skill explicitly requires the user to invoke it or grant permission; it does not activate by default

Invocation Gate (from SKILL.md)

The skill includes an explicit invocation gate: "Default: keep using the agent's native capabilities. Switch to marmot only when one of these holds: The user invokes the skill directly / The user names marmot / An active marmot pipeline is in flight / The user has granted ongoing session permission."

This opt-in design reflects an anti-pattern awareness: "When writing scripts whose purpose maps to marmot's wheelhouse, ask whether the script should use marmot — don't decide for the user."

Multi-Provider Strategy

Marmot routes AI calls to: OpenRouter, Anthropic, OpenAI, Vercel AI Gateway, Cloudflare Workers AI, Ollama. Web calls to: Brave, Exa, Firecrawl, Parallel, Tavily, ScrapeOps, ScraperAPI, ScrapingBee, Zyte. Data calls to: Apollo, Hunter, PDL (People Data Labs), Tomba, Bouncer, Datagma, ZeroBounce, Kickbox.

02

Architecture

Marmot — Architecture

Distribution

  • Type: npm package (global install)
  • Binary: marmot (scoped as @marmot-sh/cli, also available as marmot-sh)
  • Version analyzed: 0.11.0+
  • Runtime required: Node.js >= 20
  • Language: TypeScript (monorepo with Turborepo)
  • GitHub repo: marmot-sh/marmot (separate from the marmot.sh website)

Install Methods

npm install -g @marmot-sh/cli
# or shorter alias:
npm install -g marmot-sh

Monorepo Structure

marmot/
├── packages/
│   ├── core/              # Core CLI runtime
│   ├── anthropic/         # Anthropic provider adapter
│   ├── openai/            # OpenAI provider adapter
│   ├── openrouter/        # OpenRouter adapter
│   ├── ollama/            # Ollama adapter
│   ├── vercel/            # Vercel AI Gateway
│   ├── cloudflare/        # Cloudflare Workers AI
│   ├── brave/             # Brave Search
│   ├── exa/               # Exa search
│   ├── firecrawl/         # Firecrawl scraping
│   ├── parallel/          # Parallel web
│   ├── tavily/            # Tavily search
│   ├── scrapeops/         # ScrapeOps proxy
│   ├── scraperapi/        # ScraperAPI proxy
│   ├── scrapingbee/       # ScrapingBee proxy
│   ├── zyte/              # Zyte scraping
│   ├── apollo/            # Apollo enrichment
│   ├── hunter/            # Hunter email
│   ├── pdl/               # People Data Labs
│   ├── tomba/             # Tomba email
│   ├── bouncer/           # Bouncer validation
│   ├── datagma/           # Datagma enrichment
│   ├── zerobounce/        # ZeroBounce validation
│   ├── kickbox/           # Kickbox validation
│   └── ui/                # Dashboard UI
├── apps/                  # Applications
├── skills/
│   └── marmot/
│       └── SKILL.md       # Agent skill for Claude Code/Codex/OpenCode
├── .claude-plugin/
│   └── marketplace.json
├── scripts/
└── pnpm-workspace.yaml

Config Storage

~/.marmot/config.json — default providers per verb, enabled/disabled providers, custom env var names, response cache settings, presets, pipeline definitions.

Usage Log

~/.marmot/usage/<UTC-DATE>.jsonl — privacy-safe per-call log for marmot usage analytics.

Target AI Tools

  • Claude Code (primary — ships Claude Code plugin skill)
  • OpenCode
  • Codex
  • Hermes
  • OpenClaw
  • Any shell-scriptable agent

Required Setup

export OPENROUTER_API_KEY=sk-or-v1-...  # (or any supported provider key)
marmot setup   # interactive wizard
03

Components

Marmot — Components

CLI Verbs (Commands)

AI Generation

Verb Purpose
marmot <prompt> Text generation (default verb)
marmot run <prompt> Explicit text generation
marmot image <prompt> Image generation
marmot video <prompt> Video generation (async)
marmot transcribe <audio> Speech-to-text
marmot speak <text> Text-to-speech

Web Retrieval

Verb Purpose
marmot search <query> Web search
marmot scrape <url...> URL(s) to cleaned markdown
marmot fetch <url...> Raw HTML via proxy
marmot answer <query> Answer with citations
marmot map <url> List URLs on a domain
marmot crawl <url> Walk domain, return pages
marmot research <query> Async deep research
marmot findall <objective> Async entity list builder
marmot get <id> Poll async task

Data Enrichment

Verb Purpose
marmot enrich --type person|org Identifier → full record
marmot lookup --type person|org|email Filters → entity list
marmot verify <email> Email deliverability

Operations

Verb Purpose
marmot setup Interactive setup wizard
marmot config show/set/unset/path Config management
marmot providers list Inspect available providers
marmot cache stats/clear/refresh Cache management
marmot preset create/list/get/delete/rename Preset management
marmot @<name> ... Use a preset
marmot session create/use/show/export Session management
marmot pipeline create/update/list/run Named pipeline workflows
marmot tasks list/show Async task management
marmot usage Usage analytics from log
marmot doctor [--fix] Health check
marmot models --search Model discovery

Agent Skill

  • File: skills/marmot/SKILL.md
  • Format: Plain markdown (skill-md)
  • Install: npx skills add https://github.com/marmot-sh/marmot --skill marmot or via marmot setup
  • Purpose: Teaches agents when to use marmot, the verb surface, provider matrix, output formats, and invocation gate constraints

Providers (25+)

AI: OpenRouter, Anthropic, OpenAI, Vercel AI Gateway, Cloudflare Workers AI, Ollama Web: Brave, Exa, Firecrawl, Parallel, Tavily, ScrapeOps, ScraperAPI, ScrapingBee, Zyte Data: Apollo, Hunter, People Data Labs, Tomba, Bouncer, Datagma, ZeroBounce, Kickbox

Presets

Named invocation bundles:

marmot preset create haiku --mode text \
  --provider anthropic --model claude-haiku-4-5-20251001 \
  --system "Reply only with a 5-7-5 haiku, no prose."
marmot @haiku "the sea at dusk"

Pipelines

Named multi-stage shell workflows (v0.9.0+):

marmot pipeline create pdf-brief \
  "scrape {url} | run 'summarize in 5 bullets' | speak"

Sessions

Persistent chat history across invocations:

marmot session create research --mode chat
marmot session use research
05

Prompts

Marmot — Prompts

Excerpt 1 — SKILL.md Invocation Gate (Behavioral Instruction)

From skills/marmot/SKILL.md:

## Invocation gate

Marmot is opt-in. Default: keep using the agent's native capabilities. Switch to
marmot only when one of these holds:

- The user invokes the skill directly.
- The user names marmot in the request ("use marmot to scrape…").
- An active marmot pipeline is in flight in this conversation.
- The user has granted ongoing session permission.

On the first marmot call in a session, confirm the verb + provider before
dialing — these calls cost real money. Subsequent calls within the user's stated
scope proceed without re-asking.

If a request would expand scope (new verb category, materially higher cost —
e.g. switching to video), check before continuing.

Technique: Cost-aware permission gate. The skill explicitly models API call cost as a reason to require user consent before execution — unusual among skills, which typically aim for frictionless activation. This is a defensive skill pattern that prevents unexpected bill accumulation.

Excerpt 2 — SKILL.md Provider Discovery Bootstrap

From skills/marmot/SKILL.md:

## Before invoking any verb

One command does the whole bootstrap:

```bash
marmot config show --json

The envelope returns:

  • marmotVersion — installed CLI version.
  • readyProviders — alphabetically sorted slugs of every provider that is callable now.
  • defaults.<verb> — which provider (and model) backs each verb.
  • providers.<slug> — per-provider config.
  • presets — saved invocation bundles.
  • cache.totals and cache.providers — what's cached.

Use this to decide whether to pass --provider, whether the cache will short-circuit your call, and which presets are pre-tuned for the task.


**Technique**: Config-first discovery. The skill tells the agent to query its own config before making any external calls — a "read before act" pattern that avoids failed calls due to missing keys or unavailable providers.

## Excerpt 3 — SKILL.md Version Compatibility Guard

From `skills/marmot/SKILL.md`:

```markdown
Verbs and flags this skill describes target marmot 0.11.0 and later. Earlier
versions may not have `marmot video`, sampling controls (`--temperature`,
`--reasoning`, `--provider-option`), stdin image sniffing...

[extensive version compatibility notes across 0.6.0, 0.7.0, 0.8.0, 0.9.0, 0.10.0, 0.11.0]

Suggest an upgrade if `marmotVersion` is below 0.11.0.

Technique: Embedded compatibility matrix. Rather than failing silently on old versions, the skill instructs the agent to check version and suggest upgrades when features are unavailable — a reliability pattern for evolving CLIs used by agents.

09

Uniqueness

Marmot — Uniqueness

differs_from_seeds

Marmot has no direct analog among the 11 seeds. It occupies a distinct layer: not a workflow framework, not a spec methodology, not a context packager, but a multi-provider delegation CLI that allows agents to offload external data collection (web search, scraping, enrichment, AI generation) without consuming the main agent's context window. The closest conceptual parallel is taskmaster-ai's MCP integration pattern (external tool server the agent calls), but Marmot uses a shell CLI + agent skill rather than an MCP server. Unlike superpowers or BMAD-METHOD (which govern agent behavior), Marmot is a resource-access tool with an opt-in skill. Unlike codesight (context pre-packager), Marmot is active during agent sessions rather than a pre-session setup tool. Among the 11 seeds, agent-os is most philosophically adjacent in that both are "tools the agent uses," but agent-os is a project convention scaffold while Marmot is an API aggregator.

Positioning

  • Primary differentiator: The only tool in the batch (and likely the broader catalog) that provides a unified, pipeable CLI interface to 25+ AI + web + data providers in a single binary designed specifically for shell-scriptable agent delegation.
  • Secondary differentiator: Named pipelines (multi-stage workflows), preset bundles, and session persistence make Marmot a composable workflow primitive rather than just a one-shot tool.
  • Target user: Developers building agent workflows that need external data (search, scraping, enrichment) without integrating 25+ individual provider SDKs.

Observable Failure Modes

  1. Provider availability fragility: If a provider's API changes or key expires, calls fail; marmot doctor helps diagnose but doesn't auto-remediate.
  2. Cost gate friction: The SKILL.md invocation gate (confirm before first call) may slow agent workflows where speed is critical — by design, but a real tradeoff.
  3. Context window for SKILL.md: The SKILL.md is very large (detailed verb surface, compatibility matrix, invocation rules), potentially consuming significant tokens when loaded.
  4. Session window overflow: Sessions accumulate history until exported/cleared; agents must monitor window usage to avoid context overflow on long sessions.
  5. Early-stage public repo: marmot-sh/marmot has 0 stars (repository is newer/separate from the marmot.sh product), suggesting the open-source component is early-stage while the product itself is active.
04

Workflow

Marmot — Workflow

Execution Patterns

Marmot supports multiple execution patterns:

1. One-Shot Shell Command

marmot "tell me a joke"                    # AI generation
marmot search "news about apple"           # Web search
marmot enrich --type person --email x@y.z  # Data enrichment

2. Shell Pipe Composition

# Search → summarize
marmot search "openrouter pricing" | marmot "summarize for slack"

# Scrape → translate
marmot scrape https://example.com | marmot "translate to French"

# Git diff → commit message → clipboard
git diff | marmot --stream "commit message under 60 chars" | pbcopy

# CI pipeline: PR diff → description
gh pr diff $PR | marmot "write a 3-bullet PR description"

3. Preset Invocation

marmot @haiku "the sea at dusk"
marmot @security-review --file audit.md

4. Session Workflow (Stateful)

marmot session create research --mode chat
marmot session use research
marmot "What are leading vector databases in 2026?"
marmot "Of those, which support hybrid search?"
marmot "Pick one and write a setup script"
marmot session export research

5. Agent Delegation Pattern (via SKILL.md)

The agent calls marmot config show --json first to discover ready providers and defaults, then delegates external calls:

# Agent: "I need to search the web about X" → delegates to:
marmot search "X" | marmot "summarize key points"

Phase-to-Artifact Map

Phase Artifact
Config setup ~/.marmot/config.json
API call stdout (plain text or JSON)
Usage tracking ~/.marmot/usage/<date>.jsonl
Cache hit ~/.marmot/cache/
Session ~/.marmot/sessions/<id>/

Approval Gates

One explicit gate in the SKILL.md invocation gate:

  • "On the first marmot call in a session, confirm the verb + provider before dialing — these calls cost real money."
  • Scope expansion check: "If a request would expand scope (new verb category, materially higher cost — e.g. switching to video), check before continuing."

Async Task Management

Long-running verbs (research, findall, video, crawl):

marmot research "AI database trends" --async
# → task ID returned
marmot get <id>          # poll status
marmot tasks list        # see all pending tasks
06

Memory Context

Marmot — Memory & Context

State Storage

Marmot maintains state in ~/.marmot/:

File/Dir Type Content
~/.marmot/config.json JSON config Provider settings, defaults, presets, pipelines
~/.marmot/usage/<date>.jsonl Append-only log Per-call log (privacy-safe)
~/.marmot/cache/<provider>/ Response cache Cached API responses (opt-in per provider)
~/.marmot/sessions/<id>/ Session store Persistent chat history per named session

Session Persistence

Sessions allow stateful multi-turn conversations across separate marmot invocations:

marmot session create research --mode chat
marmot session use research
# subsequent marmot calls thread through session history
marmot session export research   # export as jsonl or markdown
marmot session show research     # totals, message count, window usage

Context Window Management

The SKILL.md includes explicit guidance on context window usage: "session show research" reports window usage — the fraction of the model's context window consumed by session history — allowing agents to decide when to clear or export a session.

Cache

Optional response cache per provider. When enabled, repeat calls with identical inputs return cached responses:

marmot cache stats      # see cache sizes per provider
marmot cache clear      # clear all caches
marmot cache refresh    # force re-fetch cached entries

Context-Saving Design

Marmot's core context preservation mechanism is delegation — by executing external calls (search, scrape, enrichment) as separate marmot invocations returning compact outputs, the main agent's context window is not burdened with raw provider API responses. This is the architectural basis for the "agents are strongest when their context stays focused" philosophy.

Cross-Session Handoff

Supported via marmot session export research — sessions can be exported as JSONL or markdown for archival or handoff.

07

Orchestration

Marmot — Orchestration

Multi-Agent Pattern

Marmot enables a delegation pattern — the main agent delegates external calls to the marmot CLI rather than making API calls directly or spawning subagents. Each marmot call is an isolated tool invocation, not a persistent subagent.

Orchestration Pattern

none at the Marmot level — Marmot is a tool used by agents, not an orchestrator of agents. However, it enables sequential and parallel shell pipelines within scripts.

Pipeline Support (v0.9.0+)

Named multi-stage workflows:

marmot pipeline create pdf-brief "scrape {url} | run 'summarize in 5 bullets' | speak"
marmot pipeline run pdf-brief --url https://example.com/paper.pdf

This is sequential pipeline orchestration at the shell level, not multi-agent coordination.

Execution Mode

interactive-loop for sessions and one-shot for individual verb calls.

Isolation Mechanism

none — each marmot call is a subprocess. No sandboxing.

Multi-Model Usage

Yes — Marmot explicitly supports per-call model selection:

marmot --provider anthropic --model claude-opus-4-5 "complex analysis"
marmot --provider openrouter --model meta-llama/llama-3-70b "quick task"
marmot @haiku "haiku prompt"   # preset with specific model

Different tasks can route to different providers and models within the same agent session.

Model Role Mapping

Use case Recommended pattern
Quick classification Fast/cheap model (e.g. haiku)
Long synthesis Stronger model (e.g. claude-opus)
Local/private Ollama
Web search Brave/Exa/Tavily provider
Data enrichment Apollo/PDL/Hunter provider

Consensus Mechanism

None.

Prompt Chaining

Yes — shell pipes create prompt chains:

marmot search "topic" | marmot "summarize" | marmot "translate to Spanish"

Cross-Tool Portability

High — plain text/JSON stdout works with any shell-scriptable agent. The agent skill specifically supports Claude Code, Codex, OpenCode, Hermes, and OpenClaw.

08

Ui Cli Surface

Marmot — UI & CLI Surface

CLI Binary

  • Binary name: marmot
  • Is thin wrapper: No — full runtime with provider adapters, caching, session management
  • Install: npm install -g @marmot-sh/cli or npm install -g marmot-sh

Major verb groups:

  • AI: run, image, video, transcribe, speak
  • Web: search, scrape, fetch, answer, map, crawl, research, findall
  • Data: enrich, lookup, verify
  • Ops: setup, config, providers, cache, preset, session, pipeline, tasks, usage, doctor, models

Total unique subcommands: ~35+

Local UI

  • Exists: Yes — packages/ui is present in the monorepo (dashboard)
  • Type: web-dashboard (inferred from package structure)
  • Port: unknown
  • Tech stack: likely React (TypeScript monorepo, Turborepo)
  • Features: unknown details; website mentions usage analytics dashboard at marmot.sh

MCP Server

None shipped in the repository — Marmot uses a CLI + agent skill pattern instead of an MCP server.

IDE Integration

None native — the agent skill is the integration surface with AI tools (installed via marmot setup or npx skills add).

Observability

  • marmot usage — summarizes call log: totals, breakdowns, cost per provider, errors
  • marmot usage --watch — live streaming view (v0.6.0+)
  • marmot doctor [--fix] — health check: CLI version, config, providers, logging state, disk usage
  • ~/.marmot/usage/<UTC-DATE>.jsonl — per-call privacy-safe log

Global Flags

--json              Force structured JSON envelope output
--text              Force plain text (where applicable)
--stream            Stream output to stdout
--quiet / -q        Full silence (write to file only)
--provider <slug>   Override default provider
--model <id>        Override model
--dry-run           Preview without executing
-o <path>           Write output to file

Related frameworks

same archetype · same primary tool · same memory type

claude-mem (thedotmack) ★ 78k
A8 Cross-runtime harness

Background worker service captures every tool call as an observation, AI-compresses sessions, and auto-injects relevant past…

pi (badlogic/earendil) ★ 55k
A8 Cross-runtime harness

A minimal, hackable, multi-provider terminal coding agent that adapts to your workflows via npm-installable TypeScript Extensions…

Agent Skills (Addy Osmani) ★ 46k
A8 Cross-runtime harness

Encodes senior-engineer software development lifecycle as 23 auto-routed skills and 7 slash commands for any AI coding agent.

wshobson/agents Plugin Marketplace ★ 36k
A8 Cross-runtime harness

Single Markdown source for 83 domain-specialized plugins that auto-generates idiomatic artifacts for five AI coding harnesses.

TabbyML/Tabby ★ 34k
A8 Cross-runtime harness

Self-hosted AI coding assistant server (alternative to GitHub Copilot) with admin dashboard, RAG-based completions, and multi-IDE…

Compound Engineering ★ 17k
A8 Cross-runtime harness

Make each unit of engineering work compound into easier future work via brainstorm→plan→execute→review→learn cycles.