Skip to content

livery.extensions.claude._agent

livery.extensions.claude._agent

What Claude Code reads in a workspace, answered for the workshop's engine.

The extension's extension.toml names these functions as its [fragments] renders: the workshop calls each with the workspace root while a workspace lists the extension, and writes what it answers. CLAUDE.md is committed; .workshop/fragments/ and .claude/ belong to the checkout alone.

Functions:

Name Description
entry_file

CLAUDE.md: an import per delivered fragment, the own ones, the project's.

guidance_files

.workshop/fragments/: each fragment the agent reads, by delivered name.

claude_files

.claude/: each listed extension's skills and hooks, and one settings.json.

Attributes:

Name Type Description
DELIVERED
OWN
STUB_HEADER

The CLAUDE.md stub's header, formatted with the runner's name.

DELIVERED module-attribute

DELIVERED = '.workshop/fragments'

OWN module-attribute

OWN = 'fragments'

STUB_HEADER module-attribute

STUB_HEADER = "<!-- Managed by `{prog} sync`: one import per fragment, in section\n     order, the repository's own fragments/ after them, then its\n     CLAUDE.project.md, which always wins. Edit CLAUDE.project.md,\n     never this file. -->\n"

The CLAUDE.md stub's header, formatted with the runner's name.

entry_file

entry_file(root: Path) -> str

CLAUDE.md: an import per delivered fragment, the own ones, the project's.

Reads the composition guidance_files made just before it in the delivery; rendered on its own, it composes for itself.

Source code in packages/extensions/claude/src/livery/extensions/claude/_agent.py
def entry_file(root: Path) -> str:
    """``CLAUDE.md``: an import per delivered fragment, the own ones, the project's.

    Reads the composition `guidance_files` made just before it in the
    delivery; rendered on its own, it composes for itself.
    """
    kept = _COMPOSED.pop(root, None)
    files, own = kept if kept is not None else _delivered(root)
    stub = STUB_HEADER.format(prog=footman.prog())
    stub += "".join(f"@{DELIVERED}/{name}\n" for name in files)
    stub += "".join(f"@{OWN}/{name}\n" for name in own)
    return stub + "@CLAUDE.project.md\n"

guidance_files

guidance_files(root: Path) -> dict[str, str]

.workshop/fragments/: each fragment the agent reads, by delivered name.

Declared before the entry file, so the entry file reads this composition instead of making its own.

Source code in packages/extensions/claude/src/livery/extensions/claude/_agent.py
def guidance_files(root: Path) -> dict[str, str]:
    """``.workshop/fragments/``: each fragment the agent reads, by delivered name.

    Declared before the entry file, so the entry file reads this
    composition instead of making its own.
    """
    composed = _delivered(root)
    _COMPOSED[root] = composed
    return composed[0]

claude_files

claude_files(root: Path) -> dict[str, str | Path]

.claude/: each listed extension's skills and hooks, and one settings.json.

A skill or a hook is a link into the shipping extension's content, and a later extension's entry of one name takes an earlier one's place. The settings are a copy, which the agent's tooling may edit, and at most one extension ships them.

Source code in packages/extensions/claude/src/livery/extensions/claude/_agent.py
def claude_files(root: Path) -> dict[str, str | Path]:
    """``.claude/``: each listed extension's skills and hooks, and one settings.json.

    A skill or a hook is a link into the shipping extension's content,
    and a later extension's entry of one name takes an earlier one's
    place. The settings are a copy, which the agent's tooling may edit,
    and at most one extension ships them.
    """
    found: dict[str, str | Path] = {}
    settings = ""
    for extension, content in shipped_content(root):
        for kind in ("skills", "hooks"):
            shipped = content / kind
            if not shipped.is_dir():
                continue
            for entry in sorted(shipped.iterdir()):
                if entry.name.startswith(".") or entry.name == "__pycache__":
                    continue
                found[f"{kind}/{entry.name}"] = entry
        source = content / "settings.json"
        if source.is_file():
            if settings:
                fail(
                    f".claude/settings.json has one owner, and {settings}"
                    f" and {extension} both ship it"
                )
            settings = extension
            text = source.read_text(encoding="utf-8")
            found["settings.json"] = text.replace("\r\n", "\n")
    return found