Archon supports user-level (global) workflows, commands, and scripts placed directly inDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/coleam00/Archon/llms.txt
Use this file to discover all available pages before exploring further.
~/.archon/—they are loaded automatically in every project without any configuration. This is distinct from project-level files in .archon/ (which only apply to one repo) and from bundled defaults shipped with the Archon binary. This page covers the directory paths, load priority, subfolder support, use cases, dotfiles syncing, and how to migrate from the old path.
Paths
ARCHON_HOME:
These directories are direct children of
~/.archon/—the same level as workspaces/, archon.db, and config.yaml. Earlier Archon versions stored global workflows at ~/.archon/.archon/workflows/ (with an extra nested .archon/). See Migrating from the old path if you have files there.Load priority
When Archon discovers workflows, commands, and scripts, it merges them in this order (higher overrides lower on filename collision):- Bundled defaults (lowest) —
archon-*workflows/commands embedded in the Archon binary - Global / home-scoped —
~/.archon/workflows/,~/.archon/commands/,~/.archon/scripts/ - Repo-specific (highest) —
<repoRoot>/.archon/workflows/,<repoRoot>/.archon/commands/,<repoRoot>/.archon/scripts/
.archon/workflows/. Global workflows and commands carry the source: 'global' label in the Web UI node palette.
Subfolders (1 level deep)
Each directory supports one level of subfolders for grouping—matching thedefaults/ convention:
~/.archon/commands/ (or within <repoRoot>/.archon/commands/), across whatever subfolders you use.
CLI and Web support
Both the CLI and the Web UI discover home-scoped content automatically—no flag or config option needed:~/.archon/commands/ appear under a Global (~/.archon/commands/) section in the node palette, distinct from project and bundled entries.
Use cases
Personal code review workflow
A workflow that runs your preferred review checklist on every project:~/.archon/workflows/my-review.yaml
Code quality check
~/.archon/workflows/lint-check.yaml
Quick explain for unfamiliar codebases
~/.archon/workflows/explain.yaml
Personal command helpers
Commands in~/.archon/commands/ are available to every workflow on the machine. Useful for prompts you reuse across projects:
~/.archon/commands/review-checklist.md
Reusable script helper
A triage formatter that you want available in every repo:~/.archon/scripts/triage-fmt.ts
Syncing with dotfiles
If you manage configuration with a dotfiles repository, include your global Archon content:Migrating from the old path
Pre-refactor versions of Archon stored global workflows at~/.archon/.archon/workflows/ (with a doubly-nested .archon/). That path is no longer read.
If you have workflows at the old location, Archon emits a one-time deprecation warning on first use with the exact migration command:
~/.archon/commands/ is new capability with nothing to migrate.
Troubleshooting
Workflow not appearing in list
Workflow not appearing in list
-
Check the path — The directory must be exactly
~/.archon/workflows/(a direct child of~/.archon/, not the old double-nested~/.archon/.archon/workflows/): -
Check file extension — Workflow files must end in
.yamlor.yml. -
Check YAML validity — A syntax error causes the workflow to appear in the errors list rather than the workflow list:
- Check for name conflicts — If a repo-specific workflow has the same filename, it overrides the global one. The global version won’t appear when you’re in that repo.
-
Check
ARCHON_HOME— If you’ve setARCHON_HOMEto a custom path, global workflows must be at$ARCHON_HOME/workflows/, not~/.archon/workflows/.
Command not found by workflow
Command not found by workflow
- Verify the file exists at
~/.archon/commands/<name>.md - Check for name conflicts with repo-local commands — repo wins by filename
- Run
archon validate commands my-commandto check for load errors
Script not resolving
Script not resolving
Scripts are resolved by basename without extension. Ensure the file exists at
~/.archon/scripts/<name>.ts (for bun) or ~/.archon/scripts/<name>.py (for uv) and that the runtime: on the node matches the file extension.Related pages
Authoring Workflows
Full workflow YAML reference including file discovery rules.
Authoring Commands
Write reusable markdown command files.
Script Nodes
Named scripts in
.archon/scripts/ and ~/.archon/scripts/.CLI Reference
archon workflow list and archon validate commands.