Import Workflows

Import workflow packages from local directories, GitHub repositories, or any git URL.

Quick Start

codemachine import ./my-workflow
codemachine import user/repo
codemachine import https://github.com/user/repo

/import ./my-workflow
/import user/repo
/import https://github.com/user/repo

After importing, your workflow appears in the selection menu when you run codemachine.

Source Formats

CodeMachine supports multiple import source formats:

Format	Example	Resolution
Local path (absolute)	`/path/to/folder`	local-path
Local path (relative)	`./my-package` or `../other`	local-path
Local path (home)	`~/projects/my-workflow`	local-path
Short name	`package-name`	github-search
Owner/repo	`user/repo`	github-repo
Full URL	`https://github.com/user/repo`	github-repo
Git SSH	`git@github.com:user/repo.git`	git-url

Resolution Priority

When you run an import, CodeMachine checks sources in this order:

Local path — if it’s absolute, starts with ./, ../, or ~
HTTPS URLs — full GitHub or git URLs
Git SSH URLs — git@ format
Owner/repo format — checks if local path exists first
Short name — searches GitHub for matching packages

Local Imports

Import workflows from your local filesystem for development and testing.

Path Formats

# Absolute path
codemachine import /home/user/my-workflows

# Relative path
codemachine import ./my-local-package
codemachine import ../shared-workflows

# Home directory
codemachine import ~/projects/codemachine-prompts

Local imports require a valid manifest file (codemachine.json or .codemachine.json) in the source directory.

Local Path Resolution

For a path to be recognized as local, it must:

Be an absolute path (starts with /)
Start with ./ or ../ (relative)
Start with ~ (home directory)
Contain a valid manifest file

GitHub Imports

Import workflows directly from GitHub repositories.

By Owner/Repo

codemachine import username/my-workflow-codemachine

By Full URL

codemachine import https://github.com/username/my-workflow-codemachine

By Short Name

Search GitHub for packages by name:

codemachine import my-workflow

Short name search looks for repositories with the -codemachine suffix on GitHub.

Git SSH

codemachine import git@github.com:user/repo.git

Manifest Files

Every importable package needs a manifest file (codemachine.json or .codemachine.json) at the root with name and version fields.

For details on creating and configuring manifest files, see Publish Workflow.

Validation Requirements

Both local and remote imports must pass validation:

Manifest Present

Must have codemachine.json or .codemachine.json with name and version fields.

Config Directory

Must have config/main.agents.js with agent definitions.

Workflow Files

Must have at least one .workflow.js file in the workflows directory.

Prompts Directory (Optional)

If missing, you’ll see a warning but import will proceed.

Import Location

Imported packages are stored in:

~/.codemachine/imports/{name}-codemachine/

For example, importing a package named codemachine-one creates:

~/.codemachine/imports/codemachine-one-codemachine/
├── codemachine.json
├── config/
│   ├── main.agents.js
│   └── ...
├── templates/
│   └── workflows/
│       └── codemachine-one.workflow.js
└── prompts/
    └── ...

Examples

Import Local Development Package

# Create a local package
mkdir -p ~/my-workflow/config ~/my-workflow/templates/workflows

# Add manifest
echo '{"name": "my-workflow", "version": "1.0.0"}' > ~/my-workflow/codemachine.json

# Add required files...

# Import it
codemachine import ~/my-workflow

Import from GitHub

# By owner/repo
codemachine import username/my-workflow-codemachine

# By short name (searches GitHub)
codemachine import my-workflow

# By full URL
codemachine import https://github.com/username/my-workflow-codemachine

Import Using TUI

Within CodeMachine, use the /import command:

/import ./my-local-package
/import username/my-workflow-codemachine

Troubleshooting

Import fails with 'manifest not found'

Ensure your package has either codemachine.json or .codemachine.json at the root level with valid name and version fields.

Import fails with 'missing main.agents.js'

Create config/main.agents.js with at least one agent definition:

module.exports = [
  {
    id: 'my-agent',
    name: 'My Agent',
    description: 'Agent description',
    promptPath: './prompts/my-agent.md'
  }
];

Import fails with 'no workflow files'

Create at least one .workflow.js file in templates/workflows/:

export default {
  steps: [
    resolveStep('my-agent'),
  ],
};

Local path not recognized

Make sure your path:

Starts with / (absolute), ./, ../ (relative), or ~ (home)
Points to an existing directory
Contains a valid manifest file

Next Steps

Publish Workflow

Share your workflow with others on GitHub

Build Workflows

Configuration

Share Workflows

Quick Start

Source Formats

Resolution Priority

Local Imports

Path Formats

Local Path Resolution

GitHub Imports

By Owner/Repo

By Full URL

By Short Name

Git SSH

Manifest Files

Validation Requirements

Import Location

Examples

Import Local Development Package

Import from GitHub

Import Using TUI

Troubleshooting

Next Steps

Publish Workflow

​Quick Start

​Source Formats

​Resolution Priority

​Local Imports

​Path Formats

​Local Path Resolution

​GitHub Imports

​By Owner/Repo

​By Full URL

​By Short Name

​Git SSH

​Manifest Files

​Validation Requirements

​Import Location

​Examples

​Import Local Development Package

​Import from GitHub

​Import Using TUI

​Troubleshooting

​Next Steps

Publish Workflow

Quick Start

Source Formats

Resolution Priority

Local Imports

Path Formats

Local Path Resolution

GitHub Imports

By Owner/Repo

By Full URL

By Short Name

Git SSH

Manifest Files

Validation Requirements

Import Location

Examples

Import Local Development Package

Import from GitHub

Import Using TUI

Troubleshooting

Next Steps