@meer-ai/core

---

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.

---