> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codemachine.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Import Workflows

> Install workflows from local directories, GitHub, and other git repositories.

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

***

## Quick Start

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    codemachine import ./my-workflow
    codemachine import user/repo
    codemachine import https://github.com/user/repo
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /import ./my-workflow
    /import user/repo
    /import https://github.com/user/repo
    ```
  </Tab>
</Tabs>

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:

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

```bash theme={null}
# 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
```

<Info>
  Local imports require a valid manifest file (`codemachine.json` or `.codemachine.json`) in the source directory.
</Info>

### 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

```bash theme={null}
codemachine import username/my-workflow-codemachine
```

### By Full URL

```bash theme={null}
codemachine import https://github.com/username/my-workflow-codemachine
```

### By Short Name

Search GitHub for packages by name:

```bash theme={null}
codemachine import my-workflow
```

<Note>
  Short name search looks for repositories with the `-codemachine` suffix on GitHub.
</Note>

### Git SSH

```bash theme={null}
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.

<Info>
  For details on creating and configuring manifest files, see [Publish Workflow](/build-workflows/publish-workflow#create-the-manifest).
</Info>

***

## Validation Requirements

Both local and remote imports must pass validation:

<Steps>
  <Step title="Manifest Present">
    Must have `codemachine.json` or `.codemachine.json` with `name` and `version` fields.
  </Step>

  <Step title="Config Directory">
    Must have `config/main.agents.js` with agent definitions.
  </Step>

  <Step title="Workflow Files">
    Must have at least one `.workflow.js` file in the workflows directory.
  </Step>

  <Step title="Prompts Directory (Optional)">
    If missing, you'll see a warning but import will proceed.
  </Step>
</Steps>

***

## 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

```bash theme={null}
# 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

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Import fails with 'missing main.agents.js'">
    Create `config/main.agents.js` with at least one agent definition:

    ```javascript theme={null}
    module.exports = [
      {
        id: 'my-agent',
        name: 'My Agent',
        description: 'Agent description',
        promptPath: './prompts/my-agent.md'
      }
    ];
    ```
  </Accordion>

  <Accordion title="Import fails with 'no workflow files'">
    Create at least one `.workflow.js` file in `templates/workflows/`:

    ```javascript theme={null}
    export default {
      steps: [
        resolveStep('my-agent'),
      ],
    };
    ```
  </Accordion>

  <Accordion title="Local path not recognized">
    Make sure your path:

    * Starts with `/` (absolute), `./`, `../` (relative), or `~` (home)
    * Points to an existing directory
    * Contains a valid manifest file
  </Accordion>
</AccordionGroup>

***

## Next Steps

<Card title="Publish Workflow" icon="upload" href="/build-workflows/publish-workflow">
  Share your workflow with others on GitHub
</Card>