The Polytoken VFS

The Polytoken virtual filesystem (VFS) exposes the prompts, facets, subagents, and supporting resources that ship with Polytoken. Inspect those resources before you write a custom facet, replace a prompt section, or reference a built-in resource from your own configuration.

Use the VFS to compare your customization with Polytoken’s baseline behavior before you customize a facet, subagent, prompt, or resource outside the core engine.

What the VFS contains

Run polytoken vfs ls to see the VFS schemes Polytoken can inspect:

polytoken vfs ls

polytoken://

Run polytoken vfs ls polytoken:// to see the top-level directories in the built-in VFS:

polytoken vfs ls polytoken://

facets/
resources/
subagents/
system_prompts/
themes/

Directory	Contents
facets/	The built-in plan and execute facets. Read these files before you replace a facet or write a related facet.
resources/	Supporting text that built-in prompts or facets reference.
subagents/	Built-in subagent definitions. These files show how Polytoken frames delegated work.
system_prompts/	Base prompt templates and prompt fragments Polytoken uses when Polytoken builds a system prompt.
themes/	Theme files that ship with Polytoken. The built-in default theme lives at themes/default.yaml.

Browse built-in resources

Run polytoken vfs ls with a URI to list a directory. Directory names end with /, and file names do not.

polytoken vfs ls polytoken://system_prompts

polytoken vfs cat prints a file exactly as Polytoken stores the file:

polytoken vfs cat polytoken://facets/plan.md

Every VFS path uses a URI scheme. Polytoken accepts polytoken:// paths for the built-in VFS. Polytoken also accepts file-style polytoken:/// paths, so polytoken:///facets/plan.md and polytoken://facets/plan.md reference the same built-in resource. A bare path such as facets/plan.md is not a VFS path, and Polytoken rejects schemes such as example://facets/plan.md.

Inspect before you extend

Start with the resource closest to the behavior you want to change. When you write a facet, inspect the built-in facet and the prompt that the built-in facet includes with transclude:

polytoken vfs cat polytoken://facets/plan.md
polytoken vfs cat polytoken://system_prompts/facet.md

The built-in facet shows the frontmatter keys, model and tool choices, and prompt framing that Polytoken uses by default. The prompt fragment shows the base instructions the facet includes with transclude("polytoken://system_prompts/facet.md").

You can copy a built-in file as a starting point:

mkdir -p .polytoken/facets
polytoken vfs cat polytoken://facets/plan.md > .polytoken/facets/my-plan.md

Copying is optional. When you write a facet from scratch, use the VFS to compare your design with the prompts, tool choices, and instructions that shape Polytoken’s default model behavior.

Inspect the built-in theme

The built-in default theme lives at polytoken://themes/default.yaml. Copy the file as a starting point for a custom theme:

polytoken vfs cat polytoken://themes/default.yaml > ~/.config/polytoken/themes/my-theme.yaml

The path above is the default location. Polytoken stores user config under $XDG_CONFIG_HOME/polytoken (default: ~/.config/polytoken). If you set XDG_CONFIG_HOME, substitute that directory in the command above.

For the full theme authoring guide, see Themes.

Use VFS paths in templates

Facet and subagent bodies can include built-in resources with transclude:

{{ transclude("polytoken://system_prompts/facet.md") }}

Use the VFS to inspect a resource before you transclude the resource. The VFS shows which resource the URI references. For template rendering behavior, see Templating.

Path format

The built-in VFS uses polytoken:// and polytoken:/// URIs. polytoken vfs ls lists VFS schemes when you omit the URI, and lists resources when you provide a URI. polytoken vfs cat prints a resource from the command line.

Always include the URI scheme. The scheme tells Polytoken which virtual filesystem should handle the path, and polytoken:// names the resources that ship with Polytoken.