piagentsync 0.3.1rc3

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

3. If you made edits in the workspace and want to push them back into the vault:

piagentsync push 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 push <project>

Sync a single project from workspace back to the vault. This is the inverse of pull and is intended for bootstrapping the vault from existing workspaces or pushing emergency/local edits back into the vault (the user is expected to review and commit the vault afterwards).

Options:

• --dry-run — preview what would be pushed without writing
• --global — also push global agents from your local global opencode config into vault/agents/global/
• --all — push all discovered projects

Behavior notes:

• Direction: workspace (.opencode/) → vault
• Conflict rule: workspace wins (files in the vault will be overwritten if different)
• Unchanged files are skipped using hash comparison
• After a successful push the CLI will print a reminder to run: cd ~/vault && git add -A && git commit -m "..." && git push

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/

Type checking (MyPy)

We use strict mypy checks for the codebase. To run type checking locally:

uv run mypy src/ tests/ --strict

Notes:

• The repository includes a py.typed marker so the package is PEP-561 compatible.
• Pre-commit runs ruff (format + lint). Running mypy in pre-commit was avoided due to isolated pre-commit environments — instead run mypy manually or add it to CI for consistent enforcement.

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