agentfiles 0.5.0

Sync AI tool configurations (agents, skills, commands, plugins) for OpenCode

agentfiles

Sync AI tool configurations for OpenCode

pip install agentfiles

---

agentfiles is a CLI that keeps your OpenCode AI coding assistant configurations — agents, skills, commands, and plugins — in sync. Treat a source repository as the single source of truth and propagate changes to your local OpenCode config.

Why?

You manage OpenCode agents, skills, commands, and plugins across multiple machines or projects. agentfiles lets you maintain one repository and sync everywhere:

source repo ──────── OpenCode (~/.config/opencode/)
(agents/skills/
 commands/plugins)

Features

• OpenCode support — agents, skills, commands, plugins, configs, and workflows
• Bidirectional sync — pull and push with conflict detection
• Surgical filtering — --only, --except, --type, --item agent/coder, --scope
• PR creation — push --create-pr to auto-create a pull request via gh
• Smart cloning — shallow clone + sparse checkout for remote sources
• Dry-run — preview changes without applying
• Diagnostics — doctor, verify (CI drift detection), shell completions
• One dependency — pyyaml only

Quick Start

pip install agentfiles

# Initialize a new repository
agentfiles init

# Pull to OpenCode
agentfiles pull /path/to/source-repo

# Pull only agents
agentfiles pull --type agent

# Preview without applying
agentfiles pull --dry-run

Commands

Command	Description
pull	Install/update items from source to local OpenCode config
push	Push local items back to source (with conflict detection)
status	Show installed items (--list, --diff)
clean	Remove orphaned items
init	Scaffold a new repository
verify	CI-friendly drift detection (exit 1 if drift)
doctor	Run environment diagnostics
completion	Generate shell completion scripts

pull

Install or update items from a source repository to your local OpenCode config.

agentfiles pull                                    # interactive (default)
agentfiles pull --yes                              # non-interactive
agentfiles pull --update                           # git pull source, then sync
agentfiles pull --type agent                       # only agents
agentfiles pull --only coder,solid-principles      # specific items
agentfiles pull --item agent/coder                 # single item by key
agentfiles pull --dry-run --verbose                # preview with details
agentfiles pull --symlinks                         # use symlinks instead of copies
agentfiles pull --full-clone                       # disable shallow clone optimization
agentfiles pull --scope global                     # only global-scope items
agentfiles pull --scope project --project-dir .    # project-scope items to current dir

push

Push locally-installed items back into the source repository. Useful when you've edited configs on one machine and want to propagate.

agentfiles push                         # interactive (with conflict detection)
agentfiles push --yes                   # non-interactive (skips conflicts)
agentfiles push --dry-run               # preview
agentfiles push --item agent/coder      # push a single item
agentfiles push --create-pr             # auto-create PR via gh
agentfiles push --create-pr --pr-title "Update agents" --pr-branch my-branch

status

Show installed-item information. Supports two sub-modes via flags:

• --list — list items available in the source repository
• --diff — compare source vs installed items

agentfiles status                            # show overview
agentfiles status --format json              # JSON output

# --list mode: list source items
agentfiles status --list                     # text table
agentfiles status --list --tokens            # include token estimates
agentfiles status --list --format json       # machine-readable

# --diff mode: compare source vs installed
agentfiles status --diff                     # show differences
agentfiles status --diff --verbose           # content-level diffs
agentfiles status --diff --format json       # machine-readable

clean

Remove installed items whose source no longer exists in the repository.

agentfiles clean --dry-run      # preview
agentfiles clean --yes          # non-interactive

init

Scaffold a new agentfiles repository with agents/, skills/, commands/, plugins/ directories and a .agentfiles.yaml config.

agentfiles init                              # current directory
agentfiles init /path/to/project             # specific directory
agentfiles init --yes                        # skip confirmation

verify

CI-friendly drift detection. Compares source vs installed items, exits 0 if in sync, 1 if drift detected.

agentfiles verify                    # human-readable output
agentfiles verify --format json      # machine-readable
agentfiles verify --quiet            # silent, exit code only

doctor

Run environment diagnostics — checks config, source dir, git, platform directory, state file, and tool binaries.

agentfiles doctor

completion

Generate shell completion scripts.

agentfiles completion bash    # bash completions
agentfiles completion zsh     # zsh completions
agentfiles completion fish    # fish completions

# Example: add to .bashrc
eval "$(agentfiles completion bash)"

Global Options

--color {always,auto,never}   Color output control (respects NO_COLOR/FORCE_COLOR)
--verbose, -v                 Verbose output
--quiet, -q                   Quiet mode (errors only)
--version                     Show version

Filter Options

Most commands support surgical filtering:

--type {agent,skill,command,plugin,config,workflow,all} Item type
--only coder,solid-principles                          Only these items (by name)
--except old-plugin,deprecated                         Exclude these items
--item agent/coder                                     Specific item by type/name key
--scope {global,project,local,all}                     Filter by scope

Source Repository Structure

my-agents/
├── agents/
│   ├── coder/
│   │   └── coder.md              # YAML frontmatter + prompt
│   └── debugger/
│       └── debugger.md
├── skills/
│   ├── solid-principles/
│   │   ├── SKILL.md
│   │   └── references/
│   └── dry-principle/
│       └── SKILL.md
├── commands/
│   └── autopilot/
│       └── autopilot.md
├── plugins/
│   └── patterns.yaml
├── configs/
│   └── global-settings.yaml
├── workflows/
│   └── deploy-pipeline/
│       └── workflow.md
└── .agentfiles.yaml              # Config (auto-generated)

Supported Platform

Platform	Config path	Agents	Skills	Commands	Plugins	Configs	Workflows
OpenCode	~/.config/opencode/	✅	✅	✅	✅	✅	✅

Architecture

graph LR
    A["Source Resolution<br/><code>source.py</code>"] --> B["Scanner<br/><code>scanner.py</code>"]
    B --> C["Differ<br/><code>differ.py</code>"]
    C --> D["Engine<br/><code>engine.py</code>"]
    D --> E["SyncResult[]"]
    E --> F["SyncReport"]

    G["Target<br/><code>target.py</code>"] --> C
    H["Config<br/><code>config.py</code>"] --> D

Module	Purpose
source.py	Resolve user input → local directory (local dir, git URL, git clone)
scanner.py	Walk source dirs → list[Item]
differ.py	Compare source vs installed: existence → metadata → SHA-256
engine.py	Plan actions (INSTALL/UPDATE/SKIP) → execute → collect results
target.py	Discover OpenCode config directory, manage installed items
config.py	YAML config + sync-state persistence
cli.py	Argparse CLI with all subcommands

CI Pipeline

graph TD
    Lint["ruff check + format"] --> Gate{"CI Gate"}
    TypeCheck["mypy strict"] --> Gate
    Security["bandit"] --> Gate
    Test["pytest × 4 Pythons"] --> Gate
    Gate -->|on Release| Publish["PyPI Publish"]

Extending

Add a new item type:

1. Add ItemType enum value in models.py
2. Write a scanner function in scanner.py
3. Register via _register_scanner()

No other modules need changes (Open/Closed Principle).

Development

# Install with dev dependencies
uv sync --dev

# Lint & format
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/

# Type check
uv run mypy src/

# Security scan
uv run bandit -r src/ -c pyproject.toml

# Test
uv run pytest tests/ -v

# Test with coverage
uv run pytest tests/ -v --cov=agentfiles --cov-report=term-missing

# Build package
uv run python -m build

License

MIT