mobius-loop 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/commands/linear/define.md +22 -0
- package/.claude/commands/linear/execute.md +22 -0
- package/.claude/commands/linear/refine.md +22 -0
- package/.claude/commands/linear/verify.md +22 -0
- package/.claude/skills/define-linear-issue/SKILL.md +386 -0
- package/.claude/skills/execute-linear-issue/SKILL.md +629 -0
- package/.claude/skills/refine-linear-issue/SKILL.md +379 -0
- package/.claude/skills/verify-linear-issue/SKILL.md +663 -0
- package/AGENTS.md +70 -0
- package/LICENSE +21 -0
- package/README.md +457 -0
- package/dist/bin/mobius.d.ts +3 -0
- package/dist/bin/mobius.d.ts.map +1 -0
- package/dist/bin/mobius.js +75 -0
- package/dist/bin/mobius.js.map +1 -0
- package/dist/commands/config.d.ts +6 -0
- package/dist/commands/config.d.ts.map +1 -0
- package/dist/commands/config.js +88 -0
- package/dist/commands/config.js.map +1 -0
- package/dist/commands/doctor.d.ts +2 -0
- package/dist/commands/doctor.d.ts.map +1 -0
- package/dist/commands/doctor.js +86 -0
- package/dist/commands/doctor.js.map +1 -0
- package/dist/commands/run.d.ts +10 -0
- package/dist/commands/run.d.ts.map +1 -0
- package/dist/commands/run.js +62 -0
- package/dist/commands/run.js.map +1 -0
- package/dist/commands/setup.d.ts +2 -0
- package/dist/commands/setup.d.ts.map +1 -0
- package/dist/commands/setup.js +131 -0
- package/dist/commands/setup.js.map +1 -0
- package/dist/lib/checks/cclean.d.ts +3 -0
- package/dist/lib/checks/cclean.d.ts.map +1 -0
- package/dist/lib/checks/cclean.js +23 -0
- package/dist/lib/checks/cclean.js.map +1 -0
- package/dist/lib/checks/claude.d.ts +3 -0
- package/dist/lib/checks/claude.d.ts.map +1 -0
- package/dist/lib/checks/claude.js +38 -0
- package/dist/lib/checks/claude.js.map +1 -0
- package/dist/lib/checks/config.d.ts +4 -0
- package/dist/lib/checks/config.d.ts.map +1 -0
- package/dist/lib/checks/config.js +45 -0
- package/dist/lib/checks/config.js.map +1 -0
- package/dist/lib/checks/docker.d.ts +3 -0
- package/dist/lib/checks/docker.d.ts.map +1 -0
- package/dist/lib/checks/docker.js +46 -0
- package/dist/lib/checks/docker.js.map +1 -0
- package/dist/lib/checks/linear-mcp.d.ts +3 -0
- package/dist/lib/checks/linear-mcp.d.ts.map +1 -0
- package/dist/lib/checks/linear-mcp.js +46 -0
- package/dist/lib/checks/linear-mcp.js.map +1 -0
- package/dist/lib/checks/path.d.ts +5 -0
- package/dist/lib/checks/path.d.ts.map +1 -0
- package/dist/lib/checks/path.js +49 -0
- package/dist/lib/checks/path.js.map +1 -0
- package/dist/lib/config.d.ts +37 -0
- package/dist/lib/config.d.ts.map +1 -0
- package/dist/lib/config.js +145 -0
- package/dist/lib/config.js.map +1 -0
- package/dist/lib/paths.d.ts +39 -0
- package/dist/lib/paths.d.ts.map +1 -0
- package/dist/lib/paths.js +117 -0
- package/dist/lib/paths.js.map +1 -0
- package/dist/types.d.ts +39 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +19 -0
- package/dist/types.js.map +1 -0
- package/mobius.config.yaml +38 -0
- package/package.json +56 -0
- package/scripts/mobius.sh +394 -0
- package/scripts/render-diagrams.sh +38 -0
- package/scripts/render-terminal.sh +49 -0
package/AGENTS.md
ADDED
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
Operational guide for autonomous Mobius execution. This file is loaded each iteration to provide project-specific context to Claude.
|
|
4
|
+
|
|
5
|
+
**Copy this template to your project root and customize for your codebase.**
|
|
6
|
+
|
|
7
|
+
## Build & Validation
|
|
8
|
+
|
|
9
|
+
Run these commands after implementing changes to get immediate feedback:
|
|
10
|
+
|
|
11
|
+
- **Tests:** `npm test` or `pytest` or `go test ./...`
|
|
12
|
+
- **Single test:** `npm test -- path/to/test.spec.ts`
|
|
13
|
+
- **Typecheck:** `npm run typecheck` or `mypy .`
|
|
14
|
+
- **Lint:** `npm run lint` or `ruff check .`
|
|
15
|
+
- **Build:** `npm run build` or `go build ./...`
|
|
16
|
+
|
|
17
|
+
## Operational Notes
|
|
18
|
+
|
|
19
|
+
Guidelines for autonomous execution:
|
|
20
|
+
|
|
21
|
+
- Always run validation commands after making changes
|
|
22
|
+
- Commit frequently with descriptive messages
|
|
23
|
+
- If tests fail, fix them before moving to the next sub-task
|
|
24
|
+
- When blocked, add a comment to the issue explaining the blocker
|
|
25
|
+
- Prefer small, focused changes over large refactors
|
|
26
|
+
|
|
27
|
+
## Codebase Patterns
|
|
28
|
+
|
|
29
|
+
Document your project's conventions here:
|
|
30
|
+
|
|
31
|
+
- **Components:** `src/components/` - React components, PascalCase naming
|
|
32
|
+
- **Services:** `src/services/` - Business logic, singleton pattern
|
|
33
|
+
- **API:** `src/api/` - REST endpoints, OpenAPI documented
|
|
34
|
+
- **Tests:** `__tests__/` directories, `.spec.ts` suffix
|
|
35
|
+
- **Types:** `src/types/` - Shared TypeScript interfaces
|
|
36
|
+
|
|
37
|
+
## Common Issues
|
|
38
|
+
|
|
39
|
+
Known gotchas and their solutions:
|
|
40
|
+
|
|
41
|
+
- **Mock setup:** Always reset mocks in `beforeEach`
|
|
42
|
+
- **Async tests:** Use `await` with all async operations
|
|
43
|
+
- **Import paths:** Use absolute imports from `@/`
|
|
44
|
+
- **Environment:** Test env vars are in `.env.test`
|
|
45
|
+
|
|
46
|
+
## Project Structure
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
your-project/
|
|
50
|
+
├── src/
|
|
51
|
+
│ ├── components/ # UI components
|
|
52
|
+
│ ├── services/ # Business logic
|
|
53
|
+
│ ├── api/ # API routes
|
|
54
|
+
│ ├── types/ # TypeScript types
|
|
55
|
+
│ └── utils/ # Shared utilities
|
|
56
|
+
├── tests/
|
|
57
|
+
│ ├── unit/ # Unit tests
|
|
58
|
+
│ └── integration/ # Integration tests
|
|
59
|
+
├── docs/ # Documentation
|
|
60
|
+
└── scripts/ # Build/deploy scripts
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Mobius-Specific Instructions
|
|
64
|
+
|
|
65
|
+
Add any special instructions for the autonomous Mobius loop:
|
|
66
|
+
|
|
67
|
+
- Priority order for sub-tasks (if not using blockedBy)
|
|
68
|
+
- Files that should never be modified
|
|
69
|
+
- Required reviewers for certain changes
|
|
70
|
+
- Branch naming conventions
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Tubular Health
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,457 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
```
|
|
4
|
+
███╗ ███╗ ██████╗ ██████╗ ██╗██╗ ██╗███████╗
|
|
5
|
+
████╗ ████║██╔═══██╗██╔══██╗██║██║ ██║██╔════╝
|
|
6
|
+
██╔████╔██║██║ ██║██████╔╝██║██║ ██║███████╗
|
|
7
|
+
██║╚██╔╝██║██║ ██║██╔══██╗██║██║ ██║╚════██║
|
|
8
|
+
██║ ╚═╝ ██║╚██████╔╝██████╔╝██║╚██████╔╝███████║
|
|
9
|
+
╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═════╝ ╚══════╝
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
**Autonomous AI development that works with your existing workflow.**
|
|
13
|
+
|
|
14
|
+
**Define issues in Linear. Let Claude implement them. Review and ship.**
|
|
15
|
+
|
|
16
|
+
[](https://www.npmjs.com/package/mobius-loop)
|
|
17
|
+
[](LICENSE)
|
|
18
|
+
[](https://nodejs.org/)
|
|
19
|
+
|
|
20
|
+
<br>
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
npm install -g mobius-loop && mobius setup
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
**Works on Mac, Windows, and Linux.**
|
|
27
|
+
|
|
28
|
+
</div>
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## Table of Contents
|
|
33
|
+
|
|
34
|
+
- [The Problem](#the-problem)
|
|
35
|
+
- [The Solution](#the-solution)
|
|
36
|
+
- [How It Works](#how-it-works)
|
|
37
|
+
- [Quick Start](#quick-start)
|
|
38
|
+
- [The Execution Loop](#the-execution-loop)
|
|
39
|
+
- [Why Mobius?](#why-mobius)
|
|
40
|
+
- [The 4 Skills](#the-4-skills)
|
|
41
|
+
- [Configuration](#configuration)
|
|
42
|
+
- [Backend Architecture](#backend-architecture)
|
|
43
|
+
- [Project Setup](#project-setup-agentsmd)
|
|
44
|
+
- [Sandbox Mode](#sandbox-mode)
|
|
45
|
+
- [Requirements](#requirements)
|
|
46
|
+
- [CLI Reference](#cli-reference)
|
|
47
|
+
- [Troubleshooting](#troubleshooting)
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## The Problem
|
|
52
|
+
|
|
53
|
+
AI-assisted coding has a coordination problem:
|
|
54
|
+
|
|
55
|
+
- **Context amnesia** — Every session starts from scratch, losing prior decisions
|
|
56
|
+
- **Manual orchestration** — You become the glue between AI and your issue tracker
|
|
57
|
+
- **Team blindness** — No visibility into what AI is doing or has done
|
|
58
|
+
- **Scope creep** — Without guardrails, AI changes spiral beyond the original ask
|
|
59
|
+
- **Risky autonomy** — Letting AI run unattended feels dangerous
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## The Solution
|
|
64
|
+
|
|
65
|
+
Mobius uses **your existing Linear issues** as the source of truth. No new systems to learn. No state files to merge. Your team already knows how to use Linear.
|
|
66
|
+
|
|
67
|
+
| What You Do | What Mobius Does |
|
|
68
|
+
|-------------|------------------|
|
|
69
|
+
| Create a Linear issue | Break it into focused sub-tasks |
|
|
70
|
+
| Run `mobius ABC-123` | Execute each sub-task autonomously |
|
|
71
|
+
| Review the PR | Validate against acceptance criteria |
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## How It Works
|
|
76
|
+
|
|
77
|
+
<p align="center">
|
|
78
|
+
<img src="assets/diagrams/workflow.svg" alt="Mobius Workflow" width="700" />
|
|
79
|
+
</p>
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## Quick Start
|
|
84
|
+
|
|
85
|
+
Get from zero to executing your first issue:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
npm install -g mobius-loop
|
|
89
|
+
mobius setup
|
|
90
|
+
mobius ABC-123
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
<p align="center">
|
|
94
|
+
<img src="assets/terminal/setup.svg" alt="Mobius Setup" width="700" />
|
|
95
|
+
</p>
|
|
96
|
+
|
|
97
|
+
<details>
|
|
98
|
+
<summary>Alternative installation methods</summary>
|
|
99
|
+
|
|
100
|
+
### Manual Installation
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
git clone https://github.com/Tubular-Health/mobius.git
|
|
104
|
+
cd mobius
|
|
105
|
+
./install.sh
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
The installer places:
|
|
109
|
+
- `mobius` command in `~/.local/bin/`
|
|
110
|
+
- Config at `~/.config/mobius/config.yaml`
|
|
111
|
+
- Claude skills in `~/.claude/skills/`
|
|
112
|
+
|
|
113
|
+
Ensure `~/.local/bin` is in your PATH:
|
|
114
|
+
```bash
|
|
115
|
+
export PATH="$HOME/.local/bin:$PATH"
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
</details>
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## The Execution Loop
|
|
123
|
+
|
|
124
|
+
When you run `mobius ABC-123`, here's what happens:
|
|
125
|
+
|
|
126
|
+
<p align="center">
|
|
127
|
+
<img src="assets/diagrams/execution-loop.svg" alt="Execution Loop" width="600" />
|
|
128
|
+
</p>
|
|
129
|
+
|
|
130
|
+
```
|
|
131
|
+
do {
|
|
132
|
+
task = findNextReady(issue) // Respects blockedBy dependencies
|
|
133
|
+
|
|
134
|
+
implement(task) // Single-file focus per sub-task
|
|
135
|
+
|
|
136
|
+
validate() // Tests, typecheck, lint
|
|
137
|
+
|
|
138
|
+
commit() // Descriptive message, push
|
|
139
|
+
|
|
140
|
+
markComplete(task) // Update Linear status
|
|
141
|
+
|
|
142
|
+
} while (hasReadyTasks(issue))
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
<p align="center">
|
|
146
|
+
<img src="assets/terminal/execution.svg" alt="Mobius Execution" width="800" />
|
|
147
|
+
</p>
|
|
148
|
+
|
|
149
|
+
**Stop anytime. Resume later.** State lives in Linear, not local files.
|
|
150
|
+
|
|
151
|
+
---
|
|
152
|
+
|
|
153
|
+
## Why Mobius?
|
|
154
|
+
|
|
155
|
+
| Feature | Mobius | GSD | Beads |
|
|
156
|
+
|---------|--------|-----|-------|
|
|
157
|
+
| **State management** | Linear (existing tracker) | PROJECT.md, STATE.md files | .beads/ SQLite + daemon |
|
|
158
|
+
| **Setup** | `npm install -g mobius-loop` | Clone + configure file structure | Clone + daemon + database |
|
|
159
|
+
| **Team workflow** | Works with existing process | Requires learning new system | Requires syncing database |
|
|
160
|
+
| **Merge conflicts** | None — state is external | Frequent on state files | Database sync issues |
|
|
161
|
+
| **Resumability** | Stop/resume anytime | Manual state management | Daemon must be running |
|
|
162
|
+
| **Sandbox mode** | Docker isolation built-in | None | None |
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## The 4 Skills
|
|
167
|
+
|
|
168
|
+
Mobius provides four skills for the complete issue lifecycle. Currently implemented for Linear; the architecture supports additional backends.
|
|
169
|
+
|
|
170
|
+
<details>
|
|
171
|
+
<summary><code>/linear:define</code> — Create well-defined issues</summary>
|
|
172
|
+
|
|
173
|
+
Through Socratic questioning, Claude helps you create issues with:
|
|
174
|
+
- Clear title and description
|
|
175
|
+
- Measurable acceptance criteria
|
|
176
|
+
- Appropriate labels and priority
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
claude "/linear:define"
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
</details>
|
|
183
|
+
|
|
184
|
+
<details>
|
|
185
|
+
<summary><code>/linear:refine</code> — Break into sub-tasks</summary>
|
|
186
|
+
|
|
187
|
+
Analyzes your codebase and creates sub-tasks that are:
|
|
188
|
+
- Small enough for single-file focus
|
|
189
|
+
- Ordered with blocking dependencies
|
|
190
|
+
- Detailed with specific files and changes
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
claude "/linear:refine ABC-123"
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
</details>
|
|
197
|
+
|
|
198
|
+
<details>
|
|
199
|
+
<summary><code>/linear:execute</code> — Implement one sub-task</summary>
|
|
200
|
+
|
|
201
|
+
Executes the next ready sub-task:
|
|
202
|
+
1. Reads parent issue context
|
|
203
|
+
2. Implements the change
|
|
204
|
+
3. Runs validation commands
|
|
205
|
+
4. Commits and pushes
|
|
206
|
+
5. Marks sub-task complete
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
claude "/linear:execute ABC-123"
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
Or use the CLI for continuous execution:
|
|
213
|
+
```bash
|
|
214
|
+
mobius ABC-123
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
</details>
|
|
218
|
+
|
|
219
|
+
<details>
|
|
220
|
+
<summary><code>/linear:verify</code> — Validate completion</summary>
|
|
221
|
+
|
|
222
|
+
Reviews implementation against acceptance criteria:
|
|
223
|
+
- Compares changes to requirements
|
|
224
|
+
- Runs final validation
|
|
225
|
+
- Adds review notes as Linear comment
|
|
226
|
+
- Marks issue complete if passing
|
|
227
|
+
|
|
228
|
+
```bash
|
|
229
|
+
claude "/linear:verify ABC-123"
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
</details>
|
|
233
|
+
|
|
234
|
+
---
|
|
235
|
+
|
|
236
|
+
## Configuration
|
|
237
|
+
|
|
238
|
+
<details>
|
|
239
|
+
<summary>View configuration options</summary>
|
|
240
|
+
|
|
241
|
+
### Config File
|
|
242
|
+
|
|
243
|
+
Edit `~/.config/mobius/config.yaml`:
|
|
244
|
+
|
|
245
|
+
```yaml
|
|
246
|
+
backend: linear
|
|
247
|
+
|
|
248
|
+
execution:
|
|
249
|
+
delay_seconds: 3
|
|
250
|
+
max_iterations: 50
|
|
251
|
+
model: opus
|
|
252
|
+
sandbox: true
|
|
253
|
+
container_name: mobius-sandbox
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
### Environment Variables
|
|
257
|
+
|
|
258
|
+
Override any setting with environment variables:
|
|
259
|
+
|
|
260
|
+
```bash
|
|
261
|
+
export MOBIUS_BACKEND=linear
|
|
262
|
+
export MOBIUS_DELAY_SECONDS=5
|
|
263
|
+
export MOBIUS_MAX_ITERATIONS=100
|
|
264
|
+
export MOBIUS_MODEL=sonnet
|
|
265
|
+
export MOBIUS_SANDBOX_ENABLED=false
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
### Commands
|
|
269
|
+
|
|
270
|
+
```bash
|
|
271
|
+
mobius config # Show current configuration
|
|
272
|
+
mobius config --edit # Open config in editor
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
</details>
|
|
276
|
+
|
|
277
|
+
---
|
|
278
|
+
|
|
279
|
+
## Backend Architecture
|
|
280
|
+
|
|
281
|
+
<p align="center">
|
|
282
|
+
<img src="assets/diagrams/architecture.svg" alt="Backend Architecture" width="600" />
|
|
283
|
+
</p>
|
|
284
|
+
|
|
285
|
+
Mobius uses a skill-based architecture that abstracts the issue tracker. While **Linear is the primary supported backend**, the architecture is designed for extensibility.
|
|
286
|
+
|
|
287
|
+
Each backend has corresponding skills at `.claude/skills/<backend>/`. The pattern supports adding new backends (Jira, GitHub Issues, etc.) by implementing the skill interface:
|
|
288
|
+
|
|
289
|
+
| Backend | Status | Skills Location |
|
|
290
|
+
|---------|--------|-----------------|
|
|
291
|
+
| **Linear** | Supported | `.claude/skills/*-linear-issue/` |
|
|
292
|
+
| Jira | Planned | `.claude/skills/*-jira-issue/` |
|
|
293
|
+
| GitHub Issues | Planned | `.claude/skills/*-github-issue/` |
|
|
294
|
+
|
|
295
|
+
---
|
|
296
|
+
|
|
297
|
+
## Project Setup: AGENTS.md
|
|
298
|
+
|
|
299
|
+
Copy the template to your project root to provide context each iteration:
|
|
300
|
+
|
|
301
|
+
```bash
|
|
302
|
+
cp /path/to/mobius/AGENTS.md ./AGENTS.md
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
This file tells Claude about your project:
|
|
306
|
+
- Build and validation commands
|
|
307
|
+
- Codebase patterns and conventions
|
|
308
|
+
- Common issues and solutions
|
|
309
|
+
- Files that should not be modified
|
|
310
|
+
|
|
311
|
+
<details>
|
|
312
|
+
<summary>Example AGENTS.md</summary>
|
|
313
|
+
|
|
314
|
+
```markdown
|
|
315
|
+
## Build & Validation
|
|
316
|
+
|
|
317
|
+
- **Tests:** `npm test`
|
|
318
|
+
- **Typecheck:** `npm run typecheck`
|
|
319
|
+
- **Lint:** `npm run lint`
|
|
320
|
+
|
|
321
|
+
## Codebase Patterns
|
|
322
|
+
|
|
323
|
+
- Components: `src/components/` - React, PascalCase
|
|
324
|
+
- Services: `src/services/` - Business logic
|
|
325
|
+
- Tests: `__tests__/` directories, `.spec.ts` suffix
|
|
326
|
+
|
|
327
|
+
## Common Issues
|
|
328
|
+
|
|
329
|
+
- Always reset mocks in `beforeEach`
|
|
330
|
+
- Use absolute imports from `@/`
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
</details>
|
|
334
|
+
|
|
335
|
+
---
|
|
336
|
+
|
|
337
|
+
## Sandbox Mode
|
|
338
|
+
|
|
339
|
+
By default, Mobius runs Claude in a Docker container for safer autonomous execution. This isolates file system changes and prevents accidental damage to your system.
|
|
340
|
+
|
|
341
|
+
```bash
|
|
342
|
+
# Run in sandbox (default)
|
|
343
|
+
mobius ABC-123
|
|
344
|
+
|
|
345
|
+
# Run locally (bypass sandbox)
|
|
346
|
+
mobius ABC-123 --local
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
To disable sandbox permanently:
|
|
350
|
+
```yaml
|
|
351
|
+
execution:
|
|
352
|
+
sandbox: false
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
---
|
|
356
|
+
|
|
357
|
+
## Requirements
|
|
358
|
+
|
|
359
|
+
| Requirement | Notes |
|
|
360
|
+
|-------------|-------|
|
|
361
|
+
| **Node.js 18+** | For npm installation |
|
|
362
|
+
| **Claude Code CLI** | Install from [claude.ai/code](https://claude.ai/code) |
|
|
363
|
+
| **Linear account** | Primary supported backend; architecture supports additional backends |
|
|
364
|
+
| **Docker** (optional) | For sandbox mode |
|
|
365
|
+
|
|
366
|
+
---
|
|
367
|
+
|
|
368
|
+
## CLI Reference
|
|
369
|
+
|
|
370
|
+
```bash
|
|
371
|
+
mobius <issue-id> [iterations] # Execute sub-tasks
|
|
372
|
+
mobius ABC-123 # Run until complete
|
|
373
|
+
mobius ABC-123 10 # Limit to 10 iterations
|
|
374
|
+
mobius ABC-123 --local # Bypass sandbox
|
|
375
|
+
mobius ABC-123 --model=sonnet # Use specific model
|
|
376
|
+
|
|
377
|
+
mobius setup # Interactive setup wizard
|
|
378
|
+
mobius config # Show configuration
|
|
379
|
+
mobius config --edit # Edit configuration
|
|
380
|
+
mobius doctor # Check system requirements
|
|
381
|
+
mobius --help # Show help
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
---
|
|
385
|
+
|
|
386
|
+
## Troubleshooting
|
|
387
|
+
|
|
388
|
+
<details>
|
|
389
|
+
<summary>Common issues and solutions</summary>
|
|
390
|
+
|
|
391
|
+
### "Claude CLI not found"
|
|
392
|
+
|
|
393
|
+
Install Claude Code CLI from [claude.ai/code](https://claude.ai/code).
|
|
394
|
+
|
|
395
|
+
### "cclean not found"
|
|
396
|
+
|
|
397
|
+
The `cclean` utility formats Claude's JSON output. Mobius works without it, but output will be less readable.
|
|
398
|
+
|
|
399
|
+
### Mobius stops unexpectedly
|
|
400
|
+
|
|
401
|
+
Check iteration limit:
|
|
402
|
+
```bash
|
|
403
|
+
mobius config
|
|
404
|
+
```
|
|
405
|
+
|
|
406
|
+
Increase `max_iterations` or set to `0` for unlimited.
|
|
407
|
+
|
|
408
|
+
### Sub-tasks not executing in order
|
|
409
|
+
|
|
410
|
+
Ensure sub-tasks have proper `blockedBy` relationships. Run `/linear:refine` again if dependencies are missing.
|
|
411
|
+
|
|
412
|
+
### Linear MCP not configured
|
|
413
|
+
|
|
414
|
+
Ensure Linear MCP tools are configured in your Claude settings. Check with:
|
|
415
|
+
```bash
|
|
416
|
+
mobius doctor
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
### Docker sandbox fails to start
|
|
420
|
+
|
|
421
|
+
Verify Docker is running:
|
|
422
|
+
```bash
|
|
423
|
+
docker info
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
If issues persist, run without sandbox:
|
|
427
|
+
```bash
|
|
428
|
+
mobius ABC-123 --local
|
|
429
|
+
```
|
|
430
|
+
|
|
431
|
+
### Permission denied errors
|
|
432
|
+
|
|
433
|
+
Ensure `~/.local/bin` is in your PATH and mobius is executable:
|
|
434
|
+
```bash
|
|
435
|
+
chmod +x ~/.local/bin/mobius
|
|
436
|
+
```
|
|
437
|
+
|
|
438
|
+
### Sub-task implementation fails validation
|
|
439
|
+
|
|
440
|
+
The task will remain incomplete. Fix the issue manually or run:
|
|
441
|
+
```bash
|
|
442
|
+
claude "/linear:execute ABC-123"
|
|
443
|
+
```
|
|
444
|
+
|
|
445
|
+
Claude will retry the failed task.
|
|
446
|
+
|
|
447
|
+
</details>
|
|
448
|
+
|
|
449
|
+
---
|
|
450
|
+
|
|
451
|
+
<p align="center">
|
|
452
|
+
<strong>MIT License</strong>
|
|
453
|
+
</p>
|
|
454
|
+
|
|
455
|
+
<p align="center">
|
|
456
|
+
<code>npm install -g mobius-loop && mobius setup</code>
|
|
457
|
+
</p>
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"mobius.d.ts","sourceRoot":"","sources":["../../src/bin/mobius.ts"],"names":[],"mappings":""}
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { program } from 'commander';
|
|
3
|
+
import { doctor } from '../commands/doctor.js';
|
|
4
|
+
import { setup } from '../commands/setup.js';
|
|
5
|
+
import { run } from '../commands/run.js';
|
|
6
|
+
import { showConfig } from '../commands/config.js';
|
|
7
|
+
const version = '1.0.0';
|
|
8
|
+
program
|
|
9
|
+
.name('mobius')
|
|
10
|
+
.description('AI-Powered Development Workflow Tool')
|
|
11
|
+
.version(version);
|
|
12
|
+
program
|
|
13
|
+
.command('setup')
|
|
14
|
+
.description('Interactive setup wizard')
|
|
15
|
+
.action(async () => {
|
|
16
|
+
await setup();
|
|
17
|
+
});
|
|
18
|
+
program
|
|
19
|
+
.command('doctor')
|
|
20
|
+
.description('Check system requirements and configuration')
|
|
21
|
+
.action(async () => {
|
|
22
|
+
await doctor();
|
|
23
|
+
});
|
|
24
|
+
program
|
|
25
|
+
.command('config')
|
|
26
|
+
.description('Show current configuration')
|
|
27
|
+
.option('-e, --edit', 'Open config in editor')
|
|
28
|
+
.action(async (options) => {
|
|
29
|
+
await showConfig(options);
|
|
30
|
+
});
|
|
31
|
+
program
|
|
32
|
+
.command('run <task-id> [max-iterations]')
|
|
33
|
+
.description('Execute sub-tasks of an issue')
|
|
34
|
+
.option('-l, --local', 'Run locally (bypass container sandbox)')
|
|
35
|
+
.option('-b, --backend <backend>', 'Backend: linear or jira')
|
|
36
|
+
.option('-m, --model <model>', 'Model: opus, sonnet, or haiku')
|
|
37
|
+
.option('-d, --delay <seconds>', 'Delay between iterations', parseInt)
|
|
38
|
+
.action(async (taskId, maxIterations, options) => {
|
|
39
|
+
const max = maxIterations ? parseInt(maxIterations, 10) : undefined;
|
|
40
|
+
await run(taskId, max, {
|
|
41
|
+
local: options.local,
|
|
42
|
+
backend: options.backend,
|
|
43
|
+
model: options.model,
|
|
44
|
+
delay: options.delay,
|
|
45
|
+
});
|
|
46
|
+
});
|
|
47
|
+
// Default command: treat first arg as task ID if no command specified
|
|
48
|
+
program
|
|
49
|
+
.argument('[task-id]', 'Task ID to execute (shorthand for "run")')
|
|
50
|
+
.argument('[max-iterations]', 'Maximum iterations')
|
|
51
|
+
.option('-l, --local', 'Run locally (bypass container sandbox)')
|
|
52
|
+
.option('-b, --backend <backend>', 'Backend: linear or jira')
|
|
53
|
+
.option('-m, --model <model>', 'Model: opus, sonnet, or haiku')
|
|
54
|
+
.option('-d, --delay <seconds>', 'Delay between iterations', parseInt)
|
|
55
|
+
.action(async (taskId, maxIterations, options) => {
|
|
56
|
+
// If no task ID, show help
|
|
57
|
+
if (!taskId) {
|
|
58
|
+
program.help();
|
|
59
|
+
return; // help() calls process.exit, but this satisfies the type checker
|
|
60
|
+
}
|
|
61
|
+
// If task ID looks like a command, let commander handle it
|
|
62
|
+
if (['setup', 'doctor', 'config', 'run', 'help'].includes(taskId)) {
|
|
63
|
+
return;
|
|
64
|
+
}
|
|
65
|
+
// Otherwise, treat as task ID
|
|
66
|
+
const max = maxIterations ? parseInt(maxIterations, 10) : undefined;
|
|
67
|
+
await run(taskId, max, {
|
|
68
|
+
local: options.local,
|
|
69
|
+
backend: options.backend,
|
|
70
|
+
model: options.model,
|
|
71
|
+
delay: options.delay,
|
|
72
|
+
});
|
|
73
|
+
});
|
|
74
|
+
program.parse();
|
|
75
|
+
//# sourceMappingURL=mobius.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"mobius.js","sourceRoot":"","sources":["../../src/bin/mobius.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/commands/config.ts"],"names":[],"mappings":"AAMA,UAAU,aAAa;IACrB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAmEtE"}
|