mars-agents 0.2.4

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
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189

# Troubleshooting

## `mars doctor`

The primary diagnostic tool. Checks six areas and reports all issues at once.

```bash
mars doctor
```

### What it checks

| Area | What's validated |
|---|---|
| Config | `mars.toml` parses without errors |
| Lock file | `mars.lock` parses without errors |
| File integrity | Every locked item exists on disk |
| Conflict markers | Agent files don't contain `<<<<<<<` / `>>>>>>>` |
| Config-lock consistency | Every dependency in config has a lock entry |
| Skill references | Every agent's declared skill deps exist on disk |
| Link health | Symlinks exist, point to correct managed root, not broken |
| Target divergence | Each locked item's target copy matches lock checksum |

### Exit codes

| Code | Meaning |
|---|---|
| 0 | All checks passed |
| 2 | Issues found (printed to stderr) |

### Example output

```
  agents/coder.md has unresolved conflict markers
  dependency `dev` is in config but not in lock — run `mars sync`
  agent `coder` references missing skill `planning` — add a source that provides it
  link `.claude` — .claude/agents points to ../other (expected .agents/agents)
```

### Target divergence

Doctor checks each managed target directory against the lock's expected checksums. Missing files and files with unexpected content are reported as warnings with suggestions to run `mars sync --force` or `mars repair` to restore canonical state.

## `mars repair`

When things are broken beyond what `mars sync` can fix.

```bash
mars repair
```

### What it does

1. Loads the lock file. If corrupt, resets to empty and warns.
2. Runs a forced sync (`--force` mode): overwrites all managed files from dependencies.
3. During corrupt-lock recovery, removes unmanaged collision paths and retries (bounded to 1024 retries).

### When to use

- Lock file is corrupt (parse errors)
- Files were manually deleted or moved
- Managed root is in an inconsistent state
- `mars sync` reports errors that don't resolve

### What it doesn't do

- Fix config errors (you need to fix `mars.toml` manually)
- Recover deleted sources (the git cache may need to re-fetch)
- Preserve local modifications (forced sync overwrites everything)

## Common Problems

### "no mars.toml found"

Mars auto-detects from the current directory, then maps the managed root back to the project root (directory containing `mars.toml`), stopping at the nearest `.git` boundary. Solutions:

- Run `mars init` to create the config
- Use `--root <path>` to point directly at the managed root (for example, `.agents/`) when auto-detection picks the wrong location
- Make sure you're inside the git repository that contains the project root

### "dependency `X` has both `url` and `path`"

Each dependency must have exactly one source type. Edit `mars.toml` to keep only `url` or `path`.

### "only_skills and only_agents are mutually exclusive"

Invalid filter combination. A dependency can restrict to skills-only or agents-only, not both. Pick one or remove both for all items.

### "lock file error" / "failed to parse mars.lock"

The lock file is corrupt. Run:

```bash
mars repair
```

This resets the lock and rebuilds from dependencies.

### "collides with unmanaged path"

A managed item would overwrite a file that Mars doesn't own. Options:
- Move the unmanaged file out of the way
- Rename the managed item: `mars rename agents/conflict.md agents/other-name.md`
- If this is during repair, the file is removed automatically

### Missing files on disk

If `mars doctor` reports missing files:

```bash
mars sync      # Reinstall from dependencies
# or
mars repair    # Full rebuild if sync doesn't fix it
```

### Conflict markers in files

Current sync behavior is source-wins: `mars sync` overwrites local modifications with upstream content rather than producing conflict markers. Conflict markers in managed files would only come from manual edits or legacy state from an older mars version.

If conflict markers are present, edit the file to remove them, then:

```bash
mars resolve                     # Resolve all
mars resolve agents/coder.md    # Resolve specific file
```

### Link points to wrong target

```bash
mars link --unlink .claude   # Remove old link
mars link .claude            # Re-create correct link
```

Or with force:

```bash
mars link .claude --force    # Replace whatever exists
```

### "override `X` references a dependency not in mars.toml"

The `mars.local.toml` has an override for a dependency that doesn't exist in config. Either:
- Add the dependency to `mars.toml`
- Remove the stale override from `mars.local.toml`

### Cache taking too much space

```bash
mars cache info     # See disk usage
mars cache clean    # Remove all cached sources
```

The cache is rebuilt automatically on the next sync.

### Stale lock after dependency changes

If you edited `mars.toml` manually:

```bash
mars sync    # Re-resolve and update lock
```

If `mars sync` fails with frozen mode in CI:

```bash
# Locally:
mars sync          # Update lock
git add mars.lock
git commit -m "Update lock file"
```

## Diagnostic Workflow

For any issue, start with:

```bash
mars doctor          # What's wrong?
mars sync            # Can sync fix it?
mars repair          # Nuclear option: rebuild everything
```

If the problem persists after repair, check:
1. Is `mars.toml` valid? (`mars doctor` reports config errors)
2. Are git sources accessible? (network, auth)
3. Is the managed root writable? (permissions)

## Smoke Checks

For parser, discovery, transport, or sync regressions, use the manual smoke matrices in [Smoke Testing (POSIX)](smoke-testing-posix.md) or [Smoke Testing (Windows)](smoke-testing-windows.md).