artifactr 0.0.4

CLI tool for managing AI project artifacts across repositories

Artifactr

A cross-platform CLI tool for managing AI project artifacts. Maintain a personal library of skills, agents, and commands in centralized "vaults" and import them into any git repository for use with AI coding assistants.

Why? 🤔

AI coding agents accumulate configs — skills, agents, commands — and they're usually project-local. Starting a new repo often means rebuilding your environment from scratch.

I develop mostly in cloud VMs via ssh and tmux for security purposes. I got tired of rebuilding my setup every time and desperately wanted a terminal-centric solution. Lo-and-behold: Artifactr

It takes inspiration from local-first note-taking applications like Obsidian and Logseq. No external connections are made. Your vaults contain YOUR files.

Features

• Tool-agnostic storage: Store artifacts once, import to multiple AI tools
• Cross-platform: Works on Linux, macOS, and Windows
• Multiple vaults: Organize artifacts into separate collections with auto-naming (llm-vault-N)
• Vault initialization: Create new vaults from scratch with art vault init
• Artifact creation: Create skills, commands, and agents from the CLI with art create
• Artifact editing: Open artifacts in your terminal editor with art edit
• Selective import: Import specific artifacts by name with --artifacts
• Artifact discovery: Scan any project for existing artifacts with art spelunk
• Artifact collection: Store discovered artifacts back into a vault with art store
• Import tracking: .art-cache/imported records what was imported and from where
• Supported tools: Claude Code, OpenCode, Codex (extensible — add custom tools with art tool add)
• Automatic git exclusion: Adds imported artifacts to .git/info/exclude to protect against accidental commits of project-specific skills & prompts

Installation

Requires Python 3.10+

It's easiest to globally install artifactr via pipx:

pipx install artifactr

Otherwise, you can install via pip (though it's recommended to use a non-system venv):

pip install artifactr

Quickstart

art vault add ~/my-vault
art store ~/repos/existing-project
art import ~/repos/new-project

Usage

Managing Vaults

# Initialize a new vault (creates directory with skills/, agents/, commands/ scaffolding)
art vault init ~/my-vault

# Initialize with a name and set as default
art vault init ~/my-vault --name=favorites --set-default

# Add an existing directory as a vault (auto-named as llm-vault-1, llm-vault-2, etc.)
art vault add ~/my-vault

# Add a vault with an explicit name
art vault add ~/my-vault --name=favorites

# Add and set as default in one step
art vault add ~/my-vault --name=favorites --set-default

# Name or rename an existing vault
art vault name ~/my-vault favorites

# List all vaults
art vault list

# List all vaults with full artifact hierarchy
art vault list --all

# Set default vault (by name or path)
art vault select favorites

# Remove a vault (by name or path)
art vault rm favorites

Vaults added without --name are automatically assigned names using the llm-vault-N pattern. Vault names can be used in place of full directory paths in any command that accepts a vault identifier, including --vault on art import.

Managing Tools

# List supported tools — shows artifact support, source, and aliases
art tool list

# Set default tool (defaults to opencode)
art tool select claude-code

# Aliases work anywhere a tool name is accepted
art tool select claude  # resolves to claude-code

# Show details for a specific tool
art tool show codex

# Add a custom tool (e.g., Cursor IDE)
art tool add cursor --skills .cursor/skills --commands .cursor/commands \
  --global-skills '$HOME/.cursor/skills' --alias cur

# Add a tool scoped to a specific vault
art tool add my-tool --skills .my-tool/skills --vault=team-vault

# Remove a custom tool
art tool rm cursor

Importing Artifacts

# Import artifacts from default vault to default tool
art import ~/repos/my-project

# Import from a specific vault (by name or path)
art import ~/repos/my-project --vault=favorites

# Import for specific tools (overrides default)
art import ~/repos/my-project --tools=claude-code,opencode

# Symlink artifacts instead of copying
art import ~/repos/my-project --link

# Import only specific artifacts by name
art import ~/repos/my-project --artifacts=helping-hand,code-review

# Combine with other flags
art import ~/repos/my-project --vault=favorites --artifacts=helping-hand --link

Imported artifacts are tracked in .art-cache/imported within the target directory, recording which vault and tool each artifact came from.

Creating Artifacts

Create skills, commands, and agents directly from the CLI:

# Create a skill (directory-based, with SKILL.md)
art create skill my-skill -d "A helpful skill" -c "Instructions here"

# Create a command (flat .md file, filename is the name)
art create command deploy-prod -d "Run production deployment"

# Create an agent (flat .md file, name in frontmatter)
art create agent code-reviewer -d "Reviews code changes"

# Add extra frontmatter fields
art create agent my-agent -d "desc" -D model=sonnet -D version=1.0

# Create in a specific vault
art create skill my-skill -d "desc" --vault=favorites

# Create in the current project instead of a vault
art create command my-cmd -d "desc" --here
art create skill my-skill -d "desc" --here --tools=claude-code,opencode

All artifact types require --description / -d. Skills are created as directories with a SKILL.md file; commands and agents are created as flat .md files.

Editing Artifacts

Open an artifact in your terminal editor:

# Edit a skill in the default vault
art edit skill my-skill

# Edit a command or agent
art edit command deploy-prod
art edit agent code-reviewer

# Edit in a specific vault
art edit skill my-skill --vault=favorites

# Edit a project-local artifact
art edit skill my-skill --here

The editor is resolved from $VISUAL, then $EDITOR, then the first available of nano, nvim, vim, vi.

Discovering Artifacts

Scan any directory for existing artifacts across all supported tool config directories:

# Discover artifacts in a project
art spelunk ~/repos/my-project

Example output:

NAME                              TYPE      TOOL      DESCRIPTION
helping-hand (imported: favs)     skill     claude    A helpful assistant
utility-tool                      skill     claude    -
reviewer                          agent     claude    Reviews code changes
deploy                            command   opencode  -

The (imported: ...) marker appears when an artifact was previously imported via art import, showing which vault it came from.

Storing Artifacts

Collect artifacts from a project directory and store them into a vault:

# Store artifacts into default vault
art store ~/repos/my-project

# Store into a specific vault
art store ~/repos/my-project --vault=favorites

You'll be presented with a numbered list of discovered artifacts and can select which ones to store using individual numbers (1), ranges (1-3), comma-separated (1,3,5), combinations (1,3-5), or all.

Vault Structure

vault/
├── vault.yaml          # Optional: portable vault name and tool definitions
├── skills/
│   └── skill-name/
│       ├── SKILL.md
│       └── (supporting files...)
├── agents/
│   └── agent-name.md
└── commands/
    └── command-name.md

The optional vault.yaml file stores a portable vault name and vault-scoped tool definitions. When present, its name takes precedence over the name stored in the global config. Tool definitions in vault.yaml travel with the vault when shared.

Artifacts are copied (or symlinked with --link) to tool-specific directories in the target repo (e.g., .claude/skills/, .opencode/agents/) and automatically excluded from git tracking.