aidriven

aidriven

aidriven is a Python library and CLI that helps developers discover AI-oriented IDEs and install AI resources — skills, agents, and specs — into the correct locations for each AI coding assistant.

---

Features

• aidriven install — fetch and install AI skills from aidriven-resources for Claude Code, GitHub Copilot, and more
• IDE Discovery — detects locally installed AI-oriented IDEs (VS Code, Cursor, Kiro) across Windows, macOS, and Linux
• Multi-target installs — install one skill for multiple AI targets in a single command
• Canonical placement — one copy under .agents/skills/<name>/, symlinks from each AI's read path (follows the vercel-labs/skills model)
• Reproducible — lockfile (aidriven-lock.json) records the source commit SHA and content hash for every install
• Graceful degradation — partial or corrupted IDE installations are returned with a reduced confidence level rather than silently dropped
• Zero runtime dependencies — stdlib only

---

Installation

Requires Python 3.11+.

pip install aidriven

Or with uv:

uv add aidriven

---

CLI: aidriven install

Install a skill for one AI target

aidriven install skill code-reviewer --ai claude

Creates:

• .agents/skills/code-reviewer/ — canonical shared directory (all AI targets read from here)
• .claude/skills/code-reviewer → .agents/skills/code-reviewer — directory symlink for Claude Code
• aidriven-lock.json — updated with source SHA, content hash, and target list

Re-running the same command is a no-op — the CLI detects that the content is already up to date and exits 0 without modifying any files.

Install a skill for multiple AI targets

aidriven install skill code-reviewer --ai claude --ai copilot

A single canonical copy is placed at .agents/skills/code-reviewer/. Claude Code gets a symlink; Copilot reads .agents/skills/ directly so no symlink is needed.

Install at user scope

aidriven install skill code-reviewer --ai claude --scope user

Installs to ~/.agents/skills/code-reviewer/ with a symlink at ~/.claude/skills/code-reviewer. Records the entry in the user lockfile (~/.cache/aidriven/install-records.json on Linux/macOS or %LOCALAPPDATA%\aidriven\install-records.json on Windows) instead of the project lockfile.

Auto-detect AI targets

When exactly one supported AI target is detected in the current project, --ai can be omitted:

aidriven install skill code-reviewer

If zero or multiple targets are detected, the command exits with code 6 and lists what was found with instructions to specify --ai explicitly.

Preview without writing (dry run)

aidriven install skill code-reviewer --ai claude --ai copilot --dry-run

Prints the install plan — which actions would be taken for each target — without touching the filesystem or lockfile. Combine with --json for machine-readable output.

Force re-fetch

aidriven install skill code-reviewer --ai claude --force

Bypasses the local cache and re-downloads the skill tarball. Useful after upstream changes or to verify integrity. Also overwrites files that were modified after installation.

Copy mode

aidriven install skill code-reviewer --ai claude --ai copilot --copy

Places independent copies of the skill files at each AI target's read path instead of using a canonical directory + symlinks. Useful in environments where symlinks are not supported. Lockfile records installMode: "copy".

Machine-readable output

aidriven install skill code-reviewer --ai claude --json

Emits a single JSON object on stdout — no spinners or color — regardless of TTY:

{
  "request": { "artifactType": "skill", "name": "code-reviewer", "targets": ["claude"], "scope": "project", "mode": "symlink", "force": false, "dryRun": false },
  "sourceCommitSha": "a1b2c3d4…",
  "computedHash": "sha256:e5f6…",
  "lockfilePath": "/your/project/aidriven-lock.json",
  "targets": [
    {
      "target": "claude",
      "action": "install_new",
      "finalMode": "symlink",
      "readPath": "/your/project/.claude/skills/code-reviewer",
      "canonicalPath": "/your/project/.agents/skills/code-reviewer",
      "error": null
    }
  ],
  "success": true,
  "exitCode": 0
}

All options

Exit codes

The lockfile

aidriven-lock.json is placed at the project root and is designed to be committed to version control. It is deterministic — keys are sorted, content is stable across runs with identical inputs — so diffs are meaningful.

{
  "version": 1,
  "skills": {
    "code-reviewer": {
      "source": "aidriven-resources",
      "sourceCommitSha": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
      "computedHash": "sha256:e5f6…",
      "targets": ["claude", "copilot"],
      "scope": "project",
      "installMode": "symlink"
    }
  }
}

Library API

Every CLI invocation maps 1:1 to a single library call:

from aidriven.install import install_artifact, InstallRequest, ArtifactType, Scope, InstallMode

result = install_artifact(InstallRequest(
    artifact_type=ArtifactType.SKILL,
    name="code-reviewer",
    targets=("claude", "copilot"),
    scope=Scope.PROJECT,
    mode=InstallMode.SYMLINK,
    force=False,
    dry_run=False,
    assume_yes=False,
))

for tr in result.target_results:
    print(tr.target, tr.action_taken)

---

Library: IDE Discovery

Discover installed IDEs

from aidriven.discovery import discover_ides

result = discover_ides()

for ide in result.detected_ides:
    print(ide.identifier, ide.display_name, ide.version, ide.confidence)

Each DetectedIDE entry contains:

Register a custom provider

from aidriven.discovery import discover_ides, ProviderRegistry

registry = ProviderRegistry()
registry.register(MyCustomIDEProvider())

result = discover_ides(registry=registry)

---

Development

This project uses uv for dependency management.

# Install dependencies (including dev extras)
uv sync

# Run tests with coverage
uv run pytest

# Lint
uv run ruff check .

# Format check
uv run ruff format --check .

# Type check
uv run mypy src/

# Serve docs locally
uv run mkdocs serve

---

Contributing

1. Fork the repository and create a feature branch.
2. Install dev dependencies and set up pre-commit hooks:

uv sync
uv tool install pre-commit
pre-commit install

3. Make your changes, add tests, and ensure all checks pass:

pre-commit run --all-files
uv run pytest

4. Open a pull request against main.

Bug reports and feature requests are welcome via GitHub Issues.

---

License

MIT — see LICENSE.