agentsbridge 0.1.0__tar.gz

agentsbridge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agentsbridge 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.

agentsbridge-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: agentsbridge
+Version: 0.1.0
+Summary: Bridge AGENTS.md to every AI coding tool's rules file - one source of truth for Claude Code, Copilot, Cursor, Windsurf, Cline, and Aider.
+Author: agentsbridge contributors
+License: MIT
+Project-URL: Homepage, https://github.com/DavidStarYu/agentsbridge
+Project-URL: Repository, https://github.com/DavidStarYu/agentsbridge
+Project-URL: Changelog, https://github.com/DavidStarYu/agentsbridge/blob/main/CHANGELOG.md
+Keywords: agents-md,claude,claude-code,cursor,copilot,windsurf,cline,aider,ai,rules,cli,developer-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<div align="center">
+
+<img src="assets/banner.svg" alt="agentsbridge" width="640">
+
+**One `AGENTS.md`. Every AI coding tool. Zero drift.**
+
+[![CI](https://github.com/DavidStarYu/agentsbridge/actions/workflows/ci.yml/badge.svg)](https://github.com/DavidStarYu/agentsbridge/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/agentsbridge)](https://pypi.org/project/agentsbridge/)
+[![Python](https://img.shields.io/pypi/pyversions/agentsbridge)](https://pypi.org/project/agentsbridge/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+[Bridge](#why) · [Quick start](#quick-start) · [Supported tools](#supported-tools) · [CI drift check](#ci-drift-check) · [FAQ](#faq)
+
+</div>
+
+---
+
+## Why
+
+Your team uses Claude Code. Your teammate uses Cursor. Someone just switched
+to Codex CLI. And suddenly your coding standards live in **five different
+files** that silently drift apart:
+
+```text
+AGENTS.md                          ← Codex, Gemini CLI, Jules, Amp, Zed read this
+CLAUDE.md                          ← Claude Code reads this (not AGENTS.md)
+.github/copilot-instructions.md    ← GitHub Copilot reads this (not AGENTS.md)
+.cursor/rules/*.mdc                ← Cursor reads this (not AGENTS.md, older versions)
+.windsurfrules / .clinerules       ← Windsurf / Cline read these
+CONVENTIONS.md                     ← Aider reads this
+```
+
+`agentsbridge` fixes this with one command. You maintain **one** `AGENTS.md`
+(the emerging industry standard) — it generates and keeps every tool's file
+in sync. Edit once, sync everywhere, and let CI catch anything that drifts.
+
+## Quick start
+
+```bash
+pipx install agentsbridge        # or: pip install agentsbridge / uv tool install agentsbridge
+```
+
+**Already have rules somewhere?** Import them:
+
+```bash
+agentsbridge import              # seeds AGENTS.md from CLAUDE.md, .cursorrules, etc.
+```
+
+**Starting fresh?**
+
+```bash
+agentsbridge init                # creates a starter AGENTS.md
+```
+
+Then — the only command you'll ever need again:
+
+```bash
+agentsbridge sync
+```
+
+```text
+  + created   CLAUDE.md
+  + created   .github/copilot-instructions.md
+  + created   .cursor/rules/agentsbridge.mdc
+  + created   .windsurfrules
+  + created   .clinerules
+  + created   CONVENTIONS.md
+
+wrote 6 file(s)
+```
+
+Edit `AGENTS.md`, run `agentsbridge sync`, commit. That's the whole workflow.
+
+## Supported tools
+
+| Tool | File generated | Notes |
+|---|---|---|
+| **Claude Code** | `CLAUDE.md` | |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | |
+| **Cursor** | `.cursor/rules/agentsbridge.mdc` | with `alwaysApply` frontmatter |
+| **Windsurf** | `.windsurfrules` | |
+| **Cline** | `.clinerules` | |
+| **Aider** | `CONVENTIONS.md` | |
+| **Codex CLI, Gemini CLI, Jules, Amp, Zed, opencode** | — | read `AGENTS.md` natively, nothing to generate |
+
+Missing a tool? [Open an issue](https://github.com/DavidStarYu/agentsbridge/issues) —
+adding a target is ~10 lines.
+
+## Safety
+
+Generated files are marked:
+
+```markdown
+<!-- generated by agentsbridge; do not edit -->
+```
+
+If a target file already exists **without** that marker (i.e. you wrote it by
+hand), `sync` skips it instead of clobbering your work. Use `--force` to
+adopt it deliberately.
+
+```bash
+agentsbridge sync --force        # adopt existing files
+agentsbridge sync --dry-run      # preview changes
+agentsbridge sync -t claude,copilot   # subset of targets
+```
+
+## CI drift check
+
+The whole point: rules that drift are rules nobody follows. Add the check to
+your workflow and CI fails whenever someone edits a generated file — or
+forgets to re-sync after editing `AGENTS.md`:
+
+```yaml
+# .github/workflows/ci.yml
+name: rules
+on: [push, pull_request]
+jobs:
+  agentsbridge:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DavidStarYu/agentsbridge/action@main
+```
+
+Or invoke the CLI directly: `agentsbridge check` (exit code 1 on drift).
+
+This repository runs the same check on itself — [dogfooding](.github/workflows/rules.yml).
+
+## FAQ
+
+**Why AGENTS.md as the source, not my own config?**
+AGENTS.md is the emerging standard (adopted by OpenAI Codex, Gemini CLI, Jules,
+Amp, Zed and others — see [agents.md](https://agents.md)). Tools that don't
+read it yet are exactly the ones this bridge targets. You keep zero
+agentsbridge-specific config: the source file is a standard.
+
+**Cursor already reads AGENTS.md, why generate an .mdc?**
+Newer Cursor versions read `AGENTS.md` directly; many teams run versions that
+don't, or want explicit rule scoping. The generated `.mdc` is harmless if
+redundant — and you can exclude it: `agentsbridge sync -t claude,copilot,...`.
+
+**Does it send my code anywhere?**
+No. No network calls, no telemetry, no API keys. It's a template engine over
+one markdown file. [Zero dependencies](pyproject.toml).
+
+**How is this different from X?**
+rulesync (Node.js) covers more features — MCP servers, subagents, commands —
+at the cost of a bigger footprint and a `.rulesync/` directory convention.
+agentsbridge does one thing: keep rule *files* in sync, in pure Python with
+zero dependencies. If you live in `pipx`/`uv` and want the simple thing, this
+is for you.
+
+## Development
+
+```bash
+git clone https://github.com/DavidStarYu/agentsbridge
+cd agentsbridge
+pip install -e . pytest ruff
+pytest            # 36 tests
+ruff check .
+```
+
+## License
+
+[MIT](LICENSE)

agentsbridge-0.1.0/README.md

@@ -0,0 +1,166 @@
+<div align="center">
+
+<img src="assets/banner.svg" alt="agentsbridge" width="640">
+
+**One `AGENTS.md`. Every AI coding tool. Zero drift.**
+
+[![CI](https://github.com/DavidStarYu/agentsbridge/actions/workflows/ci.yml/badge.svg)](https://github.com/DavidStarYu/agentsbridge/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/agentsbridge)](https://pypi.org/project/agentsbridge/)
+[![Python](https://img.shields.io/pypi/pyversions/agentsbridge)](https://pypi.org/project/agentsbridge/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+[Bridge](#why) · [Quick start](#quick-start) · [Supported tools](#supported-tools) · [CI drift check](#ci-drift-check) · [FAQ](#faq)
+
+</div>
+
+---
+
+## Why
+
+Your team uses Claude Code. Your teammate uses Cursor. Someone just switched
+to Codex CLI. And suddenly your coding standards live in **five different
+files** that silently drift apart:
+
+```text
+AGENTS.md                          ← Codex, Gemini CLI, Jules, Amp, Zed read this
+CLAUDE.md                          ← Claude Code reads this (not AGENTS.md)
+.github/copilot-instructions.md    ← GitHub Copilot reads this (not AGENTS.md)
+.cursor/rules/*.mdc                ← Cursor reads this (not AGENTS.md, older versions)
+.windsurfrules / .clinerules       ← Windsurf / Cline read these
+CONVENTIONS.md                     ← Aider reads this
+```
+
+`agentsbridge` fixes this with one command. You maintain **one** `AGENTS.md`
+(the emerging industry standard) — it generates and keeps every tool's file
+in sync. Edit once, sync everywhere, and let CI catch anything that drifts.
+
+## Quick start
+
+```bash
+pipx install agentsbridge        # or: pip install agentsbridge / uv tool install agentsbridge
+```
+
+**Already have rules somewhere?** Import them:
+
+```bash
+agentsbridge import              # seeds AGENTS.md from CLAUDE.md, .cursorrules, etc.
+```
+
+**Starting fresh?**
+
+```bash
+agentsbridge init                # creates a starter AGENTS.md
+```
+
+Then — the only command you'll ever need again:
+
+```bash
+agentsbridge sync
+```
+
+```text
+  + created   CLAUDE.md
+  + created   .github/copilot-instructions.md
+  + created   .cursor/rules/agentsbridge.mdc
+  + created   .windsurfrules
+  + created   .clinerules
+  + created   CONVENTIONS.md
+
+wrote 6 file(s)
+```
+
+Edit `AGENTS.md`, run `agentsbridge sync`, commit. That's the whole workflow.
+
+## Supported tools
+
+| Tool | File generated | Notes |
+|---|---|---|
+| **Claude Code** | `CLAUDE.md` | |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | |
+| **Cursor** | `.cursor/rules/agentsbridge.mdc` | with `alwaysApply` frontmatter |
+| **Windsurf** | `.windsurfrules` | |
+| **Cline** | `.clinerules` | |
+| **Aider** | `CONVENTIONS.md` | |
+| **Codex CLI, Gemini CLI, Jules, Amp, Zed, opencode** | — | read `AGENTS.md` natively, nothing to generate |
+
+Missing a tool? [Open an issue](https://github.com/DavidStarYu/agentsbridge/issues) —
+adding a target is ~10 lines.
+
+## Safety
+
+Generated files are marked:
+
+```markdown
+<!-- generated by agentsbridge; do not edit -->
+```
+
+If a target file already exists **without** that marker (i.e. you wrote it by
+hand), `sync` skips it instead of clobbering your work. Use `--force` to
+adopt it deliberately.
+
+```bash
+agentsbridge sync --force        # adopt existing files
+agentsbridge sync --dry-run      # preview changes
+agentsbridge sync -t claude,copilot   # subset of targets
+```
+
+## CI drift check
+
+The whole point: rules that drift are rules nobody follows. Add the check to
+your workflow and CI fails whenever someone edits a generated file — or
+forgets to re-sync after editing `AGENTS.md`:
+
+```yaml
+# .github/workflows/ci.yml
+name: rules
+on: [push, pull_request]
+jobs:
+  agentsbridge:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DavidStarYu/agentsbridge/action@main
+```
+
+Or invoke the CLI directly: `agentsbridge check` (exit code 1 on drift).
+
+This repository runs the same check on itself — [dogfooding](.github/workflows/rules.yml).
+
+## FAQ
+
+**Why AGENTS.md as the source, not my own config?**
+AGENTS.md is the emerging standard (adopted by OpenAI Codex, Gemini CLI, Jules,
+Amp, Zed and others — see [agents.md](https://agents.md)). Tools that don't
+read it yet are exactly the ones this bridge targets. You keep zero
+agentsbridge-specific config: the source file is a standard.
+
+**Cursor already reads AGENTS.md, why generate an .mdc?**
+Newer Cursor versions read `AGENTS.md` directly; many teams run versions that
+don't, or want explicit rule scoping. The generated `.mdc` is harmless if
+redundant — and you can exclude it: `agentsbridge sync -t claude,copilot,...`.
+
+**Does it send my code anywhere?**
+No. No network calls, no telemetry, no API keys. It's a template engine over
+one markdown file. [Zero dependencies](pyproject.toml).
+
+**How is this different from X?**
+rulesync (Node.js) covers more features — MCP servers, subagents, commands —
+at the cost of a bigger footprint and a `.rulesync/` directory convention.
+agentsbridge does one thing: keep rule *files* in sync, in pure Python with
+zero dependencies. If you live in `pipx`/`uv` and want the simple thing, this
+is for you.
+
+## Development
+
+```bash
+git clone https://github.com/DavidStarYu/agentsbridge
+cd agentsbridge
+pip install -e . pytest ruff
+pytest            # 36 tests
+ruff check .
+```
+
+## License
+
+[MIT](LICENSE)

agentsbridge-0.1.0/agentsbridge/__init__.py

@@ -0,0 +1,3 @@
+"""agentsbridge - Bridge AGENTS.md to every AI coding tool's rules file."""
+
+__version__ = "0.1.0"

agentsbridge-0.1.0/agentsbridge/cli.py

@@ -0,0 +1,174 @@
+"""agentsbridge CLI - bridge AGENTS.md to every AI coding tool's rules file."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__, core
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agentsbridge",
+        description=(
+            "Bridge AGENTS.md to every AI coding tool's rules file. "
+            "Maintain one source of truth; generate CLAUDE.md, "
+            "copilot-instructions.md, Cursor rules, and more."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    p_sync = sub.add_parser("sync", help="generate all target rules files from AGENTS.md")
+    p_sync.add_argument(
+        "-t",
+        "--targets",
+        default="",
+        help="comma-separated subset of targets (default: all)",
+    )
+    p_sync.add_argument(
+        "--force", action="store_true", help="overwrite files not generated by agentsbridge"
+    )
+    p_sync.add_argument(
+        "--dry-run", action="store_true", help="show what would change without writing"
+    )
+
+    p_check = sub.add_parser(
+        "check", help="exit non-zero if any generated file drifted from AGENTS.md (for CI)"
+    )
+    p_check.add_argument(
+        "-t",
+        "--targets",
+        default="",
+        help="comma-separated subset of targets (default: all)",
+    )
+
+    p_import = sub.add_parser(
+        "import", help="seed AGENTS.md from an existing rules file (CLAUDE.md, .cursorrules, ...)"
+    )
+    p_import.add_argument("--out", default="AGENTS.md", help="output path (default: AGENTS.md)")
+
+    p_init = sub.add_parser("init", help="create a starter AGENTS.md")
+    p_init.add_argument("--force", action="store_true", help="overwrite existing AGENTS.md")
+
+    return parser
+
+
+def _parse_targets(value: str) -> list[str] | None:
+    value = value.strip()
+    if not value:
+        return None
+    return [v.strip() for v in value.split(",") if v.strip()]
+
+
+def _root() -> Path:
+    return Path.cwd()
+
+
+def cmd_sync(args: argparse.Namespace) -> int:
+    root = core.walk_up(_root())
+    try:
+        results = core.sync(
+            root, _parse_targets(args.targets), force=args.force, dry_run=args.dry_run
+        )
+    except FileNotFoundError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    except ValueError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+    label = "would create/update" if args.dry_run else "wrote"
+    for r in results:
+        icon = {
+            "created": "+",
+            "updated": "~",
+            "unchanged": "=",
+            "skipped": "!",
+            "missing": "?",
+        }.get(r.action, " ")
+        detail = f"  ({r.detail})" if r.detail else ""
+        print(f"  {icon} {r.action:<9} {r.path}{detail}")
+    created = sum(1 for r in results if r.action in ("created", "updated"))
+    skipped = sum(1 for r in results if r.action == "skipped")
+    print(
+        f"\n{label} {created} file(s)"
+        + (f", skipped {skipped}" if skipped else "")
+        + (" (dry run)" if args.dry_run else "")
+    )
+    return 0
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    root = core.walk_up(_root())
+    try:
+        clean, results = core.check(root, _parse_targets(args.targets))
+    except FileNotFoundError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    except ValueError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+    for r in results:
+        icon = {"ok": "=", "drifted": "!", "missing": "?", "skipped": "-"}.get(r.action, " ")
+        detail = f"  ({r.detail})" if r.detail else ""
+        print(f"  {icon} {r.action:<9} {r.path}{detail}")
+    if clean:
+        print("\nall target files are up to date")
+        return 0
+    print("\ndrift detected: run `agentsbridge sync` to fix", file=sys.stderr)
+    return 1
+
+
+def cmd_import(args: argparse.Namespace) -> int:
+    root = _root()
+    try:
+        body, src = core.import_source(root)
+    except FileNotFoundError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+
+    out_path = root / args.out
+    if out_path.exists():
+        print(f"error: {out_path} already exists. Delete it first or use --out.", file=sys.stderr)
+        return 1
+    out_path.write_text(body.rstrip() + "\n", encoding="utf-8")
+    print(f"created {out_path} from {src.name}")
+    print("review it, then run `agentsbridge sync` to propagate.")
+    return 0
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    root = _root()
+    if (root / core.SOURCE_FILENAME).exists() and not args.force:
+        print("AGENTS.md already exists (use --force to overwrite)")
+        return 0
+    r = core.ensure_agents_md(root, dry_run=False)
+    if r.action == "created":
+        print(f"created {r.path}")
+        print("edit it, then run `agentsbridge sync`")
+    return 0
+
+
+COMMANDS = {
+    "sync": cmd_sync,
+    "check": cmd_check,
+    "import": cmd_import,
+    "init": cmd_init,
+}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not args.command:
+        parser.print_help()
+        return 0
+    return COMMANDS[args.command](args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())