mars

Mars is a package manager for agent directories. It installs agent profiles and skills from git and local sources into a .mars/ canonical store, records ownership in mars.lock, and copies managed content into configured target directories (.agents/, .claude/, .cursor/, etc.).

Quick Start

# Initialize with a target directory
mars init --link .claude

# Add sources
mars add meridian-flow/meridian-base
mars add meridian-flow/meridian-dev-workflow

# See what's installed
mars list

# Explain why an item is present
mars why reviewer

Why Mars

• Install agents and skills from multiple sources into one managed tree
• Resolve versions and transitive source dependencies before installation
• Keep syncs safe: resolve full desired state, then apply atomically
• Track ownership and checksums in mars.lock so managed and unmanaged files coexist
• Copy managed content to multiple target directories (.agents/, .claude/, etc.)
• Support day-to-day maintenance: upgrades, outdated checks, local overrides, rename rules, conflict resolution, repair flows
• Package-distributed model aliases — no hardcoded builtins in the binary

Where Mars Fits

Mars is not an agent runtime. It sits underneath tools like Claude Code, Cursor, and Codex and manages the agent assets they read.

Install

Prebuilt binaries: https://github.com/meridian-flow/mars-agents/releases

Platforms: macOS arm64/x64, Linux arm64/x64 (glibc). Others: build from source.

Source Inputs

Commands

Global flags: --root <PATH>, --json.

How It Works

mars.toml + mars.lock (committed)
        ↓ mars sync
    .mars/ (canonical store, gitignored)
        ↓ copy to each target
    .agents/, .claude/, .cursor/ (committed, may contain non-mars content)

Every mutating command runs a typed pipeline:

load_config → resolve_graph → build_target → create_plan → apply_plan → sync_targets → finalize

1. Resolve — fetch sources, discover transitive deps, merge model aliases from dependency tree
2. Build target — discover items, apply filters, detect collisions
3. Plan — diff desired state against lock + disk
4. Apply — write resolved content to .mars/ (atomic writes via tmp+rename)
5. Sync targets — copy from .mars/ to each configured target directory (never deletes files mars didn't create)
6. Finalize — write lock, persist dependency model aliases, build report

Managed Layout

project/
  mars.toml          # Dependency config (committed)
  mars.lock          # Ownership registry (committed)
  mars.local.toml    # Dev overrides (gitignored)
  .mars/             # Canonical store (gitignored)
    agents/          # Resolved agent profiles
    skills/          # Resolved skills
    models-cache.json      # Cached model catalog
    models-merged.json     # Dependency-sourced model aliases
  .agents/           # Target directory (committed, may have non-mars content)
    agents/
    skills/
  .claude/           # Another target (committed)
    agents/
    skills/

Model Aliases

Model aliases are package-distributed — no builtins in the mars binary. Packages define aliases in their mars.toml under [models]:

# Pinned — explicit model ID
[models.opus]
harness = "claude"
model = "claude-opus-4-6"

# Auto-resolve — pattern matching against cached model catalog
[models.sonnet]
harness = "claude"
provider = "Anthropic"
match = ["sonnet"]
exclude = ["thinking"]

Merge precedence: consumer config > dependencies (declaration order, first wins).

mars models refresh          # Fetch model catalog from API
mars models list             # Show all aliases (deps + consumer config)
mars models list --include "opus*,sonnet*"   # Show only matching aliases
mars models list --exclude "experimental-*"   # Hide matching aliases
mars models resolve opus     # Resolve an alias to a concrete model ID

--include and --exclude are mutually exclusive. Both override [settings.model_visibility] for that command run.

mars.toml Example

[dependencies.base]
url = "https://github.com/meridian-flow/meridian-base"
version = "^1.0"

[dependencies.dev]
path = "../my-dev-agents"

[dependencies.ops]
url = "https://github.com/acme/ops-agents"
only_skills = true

[models.opus]
harness = "claude"
provider = "Anthropic"
match = ["opus"]

[settings]
targets = [".agents", ".claude"]

After editing mars.toml, run mars sync to apply changes.

Documentation

Detailed documentation is in docs/:

• Overview — Core concepts and quick start
• Configuration — mars.toml reference: all fields, filter modes, settings
• CLI Reference — Every subcommand with flags, examples, and behavior
• Sync Pipeline — How sync works: resolve → target → diff → apply → sync targets → finalize
• Conflicts — Collision handling, merge, conflict resolution
• Lock File — Lock file format and semantics
• Local Development — Overrides, local paths, submodules
• Troubleshooting — mars doctor, mars repair, common problems

Design Constraints

• Resolve first, then act. If resolution fails, nothing is mutated.
• Config, lock, and installed files use atomic writes (tmp+rename).
• mars.lock is the authority for what Mars manages.
• Target directories are shared — mars never deletes files it didn't create.
• User intent comes from explicit flags and arguments, not heuristics.
• No builtin model aliases — all aliases come from packages or consumer config.