{"id":31650285,"url":"https://github.com/marclove/known","last_synced_at":"2025-10-07T08:11:58.906Z","repository":{"id":303154117,"uuid":"1014564013","full_name":"marclove/known","owner":"marclove","description":"A CLI tool for managing agentic LLM instruction files in your projects.","archived":false,"fork":false,"pushed_at":"2025-09-29T03:54:07.000Z","size":192,"stargazers_count":3,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-04T02:58:27.501Z","etag":null,"topics":["claude","claude-code","cline","codex-cli","copilot","cursor","gemini-cli","llm","llms"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marclove.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-06T01:08:56.000Z","updated_at":"2025-08-26T10:40:39.000Z","dependencies_parsed_at":"2025-07-06T02:25:24.808Z","dependency_job_id":"7ab7871c-784b-401a-a664-903866af6e12","html_url":"https://github.com/marclove/known","commit_stats":null,"previous_names":["marclove/known"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/marclove/known","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marclove%2Fknown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marclove%2Fknown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marclove%2Fknown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marclove%2Fknown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marclove","download_url":"https://codeload.github.com/marclove/known/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marclove%2Fknown/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278740839,"owners_count":26037481,"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-10-07T02:00:06.786Z","response_time":59,"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":["claude","claude-code","cline","codex-cli","copilot","cursor","gemini-cli","llm","llms"],"created_at":"2025-10-07T08:11:50.320Z","updated_at":"2025-10-07T08:11:58.900Z","avatar_url":"https://github.com/marclove.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e WARNING!!!: This is still prerelease software. Backwards-incompatible changes will be pushed without warning. Stability will be indicated by a 1.0 release. The goal is to achieve a 1.0 release by the end of July.\n\n# Known\n\nA Rust library and CLI tool for managing agentic LLM instruction files in your projects.\n\n## Overview\n\nKnown helps you create and manage instruction files for various AI coding assistants like Claude Code, Gemini CLI, and other agentic tools. It provides a unified `AGENTS.md` file format with automatic symlink generation for compatibility with different naming conventions.\n\n## Features\n\n- **Unified instruction file**: Creates `AGENTS.md` as the single source of truth\n- **Automatic migration**: Renames existing `CLAUDE.md` or `GEMINI.md` files to `AGENTS.md`\n- **Symlink generation**: Creates `CLAUDE.md` and `GEMINI.md` symlinks pointing to `AGENTS.md`\n- **Rules directory management**: Automatically creates `.rules` directory and migrates files from `.cursor/rules` and `.windsurf/rules`\n- **Daemon process**: File watching daemon that maintains synchronized symlinks across IDE rules directories\n- **System-wide single instance enforcement**: Prevents multiple daemon instances from running simultaneously across the entire system using centralized PID file locking\n- **Cross-platform autostart**: System-level autostart configuration for seamless daemon management\n- **Cross-platform compatibility**: Works on Unix and Windows systems\n- **CLI interface**: Simple command-line tool for project initialization and management\n\n## Installation\n\n```bash\ncargo install known\n```\n\n## Usage\n\n### Initialize a project\n\nCreate an `AGENTS.md` file in your current directory:\n\n```bash\nknown init\n```\n\nThis command will:\n- Create an `AGENTS.md` file with default content if none exists\n- Rename existing `CLAUDE.md` or `GEMINI.md` files to `AGENTS.md`\n- Handle conflicts gracefully when multiple instruction files exist\n- Create a `.rules` directory for storing project-specific rules\n\n### Create symlinks\n\nGenerate compatibility symlinks for different AI tools:\n\n```bash\nknown symlink\n```\n\nThis command will:\n- Create `CLAUDE.md` → `AGENTS.md` (symlink)\n- Create `GEMINI.md` → `AGENTS.md` (symlink)\n- Move any files from `.cursor/rules` to `.rules` directory\n- Move any files from `.windsurf/rules` to `.rules` directory\n- Skip files that already exist in `.rules` with a user-friendly warning\n\n### Manage watched directories\n\nAdd a directory to be watched by the daemon:\n\n```bash\nknown add [DIRECTORY]\n```\n\nIf no directory is specified, the current working directory is used. This command will:\n- Add the specified directory to the daemon's configuration\n- Enable the daemon to watch the `.rules` directory within that project\n\nRemove a directory from being watched:\n\n```bash\nknown remove [DIRECTORY]\n```\n\nIf no directory is specified, the current working directory is used.\n\nList all directories currently being watched:\n\n```bash\nknown list\n```\n\nThis command displays all directories that are currently configured to be watched by the daemon.\n\n### Start daemon\n\nStart a file watching daemon to automatically maintain symlinks:\n\n```bash\nknown start\n```\n\nThis command will:\n- Monitor all configured directories' `.rules` subdirectories for changes\n- Automatically create and maintain symlinks in `.cursor/rules` and `.windsurf/rules`\n- Keep the rules directories synchronized with the unified `.rules` directory\n- Enforce system-wide single instance operation (only one daemon can run across the entire system)\n- Create a centralized PID file for process management\n- Run continuously until stopped, even if no directories are initially configured\n\nStop the daemon:\n\n```bash\nknown stop\n```\n\n### Autostart management\n\nEnable the daemon to start automatically when your system boots:\n\n```bash\nknown enable-autostart\n```\n\nDisable autostart for the daemon:\n\n```bash\nknown disable-autostart\n```\n\nCheck if autostart is enabled:\n\n```bash\nknown autostart-status\n```\n\nThe autostart feature works cross-platform:\n- **Windows**: Uses Windows registry entries\n- **macOS**: Uses Launch Agents \n- **Linux**: Uses systemd or equivalent service manager\n\n## Library Usage\n\nYou can also use Known as a Rust library:\n\n```rust\nuse known::{create_agents_file, create_symlinks, start_daemon, enable_autostart, disable_autostart, is_autostart_enabled, SingleInstanceLock};\n\n// Create AGENTS.md file\ncreate_agents_file()?;\n\n// Create symlinks to AGENTS.md\ncreate_symlinks()?;\n\n// Start daemon to watch .rules directory\nstart_daemon(mpsc::channel().1)?;\n\n// Enable autostart for the daemon\nenable_autostart()?;\n\n// Check if autostart is enabled\nlet enabled = is_autostart_enabled()?;\n\n// Disable autostart\ndisable_autostart()?;\n\n// Manual single instance lock management (advanced usage)\nlet _lock = SingleInstanceLock::acquire()?;  // Acquire system-wide lock\n// Lock is automatically released when _lock goes out of scope\n```\n\n## File Structure\n\nAfter running `known init` and `known symlink`, your project will have:\n\n```\nyour-project/\n├── AGENTS.md              # Main instruction file\n├── CLAUDE.md              # Symlink to AGENTS.md\n├── GEMINI.md              # Symlink to AGENTS.md\n└── .rules/                # Directory for project-specific rules\n    ├── rule1.txt          # Migrated from .cursor/rules/\n    └── config.toml        # Migrated from .windsurf/rules/\n```\n\n## Rules Directory Migration\n\nKnown automatically manages rules directories used by various AI coding assistants:\n\n- **`.cursor/rules`** → **`.rules`**: Files from Cursor's rules directory are moved to the unified `.rules` directory\n- **`.windsurf/rules`** → **`.rules`**: Files from Windsurf's rules directory are moved to the unified `.rules` directory\n\nThis migration happens automatically when you run `known symlink`. If files with the same name already exist in `.rules`, they will be skipped with a warning message.\n\n## Single Instance Enforcement\n\nThe daemon process enforces single instance operation to prevent conflicts and resource contention:\n\n- **Centralized PID File Locking**: Uses a system-wide PID file with exclusive file locking\n- **Automatic Cleanup**: PID file is automatically removed when daemon stops gracefully\n- **Stale Process Detection**: Detects and handles stale PID files from crashed processes\n- **Error Handling**: Provides clear error messages when attempting to start multiple instances\n\nIf you try to start a second daemon instance anywhere on the system, you'll see an error message:\n\n```bash\n$ known daemon\nError running daemon: Another instance of the daemon is already running\n```\n\nThe centralized PID file contains the process ID of the running daemon and is automatically cleaned up when the process stops.\n\n## Default AGENTS.md Content\n\nWhen you run `known init`, if no instruction file exists, it creates an `AGENTS.md` file with default content that provides guidance to agentic coding agents like Claude Code, Gemini CLI, and other AI assistants.\n\n## Development\n\n### Building\n\n```bash\ncargo build\n```\n\n### Testing\n\n```bash\ncargo test\n```\n\n### Linting\n\n```bash\ncargo clippy\ncargo fmt\n```\n\n## License\n\nThis project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarclove%2Fknown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarclove%2Fknown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarclove%2Fknown/lists"}