piagentsync 0.0.3rc2

Sync OpenCode agents and skills from an Obsidian vault to workspace directories

piagentsync

Sync OpenCode agents and skills from an Obsidian vault to workspace directories.

Install

uv add piagentsync
# or
pip install piagentsync

Quick start

1. Initialize a new project in your vault:

piagentsync init myproject --workspace ~/workspace/myproject

2. Pull the synced files to your workspace:

piagentsync pull myproject

Configuration

Environment variables (also configurable via .env file):

Variable	Default	Description
PIAGENTSYNC_VAULT_PATH	~/vault	Path to Obsidian vault
PIAGENTSYNC_GLOBAL_OPENCODE_PATH	~/.config/opencode	Path to global OpenCode config

CLI reference

piagentsync pull <project>

Sync a single project from vault to workspace.

Options:

• --dry-run / --no-dry-run — preview changes without writing
• --global / --no-global — also sync global agents
• --all — sync all discovered projects

piagentsync status [project]

Show diff between vault and workspace.

Options:

• --all — show status for all projects (default when no project given)

piagentsync init <project>

Scaffold a new project in the vault.

Options:

• --workspace PATH — required, workspace directory
• --notion-board-id TEXT — optional Notion DB ID
• --notion-project-filter TEXT — optional Notion project filter (defaults to project slug)

--version

Print version and exit.

AGENTS.md manifest format

Each project must have an AGENTS.md file in its root with YAML frontmatter:

---
project: myproject
workspace: ~/workspace/myproject
notion_board_id: 3305f9479a8d8055b3c3e86a9006cf91
notion_project_filter: myproject
---

The body below the frontmatter is the OpenCode routing table.

Expected vault structure

vault/
├── agents/
│   └── global/
│       └── *.md
└── projects/
    └── {project}/
        ├── AGENTS.md           # manifest with frontmatter
        ├── context.md          # optional context file
        ├── decisions.md        # optional decisions log
        ├── agents/
        │   └── *.md
        └── skills/
            └── *.md

Contributing

Development setup:

uv sync
uv run pytest

Lint and format:

uv run ruff check src/ tests/
uv run ruff format src/ tests/

All commits follow Conventional Commits.

Publishing (maintainers)

This repository uses GitHub Actions for CI and automated releases.

One-time PyPI setup (trusted publisher)

1. Enable OIDC on PyPI for the repository:

   • Publisher: GitHub Actions
   • Repository owner: Piwero
   • Repository name: piagentsync
   • Workflow filename: release.yml
   • Environment name: (leave blank)

2. The Release workflow handles everything: bump version, create tag, build, publish to PyPI, and create a GitHub Release.

Release process

git push → ci.yml passes
   → trigger release.yml (choose MAJOR/MINOR/PATCH/RC)
       → tests re-run → changelog generated → version bumped → tag pushed
       → GitHub Release created with assets → package published to PyPI

License

MIT