ide-agents 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ide-agents 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,131 @@
+# ide-agents
+
+Local admin for **IDE agents and skills** (Cursor and similar) from any git repository.
+
+Install skills and subagents into your IDE via symlinks — no copy-paste, no manual path juggling.
+
+## What it does
+
+- Clones git repositories into `~/.ide-agents/repos/`
+- Scans `skills/*/SKILL.md` and optional `agents/*.md`
+- Creates symlinks in `~/.cursor/` (global) or `<project>/.cursor/` (per-project)
+- Provides a browser UI for repos, skills, and agents
+
+**Not affiliated with Cursor.**
+
+## Requirements
+
+- **macOS** or **Linux** (Windows is not supported in v0.1)
+- **Node.js 20+**
+- **git** in PATH
+
+## Install
+
+```bash
+npm i -g ide-agents
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/sergeychernov/agentdesk.git
+cd agentdesk
+npm install
+npm run build
+npm i -g .
+```
+
+## Quick start
+
+```bash
+ide-agents
+```
+
+This will:
+
+1. Create `~/.ide-agents/` on first run (migrates from `~/.agentdesk/` if present)
+2. Start a local server at `http://127.0.0.1:3921` (or the next free port)
+3. Open the UI in your browser
+
+Press `Ctrl+C` to stop.
+
+### CLI options
+
+```bash
+ide-agents --port 3922    # custom port
+ide-agents --no-open      # do not open browser
+```
+
+## Add a repository
+
+1. Open **Settings** in the UI
+2. Enter a git URL and branch (default `main`)
+3. Click **Add / Clone**
+
+Your repo should contain:
+
+```
+skills/
+  my-skill/
+    SKILL.md
+agents/          # optional
+  my-agent.md
+```
+
+For local testing, use a `file://` URL:
+
+```
+file:///Users/you/code/my-skills-repo
+```
+
+Private repos: configure SSH or `gh` auth yourself — ide-agents does not store tokens.
+
+## Install artifacts
+
+1. Go to **Skills** or **Agents**
+2. Select a repository
+3. Click **Global** (🌐) or **Project** (📁) on a card — symlinks apply immediately
+
+| Kind  | Global                         | Project                              |
+|-------|--------------------------------|--------------------------------------|
+| Skill | `~/.cursor/skills/<name>`      | `<project>/.cursor/skills/<name>`    |
+| Agent | `~/.cursor/agents/<name>.md`   | `<project>/.cursor/agents/<name>.md` |
+
+Click the active icon again to remove the symlink (only if target is already a symlink).
+
+## Development
+
+```bash
+npm install
+npm run dev        # server on :3921 + Vite on :5173
+npm run build      # compile server + web
+npm start          # run production build
+```
+
+Documentation site (Docusaurus):
+
+```bash
+npm run docs:install
+npm run docs:start # http://localhost:3000
+```
+
+Fixture repo for manual testing:
+
+```bash
+cd fixtures/sample-repo && git init && git add . && git commit -m "init"
+```
+
+Then add `file://$(pwd)` in the UI.
+
+## Data layout
+
+```
+~/.ide-agents/
+├── config.json
+└── repos/
+    └── <slug>/     # git clone
+```
+
+## License
+
+MIT

package/dist/adapters/cursor.d.ts

@@ -0,0 +1,10 @@
+import type { ArtifactKind, Installation } from "../types.js";
+export interface Adapter {
+    id: "cursor";
+    getGlobalTargetPath(installation: Pick<Installation, "kind" | "targetName">): string;
+    getProjectTargetPath(installation: Pick<Installation, "kind" | "targetName" | "projectPath">): string;
+    getSourcePath(repoRoot: string, installation: Pick<Installation, "sourcePath">): string;
+}
+export declare const cursorAdapter: Adapter;
+export declare function getAdapter(adapterId: string): Adapter;
+export declare function isSymlinkType(kind: ArtifactKind): "dir" | "file";

package/dist/adapters/cursor.js

@@ -0,0 +1,39 @@
+import path from "node:path";
+import { homedir } from "node:os";
+import { resolveProjectPath } from "../paths.js";
+function skillsDir(base) {
+    return path.join(base, ".cursor", "skills");
+}
+function agentsDir(base) {
+    return path.join(base, ".cursor", "agents");
+}
+function targetPath(base, kind, targetName) {
+    if (kind === "skill") {
+        return path.join(skillsDir(base), targetName);
+    }
+    return path.join(agentsDir(base), `${targetName}.md`);
+}
+export const cursorAdapter = {
+    id: "cursor",
+    getGlobalTargetPath(installation) {
+        return targetPath(homedir(), installation.kind, installation.targetName);
+    },
+    getProjectTargetPath(installation) {
+        if (!installation.projectPath) {
+            throw new Error("projectPath is required for project target");
+        }
+        return targetPath(resolveProjectPath(installation.projectPath), installation.kind, installation.targetName);
+    },
+    getSourcePath(repoRoot, installation) {
+        return path.join(repoRoot, installation.sourcePath);
+    },
+};
+export function getAdapter(adapterId) {
+    if (adapterId === "cursor") {
+        return cursorAdapter;
+    }
+    throw new Error(`Unknown adapter: ${adapterId}`);
+}
+export function isSymlinkType(kind) {
+    return kind === "skill" ? "dir" : "file";
+}

package/dist/apply.d.ts

@@ -0,0 +1,2 @@
+import type { IdeAgentsConfig, ApplyResult } from "./types.js";
+export declare function applyInstallations(config: IdeAgentsConfig): Promise<ApplyResult>;

package/dist/apply.js

@@ -0,0 +1,100 @@
+import { lstat, mkdir, readlink, symlink, unlink } from "node:fs/promises";
+import path from "node:path";
+import { getAdapter } from "./adapters/cursor.js";
+import { getRepoPath } from "./paths.js";
+async function pathExists(filePath) {
+    try {
+        await lstat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function ensureParentDir(filePath) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+}
+async function removeSymlinkIfExists(targetPath) {
+    if (!(await pathExists(targetPath))) {
+        return { path: targetPath, action: "skipped" };
+    }
+    const stats = await lstat(targetPath);
+    if (!stats.isSymbolicLink()) {
+        return {
+            path: targetPath,
+            action: "skipped",
+            error: "Target exists and is not a symlink",
+        };
+    }
+    await unlink(targetPath);
+    return { path: targetPath, action: "removed" };
+}
+async function createSymlink(targetPath, sourcePath, type) {
+    const resolvedSource = path.resolve(sourcePath);
+    if (await pathExists(targetPath)) {
+        const stats = await lstat(targetPath);
+        if (stats.isSymbolicLink()) {
+            const current = await readlink(targetPath);
+            if (path.resolve(path.dirname(targetPath), current) === resolvedSource) {
+                return { path: targetPath, action: "skipped" };
+            }
+            await unlink(targetPath);
+        }
+        else {
+            return {
+                path: targetPath,
+                action: "skipped",
+                error: "Target exists and is not a symlink",
+            };
+        }
+    }
+    await ensureParentDir(targetPath);
+    await symlink(resolvedSource, targetPath, type);
+    return { path: targetPath, action: "created" };
+}
+async function applyScope(installation, sourcePath, type, enabled, targetPath) {
+    const results = [];
+    if (enabled) {
+        try {
+            results.push(await createSymlink(targetPath, sourcePath, type));
+        }
+        catch (err) {
+            results.push({
+                path: targetPath,
+                action: "skipped",
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        return results;
+    }
+    const removed = await removeSymlinkIfExists(targetPath);
+    if (removed.action === "removed") {
+        results.push(removed);
+    }
+    return results;
+}
+export async function applyInstallations(config) {
+    const adapter = getAdapter(config.adapter);
+    const results = [];
+    for (const installation of config.installations) {
+        const repo = config.repos.find((r) => r.id === installation.repoId);
+        if (!repo) {
+            results.push({
+                path: installation.targetName,
+                action: "skipped",
+                error: `Unknown repo: ${installation.repoId}`,
+            });
+            continue;
+        }
+        const repoRoot = getRepoPath(repo.slug);
+        const sourcePath = adapter.getSourcePath(repoRoot, installation);
+        const type = installation.kind === "skill" ? "dir" : "file";
+        const globalTarget = adapter.getGlobalTargetPath(installation);
+        results.push(...(await applyScope(installation, sourcePath, type, installation.global, globalTarget)));
+        if (installation.projectPath) {
+            const projectTarget = adapter.getProjectTargetPath(installation);
+            results.push(...(await applyScope(installation, sourcePath, type, installation.project, projectTarget)));
+        }
+    }
+    return { results };
+}

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import net from "node:net";
+import path from "node:path";
+import { readConfig } from "./config.js";
+import { startServer } from "./server.js";
+function parseArgs(argv) {
+    const options = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--no-open") {
+            options.noOpen = true;
+        }
+        else if (arg === "--port" && argv[i + 1]) {
+            options.port = Number.parseInt(argv[i + 1], 10);
+            i++;
+        }
+        else if (arg === "ui") {
+            // default command
+        }
+    }
+    return options;
+}
+async function isPortAvailable(port, host) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.once("error", () => resolve(false));
+        server.once("listening", () => {
+            server.close(() => resolve(true));
+        });
+        server.listen(port, host);
+    });
+}
+async function findAvailablePort(startPort, host, maxAttempts = 10) {
+    for (let offset = 0; offset < maxAttempts; offset++) {
+        const port = startPort + offset;
+        if (await isPortAvailable(port, host)) {
+            return port;
+        }
+    }
+    throw new Error(`Ports ${startPort}-${startPort + maxAttempts - 1} are busy on ${host}`);
+}
+function openBrowser(url) {
+    const platform = process.platform;
+    if (platform === "darwin") {
+        spawn("open", [url], { detached: true, stdio: "ignore" }).unref();
+    }
+    else if (platform === "linux") {
+        spawn("xdg-open", [url], { detached: true, stdio: "ignore" }).unref();
+    }
+    else {
+        console.log(`Open ${url} in your browser`);
+    }
+}
+async function main() {
+    const options = parseArgs(process.argv.slice(2));
+    const config = await readConfig();
+    const host = "127.0.0.1";
+    const requestedPort = options.port ?? config.server.port;
+    const port = await findAvailablePort(requestedPort, host);
+    const url = `http://${host}:${port}`;
+    const app = await startServer({
+        port,
+        host,
+        launchCwd: path.resolve(process.cwd()),
+    });
+    console.log(`ide-agents running at ${url}`);
+    if (!options.noOpen) {
+        openBrowser(url);
+    }
+    const shutdown = async () => {
+        console.log("\nShutting down...");
+        await app.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/config.d.ts

@@ -0,0 +1,5 @@
+import type { IdeAgentsConfig } from "./types.js";
+export declare function ensureIdeAgentsHome(): Promise<string>;
+export declare function readConfig(): Promise<IdeAgentsConfig>;
+export declare function writeConfig(config: IdeAgentsConfig): Promise<void>;
+export declare function addRecentProject(config: IdeAgentsConfig, projectPath: string): Promise<IdeAgentsConfig>;

package/dist/config.js

@@ -0,0 +1,86 @@
+import { access, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { homedir } from "node:os";
+import { getConfigPath, getIdeAgentsHome } from "./paths.js";
+const DEFAULT_CONFIG = {
+    version: 1,
+    adapter: "cursor",
+    server: { port: 3921 },
+    repos: [],
+    installations: [],
+    recentProjects: [],
+};
+const LEGACY_HOME = path.join(homedir(), ".agentdesk");
+async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function migrateInstallation(raw) {
+    const item = raw;
+    if (typeof item.global === "boolean") {
+        return item;
+    }
+    const scope = item.scope;
+    return {
+        id: item.id,
+        repoId: item.repoId,
+        kind: item.kind,
+        artifactId: item.artifactId,
+        sourcePath: item.sourcePath,
+        targetName: item.targetName,
+        global: scope === "global",
+        project: scope === "project",
+        projectPath: item.projectPath ?? null,
+    };
+}
+async function migrateLegacyHome() {
+    const home = getIdeAgentsHome();
+    if (home === LEGACY_HOME) {
+        return;
+    }
+    if (!(await fileExists(home)) && (await fileExists(LEGACY_HOME))) {
+        await rename(LEGACY_HOME, home);
+    }
+}
+export async function ensureIdeAgentsHome() {
+    await migrateLegacyHome();
+    const home = getIdeAgentsHome();
+    await mkdir(home, { recursive: true });
+    await mkdir(path.join(home, "repos"), { recursive: true });
+    return home;
+}
+export async function readConfig() {
+    await ensureIdeAgentsHome();
+    const configPath = getConfigPath();
+    if (!(await fileExists(configPath))) {
+        await writeConfig(DEFAULT_CONFIG);
+        return structuredClone(DEFAULT_CONFIG);
+    }
+    const raw = await readFile(configPath, "utf8");
+    const parsed = JSON.parse(raw);
+    return {
+        ...DEFAULT_CONFIG,
+        ...parsed,
+        server: { ...DEFAULT_CONFIG.server, ...parsed.server },
+        repos: parsed.repos ?? [],
+        installations: (parsed.installations ?? []).map(migrateInstallation),
+        recentProjects: parsed.recentProjects ?? [],
+    };
+}
+export async function writeConfig(config) {
+    await ensureIdeAgentsHome();
+    await writeFile(getConfigPath(), `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+export async function addRecentProject(config, projectPath) {
+    const resolved = path.resolve(projectPath);
+    const recent = [
+        resolved,
+        ...config.recentProjects.filter((p) => p !== resolved),
+    ].slice(0, 10);
+    return { ...config, recentProjects: recent };
+}

package/dist/git.d.ts

@@ -0,0 +1,6 @@
+import type { GitStatus } from "./types.js";
+export declare function cloneRepo(url: string, slug: string, ref: string): Promise<string>;
+export declare function fetchRepo(slug: string): Promise<void>;
+export declare function pullRepo(slug: string): Promise<void>;
+export declare function getGitStatus(slug: string, ref: string): Promise<GitStatus>;
+export declare function getGitStatusWithoutFetch(slug: string, ref: string): Promise<GitStatus>;

package/dist/git.js

@@ -0,0 +1,173 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import path from "node:path";
+import { access } from "node:fs/promises";
+import { getRepoPath } from "./paths.js";
+const execFileAsync = promisify(execFile);
+async function isGitRepo(dir) {
+    try {
+        await access(path.join(dir, ".git"));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function runGit(cwd, args) {
+    const result = await execFileAsync("git", args, {
+        cwd,
+        maxBuffer: 10 * 1024 * 1024,
+    });
+    return { stdout: result.stdout.trim(), stderr: result.stderr.trim() };
+}
+export async function cloneRepo(url, slug, ref) {
+    const target = getRepoPath(slug);
+    if (await isGitRepo(target)) {
+        throw new Error(`Repository already cloned at ${target}`);
+    }
+    await execFileAsync("git", ["clone", "--branch", ref, url, target], {
+        maxBuffer: 10 * 1024 * 1024,
+    }).catch(async (err) => {
+        // Retry without --branch for repos where ref is not a branch at clone time
+        try {
+            await execFileAsync("git", ["clone", url, target], {
+                maxBuffer: 10 * 1024 * 1024,
+            });
+            await runGit(target, ["checkout", ref]);
+        }
+        catch {
+            throw new Error(err.stderr?.trim() || err.message);
+        }
+    });
+    return target;
+}
+export async function fetchRepo(slug) {
+    const cwd = getRepoPath(slug);
+    if (!(await isGitRepo(cwd))) {
+        throw new Error(`Not a git repository: ${cwd}`);
+    }
+    await runGit(cwd, ["fetch", "--all", "--prune"]);
+}
+export async function pullRepo(slug) {
+    const cwd = getRepoPath(slug);
+    if (!(await isGitRepo(cwd))) {
+        throw new Error(`Not a git repository: ${cwd}`);
+    }
+    await runGit(cwd, ["pull", "--ff-only"]);
+}
+export async function getGitStatus(slug, ref) {
+    const cwd = getRepoPath(slug);
+    if (!(await isGitRepo(cwd))) {
+        return {
+            branch: null,
+            sha: null,
+            dirty: false,
+            behind: null,
+            ahead: null,
+            error: "Repository not cloned",
+        };
+    }
+    try {
+        const branchResult = await runGit(cwd, [
+            "rev-parse",
+            "--abbrev-ref",
+            "HEAD",
+        ]);
+        const shaResult = await runGit(cwd, ["rev-parse", "HEAD"]);
+        const dirtyResult = await runGit(cwd, ["status", "--porcelain"]);
+        let behind = null;
+        let ahead = null;
+        try {
+            await runGit(cwd, ["fetch", "--quiet"]);
+            const revList = await runGit(cwd, [
+                "rev-list",
+                "--left-right",
+                "--count",
+                `HEAD...origin/${ref}`,
+            ]);
+            const [aheadStr, behindStr] = revList.stdout.split(/\s+/);
+            ahead = Number.parseInt(aheadStr ?? "0", 10);
+            behind = Number.parseInt(behindStr ?? "0", 10);
+        }
+        catch {
+            // Remote tracking may not exist yet
+            behind = null;
+            ahead = null;
+        }
+        return {
+            branch: branchResult.stdout || null,
+            sha: shaResult.stdout || null,
+            dirty: dirtyResult.stdout.length > 0,
+            behind,
+            ahead,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            branch: null,
+            sha: null,
+            dirty: false,
+            behind: null,
+            ahead: null,
+            error: message,
+        };
+    }
+}
+export async function getGitStatusWithoutFetch(slug, ref) {
+    const cwd = getRepoPath(slug);
+    if (!(await isGitRepo(cwd))) {
+        return {
+            branch: null,
+            sha: null,
+            dirty: false,
+            behind: null,
+            ahead: null,
+            error: "Repository not cloned",
+        };
+    }
+    try {
+        const branchResult = await runGit(cwd, [
+            "rev-parse",
+            "--abbrev-ref",
+            "HEAD",
+        ]);
+        const shaResult = await runGit(cwd, ["rev-parse", "HEAD"]);
+        const dirtyResult = await runGit(cwd, ["status", "--porcelain"]);
+        let behind = null;
+        let ahead = null;
+        try {
+            const revList = await runGit(cwd, [
+                "rev-list",
+                "--left-right",
+                "--count",
+                `HEAD...origin/${ref}`,
+            ]);
+            const [aheadStr, behindStr] = revList.stdout.split(/\s+/);
+            ahead = Number.parseInt(aheadStr ?? "0", 10);
+            behind = Number.parseInt(behindStr ?? "0", 10);
+        }
+        catch {
+            behind = null;
+            ahead = null;
+        }
+        return {
+            branch: branchResult.stdout || null,
+            sha: shaResult.stdout || null,
+            dirty: dirtyResult.stdout.length > 0,
+            behind,
+            ahead,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            branch: null,
+            sha: null,
+            dirty: false,
+            behind: null,
+            ahead: null,
+            error: message,
+        };
+    }
+}

package/dist/paths.d.ts

@@ -0,0 +1,8 @@
+export declare function getIdeAgentsHome(): string;
+export declare function getConfigPath(): string;
+export declare function getStatePath(): string;
+export declare function getReposDir(): string;
+export declare function getRepoPath(slug: string): string;
+export declare function slugFromUrl(url: string): string;
+export declare function getWebDistDir(): string;
+export declare function resolveProjectPath(projectPath: string): string;