Skip to main content
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
After importing, your workflow appears in the selection menu when you run codemachine.

​
Source Formats

CodeMachine supports multiple import source formats:
FormatExampleResolution
Local path (absolute)/path/to/folderlocal-path
Local path (relative)./my-package or ../otherlocal-path
Local path (home)~/projects/my-workflowlocal-path
Short namepackage-namegithub-search
Owner/repouser/repogithub-repo
Full URLhttps://github.com/user/repogithub-repo
Git SSH[email protected]:user/repo.gitgit-url

​
Resolution Priority

When you run an import, CodeMachine checks sources in this order:
  1. Local path — if it’s absolute, starts with ./, ../, or ~
  2. HTTPS URLs — full GitHub or git URLs
  3. Git SSH URLs — git@ format
  4. Owner/repo format — checks if local path exists first
  5. 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 [email protected]: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:
1

Manifest Present

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

Config Directory

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

Workflow Files

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

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

Ensure your package has either codemachine.json or .codemachine.json at the root level with valid name and version fields.
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'
  }
];
Create at least one .workflow.js file in templates/workflows/:
export default {
  steps: [
    resolveStep('my-agent'),
  ],
};
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