mars-agents 0.7.2

Agent package manager for .agents/ directories
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

# mars

A package manager for AI agent profiles and skills. Install agents and skills from git sources into Claude Code, Codex, OpenCode, Cursor, and other agent harness config directories.

## Target Status

Mars materializes harness-native artifacts for multiple targets:

| Target | Status | Notes |
|---|---|---|
| `.claude` | First-class | Claude Code agents, skills, MCP, hooks, and settings surfaces. |
| `.codex` | First-class | Codex project instruction and agent-facing surfaces. |
| `.opencode` | First-class | OpenCode agent and permission surfaces. |
| `.cursor` | Experimental | Cursor CLI/config support exists, but semantics can change as Cursor's agent surface evolves. |
| `.pi` | Future first-class | Meridian-owned Pi flavor and extension surface; under active design/development. |

## Install

| Method | Command |
|---|---|
| Cargo | `cargo install mars-agents` |
| pip / uv | `uv tool install mars-agents` or `pip install mars-agents` |
| npm | `npm install -g @meridian-flow/mars-agents` |
| Prebuilt binaries | [GitHub Releases](https://github.com/haowjy/mars-agents/releases) |

## Quick Start

```bash
mars init
mars add meridian-flow/meridian-dev-workflow
mars link .claude
mars link .codex
```

Your agents and skills are now installed and available in both Claude Code and Codex. Update them with `mars upgrade`, check for drift with `mars doctor`.

## Adding Sources

```bash
# From GitHub
mars add meridian-flow/meridian-base
mars add acme/security-agents --only-agents

# From a local directory
mars add ../my-team-agents

# Pin a version
mars add meridian-flow/meridian-base@^1.0
```

## Model Aliases

Packages can distribute model routing — short names that resolve to concrete models across harnesses:

```bash
mars models list
mars models resolve opus
```

```toml
# In mars.toml — override any alias
[models.opus]
harness = "claude"
provider = "Anthropic"
match = ["*opus*"]
```

## How It Works

```mermaid
flowchart TD
    sources["mars.toml + mars.lock<br/><i>committed</i>"]
    local[".mars-src/<br/><i>your own agents, skills, MCP, hooks</i>"]
    git["git sources<br/><i>resolved from mars.toml</i>"]

    canonical[".mars/<br/><i>canonical store, gitignored</i>"]
    agents["agents/ + skills/"]
    mcp["mcp servers"]
    hooks["lifecycle hooks"]

    claude[".claude/"]
    codex[".codex/"]
    cursor[".cursor/"]
    opencode[".opencode/"]

    sources --> |mars sync| canonical
    local --> canonical
    git --> canonical

    canonical --- agents
    canonical --- mcp
    canonical --- hooks

    canonical --> |mars link| claude
    canonical --> |mars link| codex
    canonical --> |mars link| cursor
    canonical --> |mars link| opencode
```

Mars resolves the full dependency graph before touching any files. Writes are atomic. The lock file tracks what mars manages so it never touches your files. Each linked target gets harness-native artifacts — agents, skills, MCP servers, and hooks compiled to match what that tool expects.

Use `mars adopt` to bring an existing unmanaged file into `.mars-src/` in one step.

## Docs

- [Config](docs/config/) — `mars.toml`, agent profiles, compilation, MCP/hooks
- [CLI](docs/cli/commands.md) — every command with flags and examples
- [Internals](docs/internals/) — sync pipeline, lock file, conflicts
- [Dev](docs/dev/) — local development, troubleshooting, smoke testing

## License

MIT