🌊 MeerAI

Dive deep into your code.

MeerAI (from the German word "Meer" — sea) is an open-source, local-first AI CLI for developers. Operate entirely on your machine with local models, or connect to hosted providers (Meer Managed, OpenRouter, OpenAI, Anthropic, Gemini, DeepSeek, Z.AI, Ollama) and Model Context Protocol servers — all from the terminal.

Overview

MeerAI delivers intelligent assistance inside your terminal — no browser tabs, no forced SaaS lock-in.

• Local-first or cloud-smart — chat with local Ollama models, Meer Managed, or remote APIs (OpenAI, Anthropic, Gemini, OpenRouter, DeepSeek, Z.AI)
• Structured agent — a tool-calling loop with a large toolset and Model Context Protocol integration
• Custom terminal UI — a differential renderer with live tool timelines, diff previews, approval overlays, and a slash-command palette; native terminal scrollback and text selection/copy
• Headless modes — meer run / meer --print stream plain-text or newline-delimited-JSON events for scripting, CI, and editor/cloud integrations
• Workspace-native — read/edit files, run commands and tests, manage git, scaffold projects, run semantic search
• Private by default — nothing leaves your machine unless you choose a remote provider
• Layered & extensible — a clean package split (core → ai → agent → coding-agent) keeps the generic agent separable from the coding assistant

Feature Highlights

| Area | Capabilities | | ---- | ------------ | | Chat (meer) | Interactive TUI with streaming responses, plan tracking (restored on resume), tool timeline, diff previews | | Headless (meer run, meer --print) | Non-interactive runs that stream text or JSON events — for CI, scripts, and integrations | | One-shot Q&A (meer ask) | Repo-aware answers with optional memory and slash-command access | | Reviews & commits | meer review, meer commit-msg with conventional-commit support | | Toolbox | 60+ structured tools: read/write/edit, git, run_command, semantic_search, scaffold_project, generate_tests, security_scan, and more | | Slash commands | Built-in palette (/model, /setup, /history, /plan, …) plus custom commands | | Sessions & memory | Resumable sessions (--resume, --fork), recent-context loading, per-command memory control | | MCP support | Auto-load Model Context Protocol servers via ~/.meer/mcp.yaml, with lazy reconnect on server restart |

Quick Start

Install (recommended)

npm install -g meerai

Requires Node.js 20+. Optional: Ollama for local models.

Configure a provider

meer setup

Select Ollama, Meer Managed, or another remote provider. Profiles are stored in ~/.meer/config.yaml. For Meer Managed, run meer login or set MEER_API_KEY.

Launch

meer

Usage

Interactive coding

meer

• Live tool timeline and diff previews.
• Edit/command approvals appear as inline overlays (per the project trust mode).
• Slash commands (/plan, /history, /config, /remember, …) available inline.
• ? shows shortcuts. Scroll and copy use your terminal natively.

Headless / scripting

# Plain-text, non-interactive run (auto-approves safe actions)
meer run --yes "add a TODO to README.md explaining the project"

# Newline-delimited JSON event stream (for CI / integrations)
meer run --json --yes "fix the failing tests"

# Top-level shorthand for a one-shot prompt
meer --print "summarize the recent changes"
meer --print "summarize the recent changes" --json

Repo-aware Q&A

meer ask "Explain the authentication flow"
meer ask --plan "Draft a migration checklist to Express 5"

Code review & commits

meer review src/modules/payments
git add .
meer commit-msg --conventional

Sessions & memory

meer --resume                 # resume the latest session (restores an unfinished plan)
meer --fork <session>         # branch a saved session into a new one
meer memory stats
meer ask --no-memory "Refactor this script"

Configuration

~/.meer/config.yaml

profile: managed

profiles:
  managed:
    providerType: meer
    model: meer:sonnet
    maxIterations: 6
  ollama-mistral:
    providerType: ollama
    provider:
      name: ollama
      options:
        host: http://localhost:11434
    model: mistral:7b-instruct
    contextEmbedding:
      enabled: true
      maxFileSize: 200_000
  openrouter-claude:
    providerType: openrouter
    provider:
      name: openrouter
      options:
        apiKey: ${OPENROUTER_API_KEY}
    model: openrouter/anthropic/claude-3.5-sonnet

Switch profiles per invocation with meer --profile <name> (or DEVAI_PROFILE=<name>):

meer --profile ollama-mistral review src
meer --profile openrouter-claude ask "Generate tests for the CLI"

Memory Layout

| Type | Location | Description | | ---------------- | ----------------------- | ---------------------------------- | | Conversations | ~/.meer/sessions/ | Rolling session history (JSONL) | | Long-term memory | ~/.meer/longterm/ | Facts, preferences, embeddings | | Config | ~/.meer/config.yaml | Provider profiles & agent defaults | | MCP servers | ~/.meer/mcp.yaml | Configured Model Context Protocol servers |

Skills

Agent Skills are folders with a SKILL.md (name, description, instructions) that the agent can discover and invoke via /skills or the load_skill tool. meer loads skills from:

• Project: ./.meer/skills
• Global: ~/.meer/skills

Skills interop (Claude Code & Codex)

meer also loads Agent Skills from Claude Code and Codex directories, so skills you already have work without copying them:

• Global: ~/.claude/skills, ~/.codex/skills
• Project: ./.claude/skills, ./.codex/skills (loaded only when the project is trusted)

meer's own .meer/skills always take precedence on a name collision. Disable interop or a specific source in ~/.meer/config.yaml:

skills:
  interop:
    enabled: true   # set false to turn off all interop
    claude: true
    codex: true

/skills shows each skill's origin, e.g. - critique [claude/global].

Hooks

meer can run your own shell commands at defined lifecycle points. Define them in ~/.meer/hooks.yaml (global) or ./.meer/hooks.yaml (project — loaded only when the project is trusted). No file means no hooks.

hooks:
  PreToolUse:
    - matcher: "edit_file|run_command"   # regex on tool name; omit = all tools
      command: "./scripts/guard.sh"
      timeoutMs: 30000                    # optional, default 30s
  UserPromptSubmit:
    - command: "node ./scripts/inject-context.mjs"

Events: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, PreCompact. Each hook receives a JSON event on stdin ({ "event", "cwd", "sessionId", … }) and may reply on stdout:

• { "decision": "block", "reason": "…" } — blocks the action (PreToolUse and UserPromptSubmit only).
• { "additionalContext": "…" } — injects context (SessionStart, UserPromptSubmit, PostToolUse).

Exit codes: 0 = success (stdout honored), 2 = block (reason from stderr), any other = non-blocking error (logged, execution continues). Hooks run in the project directory with your environment; a hook failure never crashes meer.

Run /hooks to list the hooks meer loaded.

Architecture

MeerAI is a pnpm workspace monorepo with an enforced dependency layering, so the generic agent is cleanly separable from the coding assistant built on top of it:

packages/
  @meer-ai/core           HTTP (fetch), auth/OAuth — the base layer, LLM-agnostic
  @meer-ai/ai             LLM I/O: message model, Provider contract, providers, attachments
  @meer-ai/agent          generic agent loop + orchestration types (no tools, no UI, no provider)
  @meer-ai/tui            vendored differential terminal renderer
  @meer-ai/coding-agent   the assistant: tools, slash commands, config, trust, skills, MCP,
                          and the interactive TUI app — owns the `meer` bin
meerai (root)             thin launcher → @meer-ai/coding-agent

Dependency rule (lower may not import higher): core ← ai ← agent ← coding-agent; tui is independent. See docs/ARCHITECTURE.md for the full design.

Extending MeerAI

• New tool — add it under packages/coding-agent/src/tools/, wrap it in packages/coding-agent/src/agent/tools/agent.ts.
• New provider — implement the Provider interface in packages/ai/src/providers/ and wire it through packages/coding-agent/src/config.ts.
• MCP server — add it to ~/.meer/mcp.yaml; the agent autoloads it.
• New CLI command — create a file in packages/coding-agent/src/commands/ and register it in packages/coding-agent/src/cli.ts.

Development

git clone https://github.com/meer-ai/meer.git
cd meer
pnpm install
pnpm run build      # build all packages in dependency order
pnpm run check      # typecheck the whole program
pnpm test           # run the verification suite (parallel)
pnpm run dev        # run the CLI from source (tsx, no build)

Releases are automated: pnpm run release bumps all packages lockstep, runs preflight, tags, and pushes — GitHub Actions then publishes every package to npm with provenance and cuts a GitHub Release.

Contributing

We welcome contributions, bug reports, and ideas!

1. Review the Code of Conduct and Contributing Guide.
2. Fork the repo and create a branch: git checkout -b feat/awesome-thing.
3. Run pnpm run build && pnpm run check && pnpm test before submitting.
4. Open a PR with the provided template.

Issue templates live under .github/ISSUE_TEMPLATE/. The Security Policy explains how to report vulnerabilities responsibly.

License

MeerAI is open-source under the MIT License.

🌊 "A sea of models, one interface."