agentloom 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agentloom contributors
+
+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,234 @@
+# agentloom
+
+`agentloom` is a unified CLI for managing agent definitions and MCP configuration across multiple AI coding tools.
+
+It uses `.agents` as the canonical source of truth and syncs provider-native files for:
+
+- Cursor
+- Claude
+- Codex
+- OpenCode
+- Gemini
+- Copilot
+
+## Install
+
+```bash
+npm i -g agentloom
+# or
+npx agentloom --help
+```
+
+## Canonical layout
+
+Project scope:
+
+```text
+.agents/
+  agents/
+    reviewer.md
+    debugger.md
+  mcp.json
+  agents.lock.json
+  settings.local.json
+```
+
+Global scope uses `~/.agents` with the same file layout.
+
+## Commands
+
+### `agentloom skills ...`
+Pass-through wrapper to `npx skills ...` from
+[`vercel-labs/skills`](https://github.com/vercel-labs/skills).
+
+### `agentloom add <source>`
+Import canonical agents/MCP from:
+
+- local repo path
+- GitHub slug (`owner/repo`)
+- generic git URL
+
+Options:
+
+- `--ref <ref>`: git ref (branch/tag/commit) for remote sources
+- `--subdir <path>`: subdirectory inside source repo
+- `--rename <name>`: rename imported agent when importing a single agent
+- `--local | --global`: choose destination scope
+- `--yes`: skip interactive conflict prompts
+- `--no-sync`: skip post-import sync
+- `--providers <csv>`: limit post-import sync providers
+- `--dry-run`: show sync changes without writing provider files
+
+Example:
+
+```bash
+agentloom add vercel-labs/skills --subdir skills
+```
+
+### `agentloom update`
+Refresh lockfile sources (`agents.lock.json`) and re-import changed revisions.
+
+Options:
+
+- `--local | --global`: choose lockfile scope
+- `--yes`: skip conflict prompts during re-import
+- `--no-sync`: skip post-update sync
+- `--providers <csv>`: limit post-update sync providers
+- `--dry-run`: show sync changes without writing provider files
+
+### `agentloom sync`
+Generate provider-specific outputs from canonical `.agents` data.
+
+Options:
+
+- `--local | --global`: choose canonical scope
+- `--providers <csv>`: limit sync providers
+- `--yes`: auto-delete stale generated files
+- `--dry-run`: show planned changes without writing files
+
+Example:
+
+```bash
+agentloom sync --providers codex,claude,cursor
+```
+
+### `agentloom mcp add|list|delete`
+Manage canonical MCP servers in `.agents/mcp.json`.
+
+`mcp add` options:
+
+- `--url <url>` or `--command <cmd>`: required transport config
+- `--arg <value>`: repeatable command arg
+- `--env KEY=VALUE`: repeatable environment variable
+- `--providers <csv>`: provider-specific assignment
+- `--local | --global`: choose canonical scope
+- `--no-sync`: skip post-change sync
+
+`mcp list` options:
+
+- `--json`: print raw canonical JSON
+- `--local | --global`: choose canonical scope
+
+`mcp delete` options:
+
+- `--local | --global`: choose canonical scope
+- `--no-sync`: skip post-change sync
+
+Examples:
+
+```bash
+agentloom mcp add browser-tools --command npx --arg browser-tools-mcp
+agentloom mcp list
+agentloom mcp delete browser-tools
+```
+
+### Top-level help
+
+```bash
+agentloom --help
+agentloom add --help
+agentloom update --help
+agentloom sync --help
+agentloom mcp --help
+agentloom mcp add --help
+```
+
+### Version update notice
+
+`agentloom` now performs a best-effort npm version check and shows an update hint when a newer release is available.
+
+- check is cached (`~/.agents/.agentloom-version-cache.json`)
+- check runs at most once every 12 hours
+- check is skipped in non-interactive sessions
+- disable via:
+
+```bash
+AGENTLOOM_DISABLE_UPDATE_NOTIFIER=1
+```
+
+### Scope resolution
+
+If neither `--local` nor `--global` is provided:
+
+- if `.agents/` exists in current directory, `agentloom` prompts for scope in interactive terminals
+- in non-interactive mode, local scope is selected when `.agents/` exists
+- otherwise global scope (`~/.agents`) is used
+
+## Agent schema
+
+Canonical agents are markdown files with YAML frontmatter.
+
+```md
+---
+name: code-reviewer
+description: Review changes and report issues.
+claude:
+  model: sonnet
+codex:
+  model: gpt-5.3-codex
+  reasoningEffort: low
+  webSearch: true
+---
+
+You are a strict reviewer...
+```
+
+## MCP schema
+
+Canonical MCP file format:
+
+```json
+{
+  "version": 1,
+  "mcpServers": {
+    "browser": {
+      "base": {
+        "command": "npx",
+        "args": ["browser-tools-mcp"]
+      },
+      "providers": {
+        "codex": {
+          "args": ["browser-tools-mcp", "--codex"]
+        },
+        "gemini": false
+      }
+    }
+  }
+}
+```
+
+## Codex multi-agent output
+
+For Codex, `agentloom sync` writes role-based multi-agent config:
+
+- `.codex/config.toml` (`[features].multi_agent = true`, `[agents.<role>]`)
+- `.codex/agents/<role>.toml`
+- `.codex/agents/<role>.instructions.md`
+
+This follows official Codex multi-agent guidance.
+
+## Development
+
+```bash
+pnpm install
+pnpm check
+pnpm build
+```
+
+## Release and publish
+
+The GitHub Actions publish workflow is defined in `.github/workflows/release.yml`.
+
+- Push to `main` with `[patch]` or `[minor]` in commit subjects to trigger an automated npm release.
+- Run the workflow manually (`workflow_dispatch`) and choose `patch` or `minor` to force a release.
+- Push a `v*` tag (for example `v0.2.0`) to publish an already-versioned commit without bumping.
+- Automated bump releases create a `vX.Y.Z` commit/tag via `npm version`, push both to GitHub, then publish to npm with provenance.
+
+Required GitHub configuration:
+
+- Secret: `NPM_TOKEN` (automation token from the npm account that should own `agentloom`).
+- Repository setting: `Actions -> General -> Workflow permissions -> Read and write permissions` (required so CI can push version commits/tags).
+
+## License
+
+MIT

package/ThirdPartyNoticeText.txt

@@ -0,0 +1,3 @@
+This project depends on third-party open source packages.
+
+See package.json and lockfile for full dependency list and licenses.

package/bin/cli.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runCli } from '../dist/cli.js';
+
+runCli(process.argv.slice(2)).catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function runCli(argv: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,61 @@
+import { parseArgs } from "./core/argv.js";
+import { runAddCommand } from "./commands/add.js";
+import { runMcpCommand } from "./commands/mcp.js";
+import { runSkillsPassthrough } from "./commands/skills.js";
+import { runSyncCommand } from "./commands/sync.js";
+import { runUpdateCommand } from "./commands/update.js";
+import { formatUnknownCommandError, getRootHelpText } from "./core/copy.js";
+import { maybeNotifyVersionUpdate } from "./core/version-notifier.js";
+import { getCliVersion } from "./core/version.js";
+export async function runCli(argv) {
+    const command = argv[0];
+    const version = getCliVersion();
+    if (!command ||
+        command === "help" ||
+        command === "--help" ||
+        command === "-h") {
+        printHelp();
+        return;
+    }
+    if (command === "--version" || command === "-v" || command === "version") {
+        console.log(version);
+        return;
+    }
+    if (command === "skills") {
+        runSkillsPassthrough(argv.slice(1));
+        return;
+    }
+    const parsed = parseArgs(argv);
+    const cwd = process.cwd();
+    if (!parsed.help) {
+        await maybeNotifyVersionUpdate({
+            command,
+            currentVersion: version,
+        });
+    }
+    switch (command) {
+        case "add":
+            await runAddCommand(parsed, cwd);
+            return;
+        case "update":
+            await runUpdateCommand(parsed, cwd);
+            return;
+        case "sync":
+            await runSyncCommand(parsed, cwd);
+            return;
+        case "mcp":
+            await runMcpCommand(parsed, cwd);
+            return;
+        default:
+            throw new Error(formatUnknownCommandError(command));
+    }
+}
+function printHelp() {
+    console.log(getRootHelpText());
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    runCli(process.argv.slice(2)).catch((err) => {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    });
+}

package/dist/commands/add.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedArgs } from "minimist";
+export declare function runAddCommand(argv: ParsedArgs, cwd: string): Promise<void>;

package/dist/commands/add.js

@@ -0,0 +1,62 @@
+import { importSource, NonInteractiveConflictError } from "../core/importer.js";
+import { resolveScope } from "../core/scope.js";
+import { updateLastScope } from "../core/settings.js";
+import { parseProvidersFlag } from "../core/argv.js";
+import { formatUsageError, getAddHelpText } from "../core/copy.js";
+import { formatSyncSummary, syncFromCanonical } from "../sync/index.js";
+export async function runAddCommand(argv, cwd) {
+    if (argv.help) {
+        console.log(getAddHelpText());
+        return;
+    }
+    const source = argv._[1];
+    if (typeof source !== "string" || source.trim() === "") {
+        throw new Error(formatUsageError({
+            issue: "Missing required <source>.",
+            usage: "agentloom add <source> [--ref <ref>] [--subdir <path>] [options]",
+            example: "agentloom add vercel-labs/skills --subdir skills",
+        }));
+    }
+    const nonInteractive = !(process.stdin.isTTY && process.stdout.isTTY);
+    const paths = await resolveScope({
+        cwd,
+        global: Boolean(argv.global),
+        local: Boolean(argv.local),
+        interactive: !nonInteractive,
+    });
+    try {
+        const summary = await importSource({
+            source,
+            ref: typeof argv.ref === "string" ? argv.ref : undefined,
+            subdir: typeof argv.subdir === "string" ? argv.subdir : undefined,
+            rename: typeof argv.rename === "string" ? argv.rename : undefined,
+            yes: Boolean(argv.yes),
+            nonInteractive,
+            paths,
+        });
+        console.log(`Imported source: ${summary.source}`);
+        console.log(`Source type: ${summary.sourceType}`);
+        console.log(`Resolved commit: ${summary.resolvedCommit}`);
+        console.log(`Imported agents: ${summary.importedAgents.length}`);
+        console.log(`Imported MCP servers: ${summary.importedMcpServers.length}`);
+        updateLastScope(paths.settingsPath, paths.scope);
+        if (!argv["no-sync"]) {
+            const syncSummary = await syncFromCanonical({
+                paths,
+                providers: parseProvidersFlag(argv.providers),
+                yes: Boolean(argv.yes),
+                nonInteractive,
+                dryRun: Boolean(argv["dry-run"]),
+            });
+            console.log("");
+            console.log(formatSyncSummary(syncSummary, paths.agentsRoot));
+        }
+    }
+    catch (err) {
+        if (err instanceof NonInteractiveConflictError) {
+            console.error(err.message);
+            process.exit(2);
+        }
+        throw err;
+    }
+}

package/dist/commands/mcp.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedArgs } from "minimist";
+export declare function runMcpCommand(argv: ParsedArgs, cwd: string): Promise<void>;

package/dist/commands/mcp.js

@@ -0,0 +1,188 @@
+import { getStringArrayFlag, parseProvidersFlag } from "../core/argv.js";
+import { formatUsageError, getMcpAddHelpText, getMcpDeleteHelpText, getMcpHelpText, getMcpListHelpText, } from "../core/copy.js";
+import { readCanonicalMcp, writeCanonicalMcp } from "../core/mcp.js";
+import { resolveScope } from "../core/scope.js";
+import { formatSyncSummary, syncFromCanonical } from "../sync/index.js";
+export async function runMcpCommand(argv, cwd) {
+    const action = argv._[1];
+    if (argv.help) {
+        if (action === "add") {
+            console.log(getMcpAddHelpText());
+            return;
+        }
+        if (action === "list") {
+            console.log(getMcpListHelpText());
+            return;
+        }
+        if (action === "delete") {
+            console.log(getMcpDeleteHelpText());
+            return;
+        }
+        console.log(getMcpHelpText());
+        return;
+    }
+    if (action !== "add" && action !== "list" && action !== "delete") {
+        throw new Error(formatUsageError({
+            issue: "Invalid mcp command.",
+            usage: "agentloom mcp <add|list|delete> [options]",
+            example: "agentloom mcp add browser --command npx --arg browser-tools-mcp",
+        }));
+    }
+    const nonInteractive = !(process.stdin.isTTY && process.stdout.isTTY);
+    const paths = await resolveScope({
+        cwd,
+        global: Boolean(argv.global),
+        local: Boolean(argv.local),
+        interactive: !nonInteractive,
+    });
+    if (action === "list") {
+        runMcpList(paths, Boolean(argv.json));
+        return;
+    }
+    if (action === "add") {
+        const name = argv._[2];
+        if (typeof name !== "string" || !name.trim()) {
+            throw new Error(formatUsageError({
+                issue: "Missing required MCP server name.",
+                usage: "agentloom mcp add <name> (--url <url> | --command <cmd>) [options]",
+                example: "agentloom mcp add browser --command npx --arg browser-tools-mcp",
+            }));
+        }
+        runMcpAdd(paths, argv, name.trim());
+        if (!argv["no-sync"]) {
+            const summary = await syncFromCanonical({
+                paths,
+                providers: parseProvidersFlag(argv.providers),
+                yes: Boolean(argv.yes),
+                nonInteractive,
+            });
+            console.log("");
+            console.log(formatSyncSummary(summary, paths.agentsRoot));
+        }
+        return;
+    }
+    if (action === "delete") {
+        const name = argv._[2];
+        if (typeof name !== "string" || !name.trim()) {
+            throw new Error(formatUsageError({
+                issue: "Missing required MCP server name.",
+                usage: "agentloom mcp delete <name> [options]",
+                example: "agentloom mcp delete browser",
+            }));
+        }
+        const mcp = readCanonicalMcp(paths);
+        if (!(name in mcp.mcpServers)) {
+            throw new Error(formatUsageError({
+                issue: `MCP server "${name}" was not found in canonical config.`,
+                usage: "agentloom mcp list [--json] [--local|--global]",
+                example: "agentloom mcp list --json",
+            }));
+        }
+        delete mcp.mcpServers[name];
+        writeCanonicalMcp(paths, mcp);
+        console.log(`Deleted MCP server: ${name}`);
+        if (!argv["no-sync"]) {
+            const summary = await syncFromCanonical({
+                paths,
+                providers: parseProvidersFlag(argv.providers),
+                yes: Boolean(argv.yes),
+                nonInteractive,
+            });
+            console.log("");
+            console.log(formatSyncSummary(summary, paths.agentsRoot));
+        }
+    }
+}
+function runMcpList(paths, asJson) {
+    const mcp = readCanonicalMcp(paths);
+    const names = Object.keys(mcp.mcpServers).sort();
+    if (asJson) {
+        console.log(JSON.stringify(mcp, null, 2));
+        return;
+    }
+    if (names.length === 0) {
+        console.log("No MCP servers configured.");
+        return;
+    }
+    for (const name of names) {
+        const server = mcp.mcpServers[name];
+        const transport = server.base && typeof server.base === "object"
+            ? server.base.url
+                ? "http"
+                : server.base.command
+                    ? "stdio"
+                    : "custom"
+            : server.url
+                ? "http"
+                : server.command
+                    ? "stdio"
+                    : "custom";
+        console.log(`${name} (${transport})`);
+    }
+}
+function runMcpAdd(paths, argv, name) {
+    const mcp = readCanonicalMcp(paths);
+    const baseConfig = {};
+    if (typeof argv.url === "string" && argv.url.trim()) {
+        baseConfig.url = argv.url.trim();
+    }
+    if (typeof argv.command === "string" && argv.command.trim()) {
+        baseConfig.command = argv.command.trim();
+    }
+    if (!baseConfig.url && !baseConfig.command) {
+        throw new Error(formatUsageError({
+            issue: "Missing MCP transport. Use --url or --command.",
+            usage: "agentloom mcp add <name> (--url <url> | --command <cmd>) [options]",
+            example: "agentloom mcp add browser --command npx --arg browser-tools-mcp",
+        }));
+    }
+    const args = getStringArrayFlag(argv.arg);
+    if (args.length > 0) {
+        baseConfig.args = args;
+    }
+    const envPairs = getStringArrayFlag(argv.env);
+    if (envPairs.length > 0) {
+        const env = {};
+        for (const pair of envPairs) {
+            const separator = pair.indexOf("=");
+            if (separator <= 0) {
+                throw new Error(formatUsageError({
+                    issue: `Invalid --env value "${pair}".`,
+                    usage: "agentloom mcp add <name> ... --env KEY=VALUE [--env KEY2=VALUE2]",
+                    example: "agentloom mcp add browser --command npx --env API_KEY=secret",
+                }));
+            }
+            const key = pair.slice(0, separator).trim();
+            const value = pair.slice(separator + 1);
+            env[key] = value;
+        }
+        baseConfig.env = env;
+    }
+    const providers = parseProvidersFlag(argv.providers);
+    if (!providers || providers.length === 0) {
+        mcp.mcpServers[name] = {
+            base: baseConfig,
+        };
+    }
+    else {
+        const providerMap = {};
+        const allProviders = [
+            "cursor",
+            "claude",
+            "codex",
+            "opencode",
+            "gemini",
+            "copilot",
+        ];
+        for (const provider of allProviders) {
+            providerMap[provider] = providers.includes(provider)
+                ? { ...baseConfig }
+                : false;
+        }
+        mcp.mcpServers[name] = {
+            providers: providerMap,
+        };
+    }
+    writeCanonicalMcp(paths, mcp);
+    console.log(`Added MCP server: ${name}`);
+}

package/dist/commands/skills.d.ts

@@ -0,0 +1 @@
+export declare function runSkillsPassthrough(args: string[]): never;

package/dist/commands/skills.js

@@ -0,0 +1,11 @@
+import { spawnSync } from "node:child_process";
+export function runSkillsPassthrough(args) {
+    const child = spawnSync("npx", ["skills", ...args], {
+        stdio: "inherit",
+        shell: false,
+    });
+    if (child.error) {
+        throw child.error;
+    }
+    process.exit(child.status ?? 1);
+}

package/dist/commands/sync.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedArgs } from "minimist";
+export declare function runSyncCommand(argv: ParsedArgs, cwd: string): Promise<void>;

package/dist/commands/sync.js

@@ -0,0 +1,25 @@
+import { parseProvidersFlag } from "../core/argv.js";
+import { getSyncHelpText } from "../core/copy.js";
+import { resolveScope } from "../core/scope.js";
+import { formatSyncSummary, syncFromCanonical } from "../sync/index.js";
+export async function runSyncCommand(argv, cwd) {
+    if (argv.help) {
+        console.log(getSyncHelpText());
+        return;
+    }
+    const nonInteractive = !(process.stdin.isTTY && process.stdout.isTTY);
+    const paths = await resolveScope({
+        cwd,
+        global: Boolean(argv.global),
+        local: Boolean(argv.local),
+        interactive: !nonInteractive,
+    });
+    const summary = await syncFromCanonical({
+        paths,
+        providers: parseProvidersFlag(argv.providers),
+        yes: Boolean(argv.yes),
+        nonInteractive,
+        dryRun: Boolean(argv["dry-run"]),
+    });
+    console.log(formatSyncSummary(summary, paths.agentsRoot));
+}

package/dist/commands/update.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedArgs } from "minimist";
+export declare function runUpdateCommand(argv: ParsedArgs, cwd: string): Promise<void>;