sibling-repo 0.1.0

package/.env.example

@@ -0,0 +1,17 @@
+# .env.example — copy to ~/.sibling-repo/.env and fill in
+
+# Sibling repositories: JSON map of short names to absolute paths
+# Example: {"api":"/home/you/repos/api","web":"/home/you/repos/web-app"}
+SIBLING_REPOS=
+
+# Claude subscription OAuth token (run: claude setup-token)
+CLAUDE_CODE_OAUTH_TOKEN=
+
+# Default models per agent mode
+# Options: haiku, sonnet, opus
+SIBLING_MODEL_EXPLORE=sonnet
+SIBLING_MODEL_PLAN=opus
+SIBLING_MODEL_EXECUTE=opus
+
+# Max agent turns before termination
+SIBLING_MAX_TURNS=50

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Delirio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,183 @@
+# sibling-repo
+
+[![npm version](https://img.shields.io/npm/v/sibling-repo.svg)](https://www.npmjs.com/package/sibling-repo)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+An MCP server that gives Claude Code agents the ability to spawn fully contextualized Claude Code sessions in sibling repositories. Ask questions about a backend API from your frontend repo, plan cross-repo implementations, or trigger changes in another codebase — all through a single tool call.
+
+## Quick Start
+
+```bash
+# 1. Generate an OAuth token from your Claude subscription
+claude setup-token
+# Copy the output token
+
+# 2. Create config directory and .env file
+mkdir -p ~/.sibling-repo
+cat > ~/.sibling-repo/.env << 'EOF'
+CLAUDE_CODE_OAUTH_TOKEN=<paste-your-token-here>
+SIBLING_REPOS={"backend":"/path/to/backend","frontend":"/path/to/frontend"}
+EOF
+
+# 3. Register with Claude Code (npx — no install needed)
+claude mcp add --scope user sibling-repo -- npx -y sibling-repo
+
+# 4. Launch Claude Code and try it
+claude
+> Use sibling-repo to explore the backend and find the check-in endpoint contract
+```
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────┐
+│  Claude Code session (e.g., in frontend repo)│
+│                                             │
+│  Agent calls: ask_repo("backend", prompt)   │
+│         │                                   │
+│         ▼                                   │
+│  ┌─────────────────────────┐                │
+│  │  sibling-repo MCP server│ (stdio)        │
+│  │  (Node.js process)      │                │
+│  └──────────┬──────────────┘                │
+│             │                               │
+└─────────────┼───────────────────────────────┘
+              │  Spawns via Claude Agent SDK
+              ▼
+┌─────────────────────────────────────────────┐
+│  Ephemeral Claude Code session              │
+│  cwd: ~/repos/backend                       │
+│  Loads backend's CLAUDE.md automatically    │
+│  Tools scoped by mode (explore/plan/execute)│
+│  Returns result to MCP server               │
+└─────────────────────────────────────────────┘
+```
+
+When you call `ask_repo`, sibling-repo spawns a real Claude Code session in the target repository using the [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview). The spawned agent loads the target repo's `CLAUDE.md`, has tools scoped to that directory, and operates in a configurable mode. From the calling agent's perspective, it's a single tool call that returns the sibling agent's answer.
+
+## Tools
+
+### `ask_repo`
+
+Spawn a Claude Code agent in a sibling repository.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `repo` | string | required | Repository short name from `SIBLING_REPOS` |
+| `prompt` | string | required | The task or question for the sibling agent |
+| `mode` | `"explore"` \| `"plan"` \| `"execute"` | `"explore"` | Agent mode |
+| `model` | string | per-mode default | Model override: `"haiku"`, `"sonnet"`, `"opus"` |
+
+### `list_repos`
+
+Returns the configured repositories and their paths. No parameters.
+
+## Agent Modes
+
+| Mode | Default Model | Tools | Purpose |
+|------|--------------|-------|---------|
+| **explore** | sonnet | Read, Grep, Glob, Bash (read-only) | Codebase investigation — find endpoints, schemas, architecture |
+| **plan** | opus | Read, Grep, Glob, Bash (read-only) | Design implementation plans without making changes |
+| **execute** | opus | Read, Grep, Glob, Bash, Write, Edit, MultiEdit | Make changes in the sibling repo |
+
+## Configuration
+
+sibling-repo reads from a `.env` file, searched in order:
+
+1. `SIBLING_ENV_PATH` environment variable (explicit override)
+2. `~/.sibling-repo/.env` (user-level default)
+3. `./.env` (current directory)
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `SIBLING_REPOS` | Yes | — | JSON map of repo names to absolute paths |
+| `CLAUDE_CODE_OAUTH_TOKEN` | Yes | — | OAuth token from `claude setup-token` |
+| `SIBLING_MODEL_EXPLORE` | No | `sonnet` | Default model for explore mode |
+| `SIBLING_MODEL_PLAN` | No | `opus` | Default model for plan mode |
+| `SIBLING_MODEL_EXECUTE` | No | `opus` | Default model for execute mode |
+| `SIBLING_MAX_TURNS` | No | `50` | Max agent turns before termination |
+
+### `SIBLING_REPOS` format
+
+A JSON object mapping short names (used in tool calls) to absolute paths:
+
+```json
+{
+  "backend": "/Users/you/repos/api-server",
+  "frontend": "/Users/you/repos/web-app",
+  "shared": "/Users/you/repos/shared-lib"
+}
+```
+
+Paths support `~` and `$HOME` expansion. Missing paths produce a startup warning but don't prevent the server from running.
+
+## Usage Examples
+
+**Explore a backend API from the frontend:**
+```
+ask_repo("backend", "What is the HTTP method, path, request body, and response shape for the user check-in endpoint?")
+```
+
+**Plan a cross-repo feature:**
+```
+ask_repo("backend", "Design a new GET endpoint at /api/v1/workouts/history that returns the user's last 30 workout sessions. Follow existing route patterns.", "plan")
+```
+
+**Execute changes in a sibling repo:**
+```
+ask_repo("backend", "Create a new GET endpoint at /api/v1/workouts/history that returns the user's last 30 sessions from Firestore.", "execute")
+```
+
+## Development
+
+```bash
+# Clone and build
+git clone https://github.com/AmirAlsad/sibling-repo.git
+cd sibling-repo
+npm install
+npm run build
+
+# Run tests
+npm test
+
+# Register local build with Claude Code
+claude mcp add --scope user sibling-repo -- node ./dist/server.js
+
+# Development with auto-reload
+npm run dev
+```
+
+### Project Structure
+
+```
+src/
+  server.ts      MCP server entry point, tool registration
+  agent.ts       Claude Agent SDK wrapper, mode configurations
+  prompts.ts     System prompt constants (explore/plan/execute)
+  config.ts      .env loading, SIBLING_REPOS parsing, path validation
+  types.ts       Shared TypeScript types
+tests/
+  config.test.ts Config parsing, path resolution, defaults
+  agent.test.ts  Mode configs, result extraction, error handling
+  server.test.ts MCP integration tests via stdio client transport
+```
+
+## Troubleshooting
+
+**"SIBLING_REPOS is not set"**
+Create `~/.sibling-repo/.env` with your repo configuration. See [Configuration](#configuration).
+
+**"Authentication failed"**
+Run `claude setup-token` to generate a fresh OAuth token and update your `.env` file. Ensure `ANTHROPIC_API_KEY` is not set in your shell (it takes precedence over OAuth).
+
+**"Repo path does not exist"**
+Check the path in your `SIBLING_REPOS` configuration. Paths must be absolute. `~` and `$HOME` are expanded automatically.
+
+**Agent returns no result**
+The spawned agent may have hit `SIBLING_MAX_TURNS`. Increase the limit in your `.env` or write a more specific prompt.
+
+## License
+
+[MIT](LICENSE)

package/dist/agent.d.ts

@@ -0,0 +1,2 @@
+import type { AgentMode } from "./types.js";
+export declare function runAgent(repoPath: string, prompt: string, mode: AgentMode, model: string, maxTurns: number): Promise<string>;

package/dist/agent.js

@@ -0,0 +1,77 @@
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { EXPLORE_PROMPT, PLAN_PROMPT, EXECUTE_PROMPT } from "./prompts.js";
+const MODE_CONFIGS = {
+    explore: {
+        allowedTools: ["Read", "Grep", "Glob", "Bash"],
+        disallowedTools: ["Write", "Edit", "MultiEdit"],
+        permissionMode: "bypassPermissions",
+        allowDangerouslySkipPermissions: true,
+        defaultModel: "sonnet",
+        systemPromptAppend: EXPLORE_PROMPT,
+    },
+    plan: {
+        allowedTools: ["Read", "Grep", "Glob", "Bash"],
+        disallowedTools: ["Write", "Edit", "MultiEdit"],
+        permissionMode: "plan",
+        allowDangerouslySkipPermissions: false,
+        defaultModel: "opus",
+        systemPromptAppend: PLAN_PROMPT,
+    },
+    execute: {
+        allowedTools: ["Read", "Grep", "Glob", "Bash", "Write", "Edit", "MultiEdit"],
+        disallowedTools: [],
+        permissionMode: "acceptEdits",
+        allowDangerouslySkipPermissions: false,
+        defaultModel: "opus",
+        systemPromptAppend: EXECUTE_PROMPT,
+    },
+};
+export async function runAgent(repoPath, prompt, mode, model, maxTurns) {
+    const config = MODE_CONFIGS[mode];
+    const options = {
+        cwd: repoPath,
+        systemPrompt: {
+            type: "preset",
+            preset: "claude_code",
+            append: config.systemPromptAppend,
+        },
+        allowedTools: config.allowedTools,
+        disallowedTools: config.disallowedTools,
+        permissionMode: config.permissionMode,
+        model,
+        maxTurns,
+    };
+    if (config.allowDangerouslySkipPermissions) {
+        options.allowDangerouslySkipPermissions = true;
+    }
+    try {
+        let result = "";
+        for await (const message of query({ prompt, options })) {
+            if (message.type === "result") {
+                if ("result" in message) {
+                    result = message.result;
+                }
+                else if ("errors" in message) {
+                    const errors = message.errors.join("; ");
+                    throw new Error(`Agent error (${message.subtype}): ${errors}`);
+                }
+            }
+        }
+        if (!result) {
+            throw new Error("Agent returned no result");
+        }
+        return result;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes("auth") ||
+            msg.includes("token") ||
+            msg.includes("unauthorized") ||
+            msg.includes("401")) {
+            throw new Error(`Authentication failed. Run \`claude setup-token\` to generate a new OAuth token ` +
+                `and add it to your .env file as CLAUDE_CODE_OAUTH_TOKEN. Original error: ${msg}`);
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,gCAAgC,CAAC;AAEvD,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE3E,MAAM,YAAY,GAAkC;IAClD,OAAO,EAAE;QACP,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;QAC9C,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC;QAC/C,cAAc,EAAE,mBAAmB;QACnC,+BAA+B,EAAE,IAAI;QACrC,YAAY,EAAE,QAAQ;QACtB,kBAAkB,EAAE,cAAc;KACnC;IACD,IAAI,EAAE;QACJ,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;QAC9C,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC;QAC/C,cAAc,EAAE,MAAM;QACtB,+BAA+B,EAAE,KAAK;QACtC,YAAY,EAAE,MAAM;QACpB,kBAAkB,EAAE,WAAW;KAChC;IACD,OAAO,EAAE;QACP,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC;QAC5E,eAAe,EAAE,EAAE;QACnB,cAAc,EAAE,aAAa;QAC7B,+BAA+B,EAAE,KAAK;QACtC,YAAY,EAAE,MAAM;QACpB,kBAAkB,EAAE,cAAc;KACnC;CACF,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,QAAgB,EAChB,MAAc,EACd,IAAe,EACf,KAAa,EACb,QAAgB;IAEhB,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAElC,MAAM,OAAO,GAA2C;QACtD,GAAG,EAAE,QAAQ;QACb,YAAY,EAAE;YACZ,IAAI,EAAE,QAAiB;YACvB,MAAM,EAAE,aAAsB;YAC9B,MAAM,EAAE,MAAM,CAAC,kBAAkB;SAClC;QACD,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,eAAe,EAAE,MAAM,CAAC,eAAe;QACvC,cAAc,EAAE,MAAM,CAAC,cAA0E;QACjG,KAAK;QACL,QAAQ;KACT,CAAC;IAEF,IAAI,MAAM,CAAC,+BAA+B,EAAE,CAAC;QAC3C,OAAO,CAAC,+BAA+B,GAAG,IAAI,CAAC;IACjD,CAAC;IAED,IAAI,CAAC;QACH,IAAI,MAAM,GAAG,EAAE,CAAC;QAEhB,IAAI,KAAK,EAAE,MAAM,OAAO,IAAI,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;YACvD,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC9B,IAAI,QAAQ,IAAI,OAAO,EAAE,CAAC;oBACxB,MAAM,GAAG,OAAO,CAAC,MAAgB,CAAC;gBACpC,CAAC;qBAAM,IAAI,QAAQ,IAAI,OAAO,EAAE,CAAC;oBAC/B,MAAM,MAAM,GAAI,OAAO,CAAC,MAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBACvD,MAAM,IAAI,KAAK,CAAC,gBAAgB,OAAO,CAAC,OAAO,MAAM,MAAM,EAAE,CAAC,CAAC;gBACjE,CAAC;YACH,CAAC;QACH,CAAC;QAED,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;QAC9C,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAE7D,IACE,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC;YACpB,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC;YACrB,GAAG,CAAC,QAAQ,CAAC,cAAc,CAAC;YAC5B,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,EACnB,CAAC;YACD,MAAM,IAAI,KAAK,CACb,kFAAkF;gBAChF,4EAA4E,GAAG,EAAE,CACpF,CAAC;QACJ,CAAC;QAED,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,2 @@
+import type { SiblingConfig } from "./types.js";
+export declare function loadConfig(): SiblingConfig;

package/dist/config.js

@@ -0,0 +1,70 @@
+import { config as dotenvConfig } from "dotenv";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+function resolvePath(rawPath) {
+    const home = homedir();
+    if (rawPath.startsWith("~/")) {
+        return join(home, rawPath.slice(2));
+    }
+    return rawPath.replace(/\$HOME/g, home);
+}
+function findEnvFile() {
+    const candidates = [
+        process.env.SIBLING_ENV_PATH,
+        join(homedir(), ".sibling-repo", ".env"),
+        join(process.cwd(), ".env"),
+    ];
+    for (const candidate of candidates) {
+        if (candidate && existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+export function loadConfig() {
+    const envPath = findEnvFile();
+    if (envPath) {
+        dotenvConfig({ path: envPath });
+        console.error(`[sibling-repo] Loaded config from ${envPath}`);
+    }
+    else {
+        console.error("[sibling-repo] No .env file found. Checking environment variables...");
+    }
+    const rawRepos = process.env.SIBLING_REPOS;
+    if (!rawRepos) {
+        throw new Error('SIBLING_REPOS is not set. Create ~/.sibling-repo/.env with:\n' +
+            'SIBLING_REPOS={"backend":"/path/to/backend","frontend":"/path/to/frontend"}\n' +
+            "See README.md for setup instructions.");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawRepos);
+    }
+    catch {
+        throw new Error(`SIBLING_REPOS is not valid JSON: ${rawRepos}\n` +
+            'Expected format: {"name":"/absolute/path"}');
+    }
+    const repos = new Map();
+    for (const [name, rawPath] of Object.entries(parsed)) {
+        const resolvedPath = resolvePath(rawPath);
+        const pathExists = existsSync(resolvedPath);
+        const hasCLAUDEmd = pathExists && existsSync(join(resolvedPath, "CLAUDE.md"));
+        if (!pathExists) {
+            console.error(`[sibling-repo] Warning: repo "${name}" path does not exist: ${resolvedPath}`);
+        }
+        else {
+            console.error(`[sibling-repo] Registered repo "${name}" → ${resolvedPath}${hasCLAUDEmd ? " (has CLAUDE.md)" : ""}`);
+        }
+        repos.set(name, { name, path: resolvedPath, hasCLAUDEmd });
+    }
+    const models = {
+        explore: process.env.SIBLING_MODEL_EXPLORE ?? "sonnet",
+        plan: process.env.SIBLING_MODEL_PLAN ?? "opus",
+        execute: process.env.SIBLING_MODEL_EXECUTE ?? "opus",
+    };
+    const maxTurns = parseInt(process.env.SIBLING_MAX_TURNS ?? "50", 10);
+    console.error(`[sibling-repo] ${repos.size} repo(s) configured, maxTurns=${maxTurns}`);
+    return { repos, models, maxTurns };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/prompts.d.ts

@@ -0,0 +1,3 @@
+export declare const EXPLORE_PROMPT = "You are a file search specialist. You excel at thoroughly navigating and exploring codebases.\n\n=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===\nThis is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:\n- Creating new files (no Write, touch, or file creation of any kind)\n- Modifying existing files (no Edit operations)\n- Deleting files (no rm or deletion)\n- Moving or copying files (no mv or cp)\n- Creating temporary files anywhere, including /tmp\n- Using redirect operators (>, >>, |) or heredocs to write to files\n- Running ANY commands that change system state\n\nYour role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools \u2014 attempting to edit files will fail.\n\nYour strengths:\n- Rapidly finding files using glob patterns\n- Searching code and text with powerful regex patterns\n- Reading and analyzing file contents\n\nUse Bash ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail).\nNEVER use Bash for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification.\n\nWhen reporting API endpoints, include: HTTP method, path, request body shape, response shape. When reporting data models, include: collection/table name, field names and types, relationships.\n\nComplete the search request efficiently and report your findings clearly and concisely.";
+export declare const PLAN_PROMPT = "You are a software architect and planning specialist. Your role is to explore the codebase and design implementation plans.\n\n=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===\nThis is a READ-ONLY planning task. You are STRICTLY PROHIBITED from:\n- Creating new files (no Write, touch, or file creation of any kind)\n- Modifying existing files (no Edit operations)\n- Deleting files (no rm or deletion)\n- Moving or copying files (no mv or cp)\n- Creating temporary files anywhere, including /tmp\n- Using redirect operators (>, >>, |) or heredocs to write to files\n- Running ANY commands that change system state\n\nYour role is EXCLUSIVELY to explore the codebase and design implementation plans. You do NOT have access to file editing tools \u2014 attempting to edit files will fail.\n\nProcess:\n1. Understand Requirements: Focus on the requirements provided and apply your analysis throughout the design process.\n2. Find existing patterns and conventions using Glob, Grep, and Read tools.\n3. Design a plan that follows the project's established conventions (informed by CLAUDE.md if present).\n\nYour plan should include:\n- Files to create or modify (with paths)\n- The changes needed in each file (described precisely, with code snippets)\n- Any new dependencies required\n- Testing considerations\n- Order of operations (what to do first)\n\nFormat the plan as a markdown document that another developer or agent could follow step-by-step.";
+export declare const EXECUTE_PROMPT = "You are a code implementation specialist. You have full read-write access to this repository.\n\nMake the requested changes following the project's existing conventions (see CLAUDE.md if present). Write clean, idiomatic code that matches the patterns already established in the codebase.\n\nAfter making changes:\n1. Verify your changes compile/parse correctly if applicable\n2. Summarize exactly what you changed (files modified, created, deleted)\n3. Note any follow-up actions needed in other repos";

package/dist/prompts.js

@@ -0,0 +1,61 @@
+export const EXPLORE_PROMPT = `You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+
+=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
+This is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:
+- Creating new files (no Write, touch, or file creation of any kind)
+- Modifying existing files (no Edit operations)
+- Deleting files (no rm or deletion)
+- Moving or copying files (no mv or cp)
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools — attempting to edit files will fail.
+
+Your strengths:
+- Rapidly finding files using glob patterns
+- Searching code and text with powerful regex patterns
+- Reading and analyzing file contents
+
+Use Bash ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail).
+NEVER use Bash for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification.
+
+When reporting API endpoints, include: HTTP method, path, request body shape, response shape. When reporting data models, include: collection/table name, field names and types, relationships.
+
+Complete the search request efficiently and report your findings clearly and concisely.`;
+export const PLAN_PROMPT = `You are a software architect and planning specialist. Your role is to explore the codebase and design implementation plans.
+
+=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
+This is a READ-ONLY planning task. You are STRICTLY PROHIBITED from:
+- Creating new files (no Write, touch, or file creation of any kind)
+- Modifying existing files (no Edit operations)
+- Deleting files (no rm or deletion)
+- Moving or copying files (no mv or cp)
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Your role is EXCLUSIVELY to explore the codebase and design implementation plans. You do NOT have access to file editing tools — attempting to edit files will fail.
+
+Process:
+1. Understand Requirements: Focus on the requirements provided and apply your analysis throughout the design process.
+2. Find existing patterns and conventions using Glob, Grep, and Read tools.
+3. Design a plan that follows the project's established conventions (informed by CLAUDE.md if present).
+
+Your plan should include:
+- Files to create or modify (with paths)
+- The changes needed in each file (described precisely, with code snippets)
+- Any new dependencies required
+- Testing considerations
+- Order of operations (what to do first)
+
+Format the plan as a markdown document that another developer or agent could follow step-by-step.`;
+export const EXECUTE_PROMPT = `You are a code implementation specialist. You have full read-write access to this repository.
+
+Make the requested changes following the project's existing conventions (see CLAUDE.md if present). Write clean, idiomatic code that matches the patterns already established in the codebase.
+
+After making changes:
+1. Verify your changes compile/parse correctly if applicable
+2. Summarize exactly what you changed (files modified, created, deleted)
+3. Note any follow-up actions needed in other repos`;
+//# sourceMappingURL=prompts.js.map

package/dist/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;wFAwB0D,CAAC;AAEzF,MAAM,CAAC,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;kGA0BuE,CAAC;AAEnG,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;oDAOsB,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/server.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { existsSync } from "node:fs";
+import { loadConfig } from "./config.js";
+import { runAgent } from "./agent.js";
+async function main() {
+    const config = loadConfig();
+    const repoNames = Array.from(config.repos.keys());
+    const repoListStr = repoNames.join(", ");
+    const server = new McpServer({
+        name: "sibling-repo",
+        version: "0.1.0",
+    });
+    server.tool("ask_repo", `Spawn a Claude Code agent in a sibling repository to explore code, plan implementations, or execute changes. Use this when you need to understand APIs, schemas, architecture, or conventions from another repo in this project.
+
+Available repos: ${repoListStr}
+
+Modes:
+- explore: Read-only investigation. Use for questions about endpoints, schemas, architecture, conventions, or "how does X work" queries.
+- plan: Generate an implementation plan without writing code. Use when you need a step-by-step plan for changes in the sibling repo.
+- execute: Read-write. Actually make changes in the sibling repo. Use when you need the sibling repo to implement something.`, {
+        repo: z.string().describe("Repository short name from SIBLING_REPOS"),
+        prompt: z.string().describe("The task or question for the sibling agent"),
+        mode: z
+            .enum(["explore", "plan", "execute"])
+            .default("explore")
+            .describe("Agent mode: explore (read-only), plan (design), execute (read-write)"),
+        model: z
+            .string()
+            .optional()
+            .describe('Model override: "haiku", "sonnet", "opus"'),
+    }, async ({ repo, prompt, mode, model }) => {
+        const entry = config.repos.get(repo);
+        if (!entry) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Unknown repo "${repo}". Available repos: ${repoListStr}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        if (!existsSync(entry.path)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Repo path does not exist: ${entry.path}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const resolvedModel = model ?? config.models[mode];
+        if (mode === "execute") {
+            console.error(`[sibling-repo] EXECUTE mode invoked on "${repo}" at ${entry.path}`);
+        }
+        try {
+            const result = await runAgent(entry.path, prompt, mode, resolvedModel, config.maxTurns);
+            return {
+                content: [{ type: "text", text: result }],
+            };
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Agent error: ${errorMessage}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("list_repos", "List all configured sibling repositories and their paths.", {}, async () => {
+        const repos = Array.from(config.repos.values()).map((r) => ({
+            name: r.name,
+            path: r.path,
+            has_claude_md: r.hasCLAUDEmd,
+        }));
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(repos, null, 2) },
+            ],
+        };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("[sibling-repo] MCP server running on stdio");
+}
+main().catch((err) => {
+    console.error("[sibling-repo] Fatal:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,23 @@
+export type AgentMode = "explore" | "plan" | "execute";
+export interface RepoEntry {
+    name: string;
+    path: string;
+    hasCLAUDEmd: boolean;
+}
+export interface ModeConfig {
+    allowedTools: string[];
+    disallowedTools: string[];
+    permissionMode: string;
+    allowDangerouslySkipPermissions: boolean;
+    defaultModel: string;
+    systemPromptAppend: string;
+}
+export interface SiblingConfig {
+    repos: Map<string, RepoEntry>;
+    models: {
+        explore: string;
+        plan: string;
+        execute: string;
+    };
+    maxTurns: number;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "sibling-repo",
+  "version": "0.1.0",
+  "description": "MCP server that spawns Claude Code agents in sibling repositories",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/server.js",
+  "bin": {
+    "sibling-repo": "./dist/server.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE",
+    ".env.example"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/server.js",
+    "dev": "tsx --watch src/server.ts",
+    "start": "node dist/server.js",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "mcp",
+    "claude-code",
+    "multi-repo",
+    "agent-sdk",
+    "cross-repository"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AmirAlsad/sibling-repo"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.0",
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "dotenv": "^16.4.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.2"
+  }
+}