{"id":30520246,"url":"https://github.com/yujiosaka/knowhub","last_synced_at":"2025-08-26T15:50:58.082Z","repository":{"id":296676241,"uuid":"993620727","full_name":"yujiosaka/knowhub","owner":"yujiosaka","description":"Synchronize AI coding–agent knowledge files (rules, templates, guidelines) across your project.","archived":false,"fork":false,"pushed_at":"2025-07-24T20:57:13.000Z","size":158,"stargazers_count":28,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-24T16:52:37.404Z","etag":null,"topics":["ai","coding-assistant","developer-tools"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yujiosaka.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":"docs/FUNDING.yml","license":"LICENSE","code_of_conduct":"docs/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["yujiosaka"]}},"created_at":"2025-05-31T06:32:43.000Z","updated_at":"2025-08-15T04:42:46.000Z","dependencies_parsed_at":"2025-06-07T23:48:35.996Z","dependency_job_id":null,"html_url":"https://github.com/yujiosaka/knowhub","commit_stats":null,"previous_names":["yujiosaka/knowhub"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/yujiosaka/knowhub","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yujiosaka%2Fknowhub","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yujiosaka%2Fknowhub/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yujiosaka%2Fknowhub/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yujiosaka%2Fknowhub/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yujiosaka","download_url":"https://codeload.github.com/yujiosaka/knowhub/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yujiosaka%2Fknowhub/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272234516,"owners_count":24897018,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-26T02:00:07.904Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","coding-assistant","developer-tools"],"created_at":"2025-08-26T15:50:54.055Z","updated_at":"2025-08-26T15:50:58.070Z","avatar_url":"https://github.com/yujiosaka.png","language":"TypeScript","funding_links":["https://github.com/sponsors/yujiosaka"],"categories":["Frameworks \u0026 Libraries"],"sub_categories":["Copilot Extensions \u0026 Alternatives"],"readme":"# knowhub [![npm version](https://badge.fury.io/js/knowhub.svg)](https://badge.fury.io/js/knowhub) [![CI/CD](https://github.com/yujiosaka/knowhub/actions/workflows/ci_cd.yml/badge.svg)](https://github.com/yujiosaka/knowhub/actions/workflows/ci_cd.yml)\n\n###### [Code of Conduct](https://github.com/yujiosaka/knowhub/blob/main/docs/CODE_OF_CONDUCT.md) | [Contributing](https://github.com/yujiosaka/knowhub/blob/main/docs/CONTRIBUTING.md) | [Security](https://github.com/yujiosaka/knowhub/blob/main/docs/SECURITY.md) | [Changelog](https://github.com/yujiosaka/knowhub/blob/main/docs/CHANGELOG.md)\n\nSynchronize AI coding–agent knowledge files (rules, templates, guidelines) across your project.\n\n## What Is knowhub?\n\n\u003cimg src=\"https://github.com/user-attachments/assets/7707f2e4-66bc-4f72-8531-fad4103c89ec\" alt=\"icon\" width=\"300\" align=\"right\"\u003e\n\n**knowhub** is a lightweight CLI tool that synchronizes “resources” (local files, directories, or remote URLs) into one or more output locations within your project. It was designed with **AI coding agents** in mind—Cursor, Copilot, Windsurf, and more—so you can centrally manage coding guidelines, AI prompts, rule files, or shared snippets and distribute them across different directories without manual copying.\n\nRunning `npx knowhub` will:\n\n1. **Load \u0026 validate** a single configuration.\n2. **Fetch** each resource (from disk or over HTTP(S)).\n3. **Place** each resource into all specified output paths by **copying** or **symlinking** (per your preference).\n\nThis ensures that any AI-agent rules, templates, or shared knowledge files stay in sync project-wide, with minimal overhead.\n\n## Why knowhub?\n\n* **AI Coding Agents Need Consistency:**  In large organizations, AI agents often rely on rule files (Cursor Rules, Copilot instructions, Windsurf settings, etc.) stored in project directories. Keeping those files up to date across multiple submodules or repos can be tedious.\n* **Centralized Knowledge, Decentralized Usage:**  With knowhub, you place your master rules (Markdown, YAML, JSON, or any format) in a central folder (or even a remote URL), then declare where each AI agent expects its rules. knowhub handles distribution automatically.\n\n## Key Features\n\n* **Single-Command Synchronization:**  Run `npx knowhub` to fetch and place resources—no subcommands needed (aside from `init`).\n* **Explicit Overwrite Control:**  Each resource can be configured with `overwrite: true | false`. If `false`, existing outputs remain untouched; if `true`, outputs are overwritten.\n* **Copy or Symlink:**  Each resource's `symlink` property can be `true` (create symbolic links; auto-fallback to copy on Windows if symlinks aren't permitted) or `false`/omitted (duplicate files or directory trees).\n* **Remote Content Support:**  Resources defined by `url` are fetched via HTTP(S) and written as text files.\n* **Directory Tree Distribution:**  If a resource’s `path` points to a directory, knowhub can recursively copy or symlink that entire directory tree into each output folder.\n* **Dry-Run Mode:**  Preview actions with `--dry-run` to see which files would be written or skipped, without modifying disk.\n\n## Installation\n\nInstall **knowhub** as a development dependency:\n\n```bash\nnpm install --save-dev knowhub\n# or\nyarn add --dev knowhub\n# or\nbun add --dev knowhub\n```\n\n## Configuration\n\nknowhub searches for your configuration in these locations (in this order):\n\n1. **`.knowhubrc`** (JSON or YAML)\n2. **`.knowhubrc.json`**\n3. **`.knowhubrc.yaml`** or **`.knowhubrc.yml`**\n4. **`.knowhubrc.js`**\n5. **`.knowhubrc.ts`**\n6. **`package.json`**, under a top-level `\"knowhub\"` field\n\nIf multiple files exist, the one with highest precedence is loaded. If no configuration is found, knowhub exits with an error.\n\n### Environment Variables\n\n**Important**: Environment variable expansion (e.g., `${API_TOKEN}`) is **not supported** in JSON or YAML configuration files. \n\n- **For `.knowhubrc.json` and `.knowhubrc.yaml`**: Use literal values or placeholders like `\"YOUR_API_TOKEN_HERE\"`\n- **For `.knowhubrc.ts` and `.knowhubrc.js`**: Use `process.env.API_TOKEN` to access environment variables\n\nExample comparison:\n\n```yaml\n# ❌ This does NOT work in YAML/JSON files\nheaders:\n  Authorization: \"Bearer ${API_TOKEN}\"\n\n# ✅ Use literal values in YAML/JSON files\nheaders:\n  Authorization: \"Bearer YOUR_API_TOKEN_HERE\"\n```\n\n```typescript\n// ✅ This works in TypeScript/JavaScript files\nheaders: {\n  Authorization: `Bearer ${process.env.API_TOKEN}`,\n}\n```\n\n### `Resource` Schema\n\nEach entry in the `resources` array must conform to this schema:\n\n```ts\n/**\n * One resource to be synchronized using the plugin architecture.\n *\n * - `plugin`: string (required) - Name of the plugin to use (e.g., \"local\", \"http\")\n * - `pluginConfig`: object (required) - Plugin-specific configuration\n * - `overwrite`: boolean (default: true) - Whether to overwrite existing files\n * - `outputs`: string or string[] (required) - Output destination paths\n */\nexport type Resource = {\n  plugin: string;           // e.g. \"local\", \"http\", \"github\"\n  pluginConfig: unknown;    // Plugin-specific configuration object\n  overwrite?: boolean;      // Default: true\n  outputs: string | string[];\n};\n```\n\n### Built-in Plugins\n\n**knowhub** comes with several built-in plugins:\n\n#### **Local Plugin** (`\"local\"`)\n\nHandles local filesystem resources (files and directories).\n\n```ts\n// Plugin configuration\ninterface LocalPluginConfig {\n  path: string;       // Local filesystem path\n  symlink?: boolean;  // Create symlinks instead of copying (default: false)\n}\n```\n\nExample:\n```yaml\n- plugin: \"local\"\n  pluginConfig:\n    path: \"./shared-rules/common-style.md\"\n    symlink: true\n  overwrite: true\n  outputs: [\".cursor/rules/common-style.md\"]\n```\n\n#### **HTTP Plugin** (`\"http\"`)\n\nFetches resources from HTTP(S) URLs with advanced features.\n\n```ts\n// Plugin configuration\ninterface HttpPluginConfig {\n  url: string;                    // HTTP(S) URL to fetch\n  headers?: Record\u003cstring, string\u003e; // Custom headers\n  timeout?: number;               // Timeout in milliseconds (default: 30000)\n  method?: string;                // HTTP method (default: \"GET\")\n  body?: string;                  // Request body for POST/PUT\n}\n```\n\nExample:\n```yaml\n- plugin: \"http\"\n  pluginConfig:\n    url: \"https://example.com/api-spec.json\"\n    headers:\n      Authorization: \"Bearer YOUR_API_TOKEN_HERE\"\n      Accept: \"application/json\"\n    timeout: 10000\n  overwrite: true\n  outputs: [\"src/assets/api-spec.json\"]\n```\n\n### Sample Config\n\nBelow is a minimal `.knowhubrc.yaml` that demonstrates common use cases:\n\n```yaml\n# .knowhubrc.yaml\n\nresources:\n  # 1) Local Markdown file, symlink to two outputs, overwrite if exists\n  - plugin: \"local\"\n    pluginConfig:\n      path: './shared-rules/common-style.md'\n      symlink: true\n    overwrite: true\n    outputs:\n      - '.cursor/rules/common-style.md'\n      - '.github/copilot-instructions.md'\n\n  # 2) Remote YAML (URL), copy to two outputs, skip overwriting existing files\n  - plugin: \"http\"\n    pluginConfig:\n      url: 'https://raw.githubusercontent.com/YourOrg/ai-rules/main/security-guidelines.yaml'\n    overwrite: false\n    outputs:\n      - '.windsurfrules'\n      - 'docs/ai/security-guidelines.yaml'\n\n  # 3) Local UI widgets directory, recursively copy into output, overwrite existing\n  - plugin: \"local\"\n    pluginConfig:\n      path: './shared-rules/ui-widgets'\n    overwrite: true\n    outputs:\n      - 'components/ui-widgets'\n\n  # 4) Local PDF, copy and overwrite\n  - plugin: \"local\"\n    pluginConfig:\n      path: './shared-rules/compliance.pdf'\n    overwrite: true\n    outputs:\n      - 'docs/ai/compliance.pdf'\n\n  # 5) Remote JSON with custom headers\n  - plugin: \"http\"\n    pluginConfig:\n      url: 'https://example.com/api-spec.json'\n      headers:\n        Authorization: \"Bearer YOUR_API_TOKEN_HERE\"\n        Accept: \"application/json\"\n      timeout: 10000\n    overwrite: true\n    outputs:\n      - 'src/assets/api-spec.json'\n```\n\nYou can also place this in a TypeScript file (`.knowhubrc.ts`) or JSON (`.knowhubrc.json`) with the same structure:\n\n```ts\n// .knowhubrc.ts\nimport type { Config } from 'knowhub';\n\nconst config: Config = {\n  resources: [\n    {\n      plugin: \"local\",\n      pluginConfig: {\n        path: './shared-rules/common-style.md',\n        symlink: true,\n      },\n      overwrite: true,\n      outputs: ['.cursor/rules/common-style.md', '.github/copilot-instructions.md'],\n    },\n    {\n      plugin: \"http\",\n      pluginConfig: {\n        url: 'https://raw.githubusercontent.com/YourOrg/ai-rules/main/security-guidelines.yaml',\n      },\n      overwrite: false,\n      outputs: ['.windsurfrules', 'docs/ai/security-guidelines.yaml'],\n    },\n    {\n      plugin: \"local\",\n      pluginConfig: {\n        path: './shared-rules/ui-widgets',\n      },\n      overwrite: true,\n      outputs: ['components/ui-widgets'],\n    },\n    {\n      plugin: \"local\",\n      pluginConfig: {\n        path: './shared-rules/compliance.pdf',\n      },\n      overwrite: true,\n      outputs: ['docs/ai/compliance.pdf'],\n    },\n    {\n      plugin: \"http\",\n      pluginConfig: {\n        url: 'https://example.com/api-spec.json',\n        headers: {\n          Authorization: \"Bearer ${API_TOKEN}\",\n          Accept: \"application/json\",\n        },\n        timeout: 10000,\n      },\n      overwrite: true,\n      outputs: ['src/assets/api-spec.json'],\n    },\n  ],\n};\n\nexport default config;\n```\n\n## Usage\n\n### `npx knowhub`\n\nSimply run this in your project root:\n\n```bash\nnpx knowhub\n```\n\nThe tool will:\n\n1. **Find** and **load** your configuration.\n2. **Validate** that each resource has a valid `plugin` name, proper `pluginConfig`, a boolean `overwrite` (defaults to `true`), and one or more `outputs`.\n3. **Fetch** each resource using the specified plugin:\n\n   * **Local plugin**: Resolves files or directories on disk, optionally creating symlinks.\n   * **HTTP plugin**: Performs HTTP requests with custom headers, timeouts, and authentication.\n   * **Custom plugins**: Any registered plugins with their specific fetch logic.\n4. **Copy, Symlink, or Write** each resource into every output path:\n\n   * **Local files** → copy or create symlinks based on plugin configuration; respect `overwrite`.\n   * **Local directories** → recursively copy or create directory symlinks; respect `overwrite`.\n   * **Remote content** → write the fetched content into each output file; respect `overwrite`.\n5. **Print Summary**:\n\n   * Number of outputs created (new files/directories).\n   * Number of outputs updated (existing files/directories overwritten).\n   * Number of outputs skipped because they already existed and `overwrite: false` or content is identical.\n\n\u003e **Dry-run preview**: To see what would happen without modifying anything, run:\n\u003e\n\u003e ```bash\n\u003e npx knowhub --dry-run\n\u003e ```\n\u003e\n\u003e This prints, for each resource and output, whether it would copy, symlink, or skip.\n\n\u003e **Quiet mode**: To suppress all output (useful for CI/CD), run:\n\u003e\n\u003e ```bash\n\u003e npx knowhub --quiet\n\u003e ```\n\n\u003e **Custom config path**: If your config file is not in the default location, specify:\n\u003e\n\u003e ```bash\n\u003e npx knowhub --config ./config/my-knowhub.yaml\n\u003e ```\n\n## Examples\n\n### Sync Cursor Rules\n\nSuppose you maintain a centralized set of Cursor Rules in a shared folder (`./ai-rules/cursor`). To distribute them to each project’s `.cursor/rules` folder:\n\n```yaml\n# .knowhubrc.yaml\nresources:\n  - plugin: \"local\"\n    pluginConfig:\n      path: './ai-rules/cursor'\n    overwrite: true\n    outputs:\n      - '.cursor/rules'\n```\n\nRunning `npx knowhub` will recursively copy everything under `./ai-rules/cursor/*` into `.cursor/rules/*`.\n\n### Share Copilot Instructions\n\nIf you keep your Copilot instruction file in a single location (`./ai-rules/copilot/instructions.md`), and you want to place it in `.github/copilot-instructions.md`:\n\n```yaml\nresources:\n  - plugin: \"local\"\n    pluginConfig:\n      path: './ai-rules/copilot/instructions.md'\n      symlink: true\n    overwrite: true\n    outputs:\n      - '.github/copilot-instructions.md'\n```\n\nOn POSIX systems, this will create a symlink:\n\n```\n.github/copilot-instructions.md → ../ai-rules/copilot/instructions.md\n```\n\nOn Windows, if symlinks aren't allowed, it will copy the file instead.\n\n### Distribute Windsurf Settings\n\nIf your Windsurf configuration is hosted remotely:\n\n```yaml\nresources:\n  - plugin: \"http\"\n    pluginConfig:\n      url: 'https://raw.githubusercontent.com/YourOrg/ai-rules/main/windsurf-config.yaml'\n    overwrite: false\n    outputs:\n      - '.windsurfrules'\n      - 'docs/ai/windsurf-config.yaml'\n```\n\nRunning `npx knowhub` will fetch the YAML text and write it to `.windsurfrules` and `docs/ai/windsurf-config.yaml`, unless those files already exist.\n\n### Copy Entire Directory Trees\n\nTo copy a folder of AI prompt templates (`./ai-templates`) into two places:\n\n```yaml\nresources:\n  - plugin: \"local\"\n    pluginConfig:\n      path: './ai-templates'\n    overwrite: true\n    outputs:\n      - 'src/ai/prompt-templates'\n      - 'docs/ai/prompt-templates'\n```\n\nThis recursively copies all files and subdirectories from `./ai-templates/*` into `src/ai/prompt-templates/*` and `docs/ai/prompt-templates/*`.\n\n### Advanced HTTP Requests\n\nFor APIs requiring authentication or custom headers:\n\n```yaml\nresources:\n  - plugin: \"http\"\n    pluginConfig:\n      url: 'https://api.internal.com/config.json'\n      headers:\n        Authorization: \"Bearer YOUR_API_TOKEN_HERE\"\n        X-Team: \"frontend\"\n        Accept: \"application/json\"\n      timeout: 15000\n    overwrite: true\n    outputs:\n      - 'config/api-settings.json'\n```\n\nThis fetches from an authenticated API with custom headers and a 15-second timeout.\n\n## CI/CD Integration\n\nIntegrate **knowhub** into your continuous-integration pipeline to ensure that generated outputs remain in sync with your configuration. For example, in GitHub Actions:\n\n```yaml\nname: Sync AI Agent Knowledge\n\non:\n  push:\n    branches:\n      - main\n  pull_request:\n    branches:\n      - main\n\njobs:\n  sync-ai-agent-knowledge:\n    runs-on: ubuntu-latest\n\n    steps:\n      - name: Check out repository\n        uses: actions/checkout@v4\n\n      - name: Setup Node.js\n        uses: actions/setup-node@v3\n\n      - name: Install dependencies\n        run: npm ci\n\n      - name: Run knowhub\n        run: npx knowhub\n\n      - name: Commit updated outputs\n        run: |\n          git config user.name \"github-actions\"\n          git config user.email \"actions@github.com\"\n          git add .\n          git diff --quiet || git commit -m \"chore: update AI agent knowledge files\"\n          git push\n```\n\n* **Run** `npx knowhub` to update all outputs.\n* **Commit** and **push** any new or changed files so your repository always has the latest AI prompts, rules, or guidelines.\n\n## Custom Plugins\n\nknowhub supports a powerful plugin system that allows you to extend its functionality with custom resource fetchers. You can create plugins to fetch from APIs, databases, cloud services, or any other data source.\n\n### Dynamic Plugin Loading\n\nknowhub automatically loads plugins specified in your configuration, eliminating the need for manual registration:\n\n```yaml\n# .knowhubrc.yaml\nplugins:\n  - \"./plugins/github-plugin.ts\"\n  - \"./plugins/my-custom-plugin.js\"\n  - \"./node_modules/knowhub-slack-plugin\"\n\nresources:\n  - plugin: \"github\"\n    pluginConfig:\n      owner: \"company\"\n      repo: \"standards\"\n      path: \"rules.md\"\n      token: \"${GITHUB_TOKEN}\"\n    outputs: [\".cursor/rules.md\"]\n```\n\n### Plugin Configuration\n\nAdd custom plugins to your knowhub configuration using the `plugins` field:\n\n- **Local plugins**: Relative paths to your plugin files (`.ts`, `.js`)\n- **NPM packages**: Node module names that export knowhub plugins\n- **Multiple export patterns**: Supports both default and named exports\n\nExample with multiple plugin types:\n\n```typescript\n// .knowhubrc.ts\nimport type { Config } from 'knowhub';\n\nconst config: Config = {\n  plugins: [\n    \"./plugins/github-plugin.ts\",        // Local TypeScript plugin\n    \"./plugins/slack-plugin.js\",         // Local JavaScript plugin\n    \"knowhub-jira-plugin\",               // NPM package plugin\n  ],\n  resources: [\n    {\n      plugin: \"github\",\n      pluginConfig: {\n        owner: \"company\",\n        repo: \"coding-standards\",\n        path: \"cursor-rules.md\",\n        token: process.env.GITHUB_TOKEN,\n      },\n      outputs: [\".cursor/rules.md\"],\n    },\n    {\n      plugin: \"slack\",\n      pluginConfig: {\n        channel: \"engineering\",\n        messageId: \"12345\",\n        token: process.env.SLACK_TOKEN,\n      },\n      outputs: [\"docs/announcements.md\"],\n    },\n  ],\n};\n\nexport default config;\n```\n\n### Available Plugins\n\n- **Built-in plugins**: `local` (filesystem), `http` (HTTP/HTTPS requests)\n- **Example plugins**: See the [`examples/`](examples) directory for plugin development guides and sample implementations\n- **Community plugins**: Check npm for community-contributed knowhub plugins\n\n### Creating Custom Plugins\n\nFor detailed instructions on creating your own plugins, including a complete GitHub plugin example, see the [**Plugin Development Guide**](examples/README.md) in the `examples/` directory.\n\nThe guide covers:\n- Plugin architecture and interfaces\n- Dynamic loading setup\n- Configuration validation\n- Error handling best practices\n- Complete working examples\n\n## License\n\nThis project is licensed under the **MIT License**. See the [LICENSE](https://github.com/yujiosaka/knowhub/blob/main/LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyujiosaka%2Fknowhub","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyujiosaka%2Fknowhub","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyujiosaka%2Fknowhub/lists"}