@motionode/cli 0.1.1 → 0.2.0

package/README.md

@@ -20,5 +20,52 @@ motionode finish T11-518   # Motionode checks your pushed commits and moves the
 - It runs only fixed git operations Motionode can ask for (check out a ticket
   branch, show a diff, commit and push, move changes onto a ticket branch) —
   never arbitrary commands.
-- `--api URL` (or `MOTIONODE_API_URL`) points it at another Motionode API.
+- `motionode use <url>` points every terminal at another Motionode API until `motionode use production`; `--api URL` or `MOTIONODE_API_URL` overrides it for one run. `motionode where` shows the current one.
 - Revoke a computer in Motionode → Settings → Development workflow.
+
+## Repositories Motionode hosts
+
+A repository Motionode hosts lives privately in Motionode's GitHub, so your own
+GitHub account does not reach it. Clone it through Motionode instead (0.2.0+):
+
+```sh
+motionode connect                          # once per computer
+motionode clone acme/orders-api            # or the service's name: motionode clone "Orders API"
+```
+
+- The clone talks to Motionode's git proxy, and this CLI is that folder's git
+  credential helper (`motionode git-credential`), set in the clone's own git
+  config only. Plain git, Cursor, VS Code and Claude Code then just work there.
+- Each sign-in is short-lived and opens one repository. It needs a development
+  step on the project, and you can revoke it in Settings → Development workflow →
+  Git access, or by disconnecting the computer.
+- Pushes go only to the branch of a ticket you are working locally
+  (`motionode work <ticket>`); main, staging, tags and deletes are refused.
+
+## Coding agents (Claude Code, Cursor, any MCP client)
+
+Let your own agent work Motionode tickets as a first-class worker. It reads the
+ticket and its acceptance criteria, reports progress and asks questions. Requirement
+changes, overlaps and failed checks reach it between steps.
+
+```sh
+motionode mcp install --claude-code   # adds the Motionode MCP server (.mcp.json) and signal hooks (.claude/settings.json)
+motionode signals watch               # keep running: signals land in .motionode/inbox.json the moment they happen
+```
+
+- **MCP tools:** `my_work`, `get_ticket`, `get_signals`, `ack_signal` (with `incorporated` once your work reflects it),
+  `start_step`, `report_progress`, `ask_question`, `report_discovery`, `request_review`.
+  Every call acts as you, with the same permissions as the web app.
+- **Coordination records** (several agents, one person's token):
+  - `claim_step` / `release_step`: an exclusive, leased claim on the ticket's current step; other workers see who holds it.
+    Name each agent (`motionode mcp install --claude-code --agent opus5`, or `MOTIONODE_AGENT=opus5`) -- claiming needs it.
+  - `report_observation` (a symptom + evidence), `report_finding` (a cause; `verified`, `root_cause`),
+    `link_observation` and `relate_work` (coordinator/manager: one root cause, duplicates, what else it affects).
+  - `ask_decision` / `choose_decision` (an owner, options, a due time), `report_blocker` (Waiting, on a ticket or a decision).
+  - `submit_evidence`: `fails_without`, `suite_baseline`, `preview_check`, `tester_recheck` -- bound to a commit; the
+    answer carries the ticket's readiness (built → verified → integrated → released).
+- **Hooks** (no model, no network; they read the local inbox):
+  - After each tool call and on each prompt, pending signals are added to the agent's context.
+  - When the agent tries to finish while a signal that needs action is unacknowledged, it is asked once to handle it first.
+- `motionode signals pending` shows what is waiting.
+- Instead of a connected computer, you can set a personal access token (create one in Settings) in `MOTIONODE_TOKEN`.

package/bin/motionode.js

@@ -9,17 +9,41 @@ const { version } = require('../lib/api');
 const HELP = `motionode ${version} — work Motionode tickets with your own local tools
 
   motionode connect [--api URL] [--name NAME]   connect this computer (once) and link the current repo
-  motionode link [--service UUID]               link the current repository folder to a Motionode repository
+  motionode link [--service UUID] [--worktrees] link the current repository folder to a Motionode repository
+                                                (--worktrees: each ticket gets its own folder next to it)
   motionode unlink                              unlink the current folder
+  motionode clone <service | owner/repo> [dir]  clone a Motionode-hosted repository through Motionode (no GitHub
+                                                access needed: this computer's connection signs git in)
   motionode dev                                 keep Motionode in sync (branches, local changes, commit requests)
   motionode work <ticket>                       start a ticket locally and check out its branches (e.g. T11-518)
   motionode finish <ticket> [--force] [--note]  you're done: Motionode checks your pushed commits and moves it on
   motionode status                              what each linked folder has checked out and changed
   motionode where                               which Motionode this terminal talks to
+  motionode use <url|production>                switch which Motionode the CLI talks to (remembered)
   motionode logout                              disconnect this computer
 
-Git stays yours: fetch, commit and push use your own git credentials and identity.
-Talks to production (https://api.motionode.com) unless MOTIONODE_API_URL or --api says otherwise;
+For coding agents (Claude Code, Cursor, any MCP client):
+  motionode mcp                                 run the Motionode MCP server (stdio) for your agent
+  motionode mcp install --claude-code           add the MCP server and signal hooks to this repo's Claude Code settings
+                        [--agent <name>]        name this agent (MOTIONODE_AGENT) so its claims say who holds a step
+  motionode signals watch                       keep one connection open; Motionode signals land in .motionode/inbox.json
+  motionode signals pending                     what is waiting for this repository
+
+Project work and notes (as you; --project <uuid or name>, or MOTIONODE_PROJECT):
+  motionode deliverables                        the project's deliverables
+  motionode work-item create --title T          file a work item (in setup, nothing starts); --description D or
+        [--deliverable R2-1 | --new-deliverable N]  --description-file F, --criteria "a | b", --confirmed-new when
+                                                open work with the same title already exists
+  motionode work-item update <code>             change its --title and/or --description (or --description-file),
+                                                as you (needs edit rights on the project)
+  motionode notes list | get <uuid> [--html]    the project notes you may read
+  motionode notes create --file F.md            a note from markdown (--deliverable R or --ticket T: a team note;
+        [--share a@x,b@y] [--category C]         else a board note shared with the people named)
+  motionode notes update <uuid> --file F.md     replace a note you wrote or that is shared with you
+
+Git stays yours: fetch, commit and push use your own git credentials and identity. A Motionode-hosted repository
+cloned with "motionode clone" signs in through this computer's Motionode connection instead (short-lived, one repo).
+Talks to production (https://api.motionode.com) unless "motionode use", MOTIONODE_API_URL or --api says otherwise;
 each Motionode keeps its own connection.`;
 
 function flags(argv) {
@@ -48,9 +72,14 @@ async function main() {
 		case 'login':
 			return Commands.login(config, { apiUrl: args.api || null, name: args.name || null });
 		case 'link':
-			return Commands.link(config, { serviceUuid: args.service || null });
+			return Commands.link(config, { serviceUuid: args.service || null, worktrees: !!args.worktrees });
 		case 'unlink':
 			return Commands.unlink(config);
+		case 'clone':
+			return require('../lib/git_credential').clone(config, args._[0], args._[1] || null);
+		case 'git-credential':
+			// git runs this as a clone's credential helper (see lib/git_credential).
+			return require('../lib/git_credential').helper(config, args._[0]);
 		case 'dev':
 			return Bridge.run(config);
 		case 'work':
@@ -59,11 +88,34 @@ async function main() {
 			return Commands.finish(config, args._[0], { force: !!args.force, note: typeof args.note === 'string' ? args.note : null });
 		case 'status':
 			return Commands.status(config);
+		case 'use': {
+			const api = Config.useApi(args._[0]);
+			const next = Config.load();
+			console.log(`✓ Using ${api}${next.token ? '' : ' — run "motionode connect" in a repository folder to connect this computer to it'}`);
+			return null;
+		}
 		case 'where':
 			console.log(`${config.apiUrl}${config.token ? ` — connected as ${config.user?.name || config.user?.email || 'you'} (${config.machine?.name || 'this computer'})` : ' — not connected'}`);
 			return null;
 		case 'logout':
 			return Commands.logout(config);
+		case 'mcp':
+			if (args._[0] === 'install') return require('../lib/agent_setup').install(config, { claudeCode: !!args['claude-code'] || !args.cursor, cursor: !!args.cursor, agent: typeof args.agent === 'string' ? args.agent : null });
+			return require('../lib/mcp').serve(config);
+		case 'signals': {
+			const sub = args._[0] || 'pending';
+			if (sub === 'watch') return require('../lib/signals_watch').watch(config, { quiet: !!args.quiet });
+			if (sub === 'hook') return require('../lib/signals_hook').run(args._[1] || 'PostToolUse');
+			return require('../lib/signals_hook').printPending();
+		}
+		case 'deliverables':
+			return require('../lib/project_cmds').deliverables(config, args);
+		case 'work-item':
+			if (args._[0] === 'update') return require('../lib/project_cmds').updateWorkItem(config, args);
+			if (args._[0] !== 'create') throw new Error('Usage: motionode work-item create --project P --title T [...] | work-item update <code> --project P [--title T] [--description D | --description-file F]');
+			return require('../lib/project_cmds').createWorkItem(config, args);
+		case 'notes':
+			return require('../lib/project_cmds').notes(config, args);
 		case '--version':
 		case '-v':
 			console.log(version);

package/lib/agent_api.js

@@ -0,0 +1,79 @@
+'use strict';
+
+/**
+ * Client for Motionode's /api/v1/agent — what an external coding agent (Claude
+ * Code, Cursor) uses to read its tickets and exchange signals. Same machine token
+ * as the rest of the CLI (or MOTIONODE_TOKEN, a personal access token).
+ */
+
+const pkg = require('../package.json');
+
+class AgentApiError extends Error {
+	constructor(message, status) {
+		super(message);
+		this.status = status;
+	}
+}
+
+/**
+ * This agent's name (MOTIONODE_AGENT, e.g. "opus5"), sent as X-Motionode-Client on every call so Motionode can tell
+ * several agents acting as the same person apart: each is its own session and holds its own claims. Claiming a step
+ * needs it. `motionode mcp install --agent <name>` writes it into .mcp.json.
+ */
+function agentName() {
+	const name = String(process.env.MOTIONODE_AGENT || '').trim().slice(0, 80);
+	return name || null;
+}
+
+function agentHeaders() {
+	const name = agentName();
+	return name ? { 'X-Motionode-Client': name } : {};
+}
+
+function agentClient(config) {
+	const base = String(config.apiUrl || '').replace(/\/+$/, '');
+	const token = process.env.MOTIONODE_TOKEN || config.token || null;
+	async function request(method, pathname, body = null, { timeoutMs = 60000 } = {}) {
+		if (!token) throw new AgentApiError('Not connected. Run "motionode connect" (or set MOTIONODE_TOKEN).', 401);
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), timeoutMs);
+		let resp;
+		try {
+			resp = await fetch(`${base}/api/v1/agent${pathname}`, {
+				method,
+				headers: {
+					'Content-Type': 'application/json',
+					'User-Agent': `motionode-cli/${pkg.version}`,
+					Authorization: `Bearer ${token}`,
+					...agentHeaders(),
+				},
+				body: body ? JSON.stringify(body) : undefined,
+				signal: controller.signal,
+			});
+		} catch (err) {
+			if (err.name === 'AbortError') throw new AgentApiError('Motionode did not answer in time.', 0);
+			throw new AgentApiError(`Could not reach Motionode at ${base}: ${err.message}`, 0);
+		} finally {
+			clearTimeout(timer);
+		}
+		let data = null;
+		try { data = await resp.json(); } catch (_e) { data = null; }
+		if (!resp.ok || data?.ok === false) {
+			// A real {ok:false} failure can arrive with HTTP 200 (the body carries the
+			// outcome) -- "Motionode answered 200." reads like success, not a refusal.
+			const message = data?.error
+				|| (data?.ok === false ? `Motionode refused: ${resp.status}` : `Motionode answered ${resp.status}.`);
+			throw new AgentApiError(message, resp.status);
+		}
+		return data || {};
+	}
+	return {
+		base,
+		token,
+		get: (p, opts) => request('GET', p, null, opts),
+		post: (p, body, opts) => request('POST', p, body || {}, opts),
+		patch: (p, body, opts) => request('PATCH', p, body || {}, opts),
+	};
+}
+
+module.exports = { agentClient, agentName, agentHeaders, AgentApiError };

package/lib/agent_setup.js

@@ -0,0 +1,86 @@
+'use strict';
+
+/**
+ * `motionode mcp install [--claude-code] [--cursor]`: wire this repository for a coding agent.
+ *   .mcp.json              → the Motionode MCP server (stdio: `motionode mcp`)
+ *   .claude/settings.json  → Claude Code hooks that surface Motionode signals at safe points
+ *   .cursor/mcp.json       → the Motionode MCP server for Cursor (no hooks -- Cursor has none)
+ * Merges into existing files (never removes anything): a file that doesn't exist yet is created;
+ * a file that exists but fails to parse as JSON stops the install instead of being silently
+ * overwritten with an empty object.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const Inbox = require('./inbox');
+
+/** Existing, valid JSON -> parsed. Missing file -> {}. Existing but invalid JSON -> throws (never silently drops it). */
+function readJson(file) {
+	let raw;
+	try {
+		raw = fs.readFileSync(file, 'utf8');
+	} catch (err) {
+		if (err.code === 'ENOENT') return {};
+		throw err;
+	}
+	try {
+		return JSON.parse(raw);
+	} catch (_e) {
+		throw new Error(`${file} isn't valid JSON — fix it or remove it, then run again`);
+	}
+}
+
+function writeJson(file, value) {
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function addHook(settings, event, matcher, command) {
+	settings.hooks = settings.hooks || {};
+	const list = Array.isArray(settings.hooks[event]) ? settings.hooks[event] : [];
+	const exists = list.some((entry) => (entry.hooks || []).some((h) => h.command === command));
+	if (!exists) list.push({ matcher, hooks: [{ type: 'command', command }] });
+	settings.hooks[event] = list;
+}
+
+function install(config, { claudeCode = true, cursor = false, agent = null } = {}) {
+	// --agent <name>: this agent's name for Motionode (X-Motionode-Client), so claims say who holds a step.
+	const env = agent ? { env: { MOTIONODE_AGENT: String(agent).trim().slice(0, 80) } } : {};
+	const root = Inbox.repoRoot(process.cwd());
+	const written = [];
+
+	const mcpFile = path.join(root, '.mcp.json');
+	const mcp = readJson(mcpFile);
+	mcp.mcpServers = mcp.mcpServers || {};
+	mcp.mcpServers.motionode = { type: 'stdio', command: 'motionode', args: ['mcp'], ...env };
+	writeJson(mcpFile, mcp);
+	written.push(path.relative(process.cwd(), mcpFile) || '.mcp.json');
+
+	if (claudeCode) {
+		const settingsFile = path.join(root, '.claude', 'settings.json');
+		const settings = readJson(settingsFile);
+		addHook(settings, 'PostToolUse', '*', 'motionode signals hook PostToolUse');
+		addHook(settings, 'UserPromptSubmit', '', 'motionode signals hook UserPromptSubmit');
+		addHook(settings, 'Stop', '', 'motionode signals hook Stop');
+		writeJson(settingsFile, settings);
+		written.push(path.relative(process.cwd(), settingsFile));
+	}
+
+	if (cursor) {
+		// Cursor has no hook system -- just the MCP server, in its own config file.
+		const cursorFile = path.join(root, '.cursor', 'mcp.json');
+		const cursorConfig = readJson(cursorFile);
+		cursorConfig.mcpServers = cursorConfig.mcpServers || {};
+		cursorConfig.mcpServers.motionode = { command: 'motionode', args: ['mcp'], ...env };
+		writeJson(cursorFile, cursorConfig);
+		written.push(path.relative(process.cwd(), cursorFile));
+	}
+
+	Inbox.ensureExcluded(root);
+	for (const file of written) console.log(`✓ Wrote ${file}`);
+	if (claudeCode) console.log('✓ Claude Code hooks added to .claude/settings.json (signals reach your agent between steps)');
+	if (cursor) console.log('✓ Cursor MCP server added to .cursor/mcp.json (no hooks -- Cursor has none; signals still reach it through "motionode signals watch")');
+	console.log(`Next: keep "motionode signals watch" running in a terminal for this repository${config?.token ? '' : ', after "motionode connect"'}.`);
+}
+
+module.exports = { install, addHook, readJson, writeJson };

package/lib/bridge.js

@@ -27,6 +27,7 @@ async function collect(config) {
 			out.push({
 				serviceUuid: ws.serviceUuid,
 				path: ws.path,
+				worktrees: !!ws.worktrees,
 				remoteUrl: await Git.remoteUrl(ws.path),
 				branch: st.branch,
 				headSha: st.headSha,
@@ -35,7 +36,7 @@ async function collect(config) {
 				dirtyFiles: st.dirtyFiles,
 			});
 		} catch (err) {
-			out.push({ serviceUuid: ws.serviceUuid, path: ws.path, gitError: err.message });
+			out.push({ serviceUuid: ws.serviceUuid, path: ws.path, worktrees: !!ws.worktrees, gitError: err.message });
 		}
 	}
 	return out;

package/lib/commands.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const os = require('os');
+const path = require('path');
 const readline = require('readline');
 const { execFile } = require('child_process');
 const Config = require('./config');
@@ -13,6 +14,8 @@ function ask(question) {
 }
 
 function openBrowser(url) {
+	// Headless/SSH sessions: the printed URL and code are enough.
+	if (process.env.MOTIONODE_NO_BROWSER) return;
 	const cmd = process.platform === 'win32' ? 'cmd' : (process.platform === 'darwin' ? 'open' : 'xdg-open');
 	const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
 	execFile(cmd, args, { windowsHide: true }, () => {});
@@ -50,7 +53,7 @@ async function login(config, { name = null } = {}) {
 }
 
 /** Link the current folder to a Motionode repository (matched by its git remote when possible). */
-async function link(config, { serviceUuid = null, dir = process.cwd() } = {}) {
+async function link(config, { serviceUuid = null, dir = process.cwd(), worktrees = false } = {}) {
 	const root = await Git.isRepo(dir);
 	if (!root) throw new Error('This folder is not a git repository. Run `motionode link` inside your clone.');
 	const api = client(config);
@@ -77,6 +80,7 @@ async function link(config, { serviceUuid = null, dir = process.cwd() } = {}) {
 	config.workspaces = (config.workspaces || []).filter((w) => !Config.samePath(w.path, root) && w.serviceUuid !== pick.uuid);
 	config.workspaces.push({
 		path: root,
+		worktrees: !!worktrees,
 		serviceUuid: pick.uuid,
 		serviceName: pick.name,
 		projectUuid: pick.projectUuid,
@@ -84,11 +88,21 @@ async function link(config, { serviceUuid = null, dir = process.cwd() } = {}) {
 	});
 	Config.save(config);
 	console.log(`✓ ${root} → ${pick.projectName} / ${pick.name}`);
+	if (worktrees) console.log('  Each ticket you start gets its own folder next to this one (git worktree), so tickets never share a working tree.');
 	return pick;
 }
 
 async function connect(config, opts = {}) {
-	if (!config.token || opts.relogin) await login(config, opts);
+	let relogin = !config.token || opts.relogin;
+	if (!relogin) {
+		// A computer revoked in Motionode keeps its old token here; connecting again must replace it.
+		try { await client(config).get('/me'); } catch (err) {
+			if (err.status !== 401) throw err;
+			console.log('This computer was disconnected from Motionode — connecting it again.');
+			relogin = true;
+		}
+	}
+	if (relogin) await login(config, opts);
 	if (await Git.isRepo(process.cwd())) await link(config, { serviceUuid: opts.service || null });
 	console.log('');
 	console.log('Next: keep `motionode dev` running so Motionode sees your branches and local changes,');
@@ -127,6 +141,22 @@ async function status(config) {
 }
 
 /** Start (or resume) a ticket locally and check its branches out here. */
+/** Where a ticket's own folder goes: next to the linked folder, one per ticket. */
+function worktreePath(ws, ticketRef) {
+	return path.join(path.dirname(ws.path), `${path.basename(ws.path)}.worktrees`, String(ticketRef).replace(/[^A-Za-z0-9._-]/g, '_'));
+}
+
+/** What `motionode finish` tells the person was recorded (the same facts the web confirmation shows). */
+function finishLines(res) {
+	const lines = [`✓ ${res.summary || 'Build finished.'}`];
+	const rec = res.recorded;
+	if (rec) {
+		lines.push(`  Recorded: ${rec.commitCount} commit${rec.commitCount === 1 ? '' : 's'} on the ticket branch${rec.commits?.length ? ` (${rec.commits.map((c) => c.sha).join(', ')})` : ''}${rec.note ? `, note "${rec.note}"` : ''}.`);
+		if (rec.next?.stepName || rec.next?.message) lines.push(`  Next: ${rec.next.message || rec.next.stepName}${rec.next.ownerName ? ` (${rec.next.ownerName})` : ''}`);
+	}
+	return lines;
+}
+
 async function work(config, ref) {
 	if (!ref) throw new Error('Which ticket? e.g. motionode work T11-518');
 	const api = client(config);
@@ -140,8 +170,15 @@ async function work(config, ref) {
 			continue;
 		}
 		try {
-			await Git.checkout(ws.path, b.branch);
-			console.log(`  ${b.serviceName}: checked out ${b.branch} in ${ws.path}`);
+			if (ws.worktrees) {
+				const dir = worktreePath(ws, lw.ticketDisplayId || ref);
+				const wt = await Git.worktreeFor(ws.path, b.branch, dir);
+				console.log(`  ${b.serviceName}: ${wt.created ? 'created' : 'reused'} a worktree on ${b.branch} in ${wt.path}`);
+				console.log(`    Open ${wt.path} in your tool; your linked folder ${ws.path} is untouched.`);
+			} else {
+				await Git.checkout(ws.path, b.branch);
+				console.log(`  ${b.serviceName}: checked out ${b.branch} in ${ws.path}`);
+			}
 		} catch (err) {
 			console.log(`  ${b.serviceName}: could not check out ${b.branch} — ${err.message}`);
 			if (/denied|403|401|authentication|permission/i.test(err.message)) {
@@ -156,8 +193,9 @@ async function finish(config, ref, { force = false, note = null } = {}) {
 	if (!ref) throw new Error('Which ticket? e.g. motionode finish T11-518');
 	const api = client(config);
 	try {
+		console.log(`Checking the ticket branch and telling Motionode ${ref} is built…`);
 		const res = await api.post(`/tickets/${encodeURIComponent(ref)}/finish`, { force, note });
-		console.log(`✓ ${res.summary || 'Build finished.'}`);
+		finishLines(res).forEach((l) => console.log(l));
 	} catch (err) {
 		console.log(`✗ ${err.message}`);
 		if (/not on the ticket branch|not pushed|uncommitted/i.test(err.message)) {
@@ -172,4 +210,4 @@ async function logout(config) {
 	console.log('✓ Disconnected this computer. (Remove it in Motionode Settings → Development workflow to revoke it there too.)');
 }
 
-module.exports = { login, link, connect, unlink, status, work, finish, logout };
+module.exports = { login, link, connect, unlink, status, work, finish, logout, worktreePath, finishLines };

package/lib/config.js

@@ -21,9 +21,33 @@ function normalizeApi(url) {
 	return String(url || '').trim().replace(/\/+$/, '') || null;
 }
 
-/** The API this run talks to: --api, then MOTIONODE_API_URL, then production. */
+const CURRENT_FILE = path.join(DIR, 'current.json');
+
+/** The Motionode chosen with `motionode use` (stays until changed). */
+function savedApi() {
+	try {
+		return normalizeApi(JSON.parse(fs.readFileSync(CURRENT_FILE, 'utf8')).apiUrl);
+	} catch (_e) {
+		return null;
+	}
+}
+
+/** `motionode use <url|production>` — which Motionode every terminal talks to. */
+function useApi(url) {
+	const next = String(url || '').trim().toLowerCase() === 'production' ? PRODUCTION_API : normalizeApi(url);
+	if (!next || !/^https?:\/\//.test(next)) throw new Error('Give a Motionode API address (https://…) or "production".');
+	fs.mkdirSync(DIR, { recursive: true });
+	if (next === PRODUCTION_API) {
+		try { fs.unlinkSync(CURRENT_FILE); } catch (_e) { /* already production */ }
+	} else {
+		fs.writeFileSync(CURRENT_FILE, JSON.stringify({ apiUrl: next }, null, 2));
+	}
+	return next;
+}
+
+/** The API this run talks to: --api, then MOTIONODE_API_URL, then `motionode use`, then production. */
 function resolveApi(override = null) {
-	return normalizeApi(override) || normalizeApi(process.env.MOTIONODE_API_URL) || PRODUCTION_API;
+	return normalizeApi(override) || normalizeApi(process.env.MOTIONODE_API_URL) || savedApi() || PRODUCTION_API;
 }
 
 function fileFor(apiUrl) {
@@ -63,4 +87,4 @@ function workspaceForPath(config, dir) {
 	return (config.workspaces || []).find((w) => samePath(w.path, dir)) || null;
 }
 
-module.exports = { DIR, PRODUCTION_API, resolveApi, fileFor, load, save, samePath, workspaceForPath };
+module.exports = { DIR, PRODUCTION_API, resolveApi, useApi, fileFor, load, save, samePath, workspaceForPath };

package/lib/git.js

@@ -112,6 +112,27 @@ async function checkout(dir, branch) {
 	return status(dir);
 }
 
+/**
+ * A separate folder (git worktree) on a ticket's branch, so two tickets of one repository never share a working tree.
+ * Reuses the folder when this ticket already has one. Returns { path, created }.
+ */
+async function worktreeFor(dir, branch, path) {
+	const fs = require('fs');
+	if (fs.existsSync(path)) {
+		const r = await run(path, ['rev-parse', '--abbrev-ref', 'HEAD'], { allowFail: true });
+		if (r.ok && String(r.stdout || '').trim() === branch) {
+			await run(path, ['fetch', 'origin', branch], { allowFail: true });
+			await run(path, ['merge', '--ff-only', `origin/${branch}`], { allowFail: true });
+			return { path, created: false };
+		}
+		throw new Error(`${path} exists and is not a checkout of ${branch}`);
+	}
+	await run(dir, ['fetch', 'origin', branch]);
+	if (await hasLocalBranch(dir, branch)) await run(dir, ['worktree', 'add', path, branch]);
+	else await run(dir, ['worktree', 'add', '--track', '-b', branch, path, `origin/${branch}`]);
+	return { path, created: true };
+}
+
 /** The uncommitted diff, including new files. */
 async function diff(dir, onlyPath = null) {
 	const args = ['diff', 'HEAD'];
@@ -178,4 +199,4 @@ async function moveChanges(dir, branch) {
 	return { moved: true, branch };
 }
 
-module.exports = { run, isRepo, remoteUrl, normalizeRepoUrl, status, checkout, diff, commit, moveChanges };
+module.exports = { run, isRepo, remoteUrl, normalizeRepoUrl, status, checkout, worktreeFor, diff, commit, moveChanges };

package/lib/git_credential.js

@@ -0,0 +1,134 @@
+'use strict';
+
+/**
+ * Git access to Motionode-hosted repositories, through Motionode.
+ *
+ * A Motionode-hosted repository lives privately in Motionode's GitHub organization, so your own GitHub account does not
+ * reach it. `motionode clone` clones it from this Motionode's git proxy (<api>/git/<owner>/<repo>.git) and sets this
+ * CLI as the clone's git credential helper: each time git needs to authenticate, the helper asks Motionode for a
+ * short-lived credential for that one repository, as the connected computer. Plain git (and Cursor, VS Code, Claude
+ * Code) then just works in that folder. Nothing is written to your global git config.
+ */
+
+const path = require('path');
+const { spawn } = require('child_process');
+const { client } = require('./api');
+
+/** git credential protocol: key=value lines. */
+function parseCredentialInput(raw) {
+	const out = {};
+	for (const line of String(raw || '').split(/\r?\n/)) {
+		const i = line.indexOf('=');
+		if (i > 0) out[line.slice(0, i)] = line.slice(i + 1);
+	}
+	return out;
+}
+
+function readStdin() {
+	return new Promise((resolve) => {
+		let data = '';
+		process.stdin.setEncoding('utf8');
+		process.stdin.on('data', (chunk) => { data += chunk; });
+		process.stdin.on('end', () => resolve(data));
+		process.stdin.on('error', () => resolve(data));
+	});
+}
+
+/** Whether a git credential request is for this Motionode's git proxy. */
+function isForThisMotionode(config, input) {
+	try {
+		const api = new URL(config.apiUrl);
+		return String(input.host || '').toLowerCase() === api.host.toLowerCase()
+			&& String(input.protocol || '').toLowerCase() === api.protocol.replace(/:$/, '');
+	} catch (_e) {
+		return false;
+	}
+}
+
+/**
+ * `motionode git-credential <get|store|erase>` — git runs this as the clone's credential helper. Only `get` answers;
+ * a request for any other host gets no answer, so git falls back to whatever else is configured.
+ */
+async function helper(config, operation, { input = null, out = process.stdout } = {}) {
+	if (operation !== 'get') return null;
+	const fields = parseCredentialInput(input == null ? await readStdin() : input);
+	if (!isForThisMotionode(config, fields) || !config.token) return null;
+	const pathname = String(fields.path || '').replace(/^\/+/, '');
+	if (!pathname.startsWith('git/')) return null;
+	try {
+		const { credential } = await client(config).post('/git-credential', { path: pathname });
+		out.write(`username=${credential.username}\npassword=${credential.password}\n`);
+	} catch (err) {
+		// git shows helper stderr; say why, then give no credential (git then reports the refusal).
+		process.stderr.write(`motionode: ${err.message}\n`);
+	}
+	return null;
+}
+
+/** The proxy address of a Motionode-hosted repository on this Motionode. */
+function proxyUrl(config, { owner, repo }) {
+	return `${String(config.apiUrl).replace(/\/+$/, '')}/git/${owner}/${String(repo).replace(/\.git$/, '')}.git`;
+}
+
+/** owner/repo of a github.com URL or an "owner/repo" string. */
+function ownerRepoOf(value) {
+	const m = String(value || '').trim().match(/(?:github\.com[/:])?([^/\s:]+)\/([^/\s]+?)(?:\.git)?\/?$/);
+	return m ? { owner: m[1], repo: m[2] } : null;
+}
+
+/** The git config that makes this CLI the credential helper for one folder (never global). */
+function helperConfig(config) {
+	const bin = path.resolve(__dirname, '..', 'bin', 'motionode.js');
+	const quote = (s) => `'${String(s).replace(/'/g, "'\\''")}'`;
+	return [
+		['credential.helper', ''],
+		['credential.helper', `!${quote(process.execPath)} ${quote(bin)} git-credential --api ${quote(config.apiUrl)}`],
+		['credential.useHttpPath', 'true'],
+	];
+}
+
+function git(args, { cwd = process.cwd() } = {}) {
+	return new Promise((resolve, reject) => {
+		const proc = spawn('git', args, { cwd, stdio: 'inherit' });
+		proc.on('error', reject);
+		proc.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`git ${args[0]} failed (exit ${code}).`))));
+	});
+}
+
+/**
+ * `motionode clone <service name | owner/repo> [dir]` — clone a Motionode-hosted repository through Motionode and
+ * keep this CLI as that folder's credential helper.
+ */
+async function clone(config, target, dir = null) {
+	if (!config.token) throw new Error('Connect this computer first: run `motionode connect`.');
+	if (!target) throw new Error('Usage: motionode clone <service name | owner/repo> [folder]');
+	let ref = String(target).includes('/') ? ownerRepoOf(target) : null;
+	if (!ref) {
+		const me = await client(config).get('/me');
+		const wanted = String(target).trim().toLowerCase();
+		const services = (me.projects || []).flatMap((p) => (p.services || []).map((s) => ({ ...s, project: p.name })));
+		const hits = services.filter((s) => s.hosting === 'motionode' && [s.name, s.uuid].map((v) => String(v || '').toLowerCase()).includes(wanted));
+		if (hits.length !== 1) {
+			throw new Error(hits.length
+				? `More than one service is called "${target}": ${hits.map((s) => `${s.name} (${s.project})`).join(', ')}. Use owner/repo.`
+				: `No Motionode-hosted service called "${target}" on your projects.`);
+		}
+		ref = ownerRepoOf(hits[0].repoUrl);
+		if (!ref) throw new Error(`"${target}" has no repository yet.`);
+	}
+	const folder = dir || ref.repo;
+	const settings = helperConfig(config);
+	const cloneArgs = [...settings.flatMap(([k, v]) => ['-c', `${k}=${v}`]), 'clone'];
+	await git([...cloneArgs, proxyUrl(config, ref), folder]);
+	// Keep the helper in the clone's own config, so later fetches and pulls authenticate the same way.
+	const cwd = path.resolve(folder);
+	await git(['config', '--local', '--unset-all', 'credential.helper'], { cwd }).catch(() => {});
+	for (const [k, v] of settings) {
+		// eslint-disable-next-line no-await-in-loop
+		await git(['config', '--local', '--add', k, v], { cwd });
+	}
+	console.log(`✓ Cloned ${ref.owner}/${ref.repo} into ${folder} through Motionode. Run \`motionode link\` inside it to tie it to your tickets.`);
+	return null;
+}
+
+module.exports = { helper, clone, parseCredentialInput, isForThisMotionode, proxyUrl, ownerRepoOf, helperConfig };