artifacts-os

Python library for storing, discovering, and managing structured markdown artifacts (tasks, specs, agents, research) in a vault directory.

Install

pip install artifacts-os

Editable install with dev dependencies:

pip install -e ".[dev]"

Optional extras: views (Rich rendering), cli, tui (Textual browser), log, ai, all.

Quick Start

from artifacts_os import find_vault_root, Registry, KindDef, create, get, list_artifacts

# Locate the vault (walks up from CWD looking for artifacts.yaml)
root = find_vault_root()

# Define artifact kinds
kinds = [
    KindDef(name="task", dir="tasks", prefix="t", numbered=True,
            statuses=["backlog", "ready", "in-progress", "done"],
            schema={}, meta={}),
    KindDef(name="agent", dir="agents", prefix="", numbered=False,
            statuses=[], schema={}, meta={}),
]
registry = Registry(kinds, root=root)

# Create an artifact
artifact = create(registry, "task", "Fix the login bug")
print(artifact.id)   # t0001

# List artifacts
tasks = list_artifacts(registry, kind="task", status="ready")

# Read a single artifact
task = get(registry, "t0001")
print(task.body)

CLI

Init

Bootstrap a new artifacts-os project with the two-stage guided flow:

# Interactive (prompts for tier, kinds, agents on a TTY)
artifacts init

# Non-interactive — accept all defaults
artifacts init -y

# Fully specified
artifacts init --template standard --kinds task,note,spec --agents architect,developer

# Preview without writing
artifacts init --template minimal --kinds all --agents all --dry-run

# Bootstrap from a distro — pulls books and creates tool-shaped views automatically
artifacts init --distro https://github.com/my-org/artbook-defaults -y

Distros that declare promote: in their books ship with automatic promotion — pulled files land under artifacts/ (canonical) and are also surfaced at tool-specific paths (e.g., .claude/agents/) via symlinks, so both artifacts list and the consuming tool see the same content without any manual linking step. See docs/artbook.md for the full artbook author and consumer reference.

See docs/init-flow.md for the complete two-stage flow, settings tier reference, and flag documentation.

Common commands

artifacts list --kind task --status ready
artifacts show t0001
artifacts create "My new task" --kind task
artifacts status t0001 in-progress

Project Structure

src/artifacts_os/
  __init__.py    # re-exports core public API
  core/          # storage, discovery, registry (fully implemented)
  views/         # formatting layer — column layout, Rich rendering (shipped)
  log/           # JSONL operation log (stub — spec: s2063)
  cli/           # command-line interface — argument parsing, dispatch (shipped)
  tui/           # interactive terminal browser (stub — spec: s2065)
  ai/            # agent context and execution (stub — spec: s2066)
tests/           # mirrors src/; uses tmp_path + make_vault fixture, no mocking
docs/            # architecture, settings, per-module guides

Development

pip install -e ".[dev]"

pytest                            # run all tests
pytest tests/core/test_store.py  # run a single file

Coding conventions:

• Full type annotations on all public functions
• Dataclasses for models (KindDef, ArtifactMeta, Artifact)
• Atomic writes: O_CREAT | O_EXCL for create, os.replace for update
• No mocking in tests — all tests operate on real temp-dir vaults

Documentation

Guides

Page	Summary
docs/architecture.md	Package overview, module map, dependency DAG, design principles
docs/artbook.md	Artbook distros — authoring artbook.yaml, promotion mechanism, consumer behaviour, migration guide
docs/settings.md	Cross-cutting settings: public API, extension pattern, schema versioning
docs/events.md	Event catalog, JSONL stream format, artifacts events CLI reference
docs/hooks.md	Declarative hooks — shell, notify, file-drop actions; phase, blocking, env vars
docs/adding-a-kind.md	How to add a new artifact kind — ARTIFACT.md description contract, L1 catalogue surface, evaluation-first authoring, kind.json schema reference
docs/init-flow.md	artifacts init two-stage flow — settings tiers, distro book loop, variable interpolation, non-TTY behaviour

Module References

Module	Summary
core	Storage, discovery, registry, settings, validation — foundational layer
views	Formatting layer — column specs, field formatting, Rich table rendering, ViewsSettings
cli	artifacts CLI — all commands with flags and examples

License

MIT © 2026 Leon Prouger