piagentsync 0.2.2rc1

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
PIAGENTSYNC_VAULT_GITHUB_USER	Piwero	GitHub username for vault repository (used in clone instructions)

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)

piagentsync bootstrap

Bootstrap machine from an existing vault. This is a one‑time setup to configure OpenCode and install global agents.

Options:

• --force — overwrite existing opencode.json if present

Steps performed:

1. Verifies that the vault exists (PIAGENTSYNC_VAULT_PATH). If missing, prints a helpful git clone command.
2. Writes {PIAGENTSYNC_GLOBAL_OPENCODE_PATH}/opencode.json with Notion and Obsidian MCPs and disables tool globs. Skips if file exists unless --force is used.
3. Runs opencode mcp auth notion interactively to authenticate with Notion. If opencode is not on PATH, a warning is printed and the step is skipped.
4. Copies {vault}/agents/global/chief-pm.md to {PIAGENTSYNC_GLOBAL_OPENCODE_PATH}/agents/chief-pm.md, overwriting if the content has changed.

All steps produce clear Rich output and non‑critical warnings. The command exits 1 only if the vault is missing or a file write fails.

--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