Publish Workflow

Share your workflow package by publishing it to a public GitHub repository. Others can then import it using the codemachine import command.

Prerequisites

Before publishing, ensure your workflow package has:

A valid manifest file (codemachine.json)
At least one agent definition in config/main.agents.js
At least one workflow file in your workflows directory

Create the Manifest

Every publishable package needs a codemachine.json file at the repository root.

Minimal Manifest

For packages using the default directory structure:

codemachine.json

{
  "name": "my-workflow",
  "version": "1.0.0"
}

Full Manifest

For packages with custom directory layouts or additional metadata:

codemachine.json

{
  "name": "my-workflow",
  "version": "1.0.0",
  "description": "A workflow for building React applications",
  "paths": {
    "config": "config",
    "workflows": "templates/workflows",
    "prompts": "prompts",
    "characters": "config/agent-characters.json"
  }
}

Required Fields

Field	Description
`name`	Package identifier (must be unique)
`version`	Semantic version (e.g., `1.0.0`)

Optional Fields

Field	Description
`description`	Brief description of the workflow
`paths`	Custom paths for package resources

Custom Paths

If your repository has an existing structure that doesn’t match the defaults, use the paths field to map your directories.

Default Paths

When paths is omitted, CodeMachine uses these defaults:

Resource	Default Path
Config	`config/`
Workflows	`templates/workflows/`
Prompts	`prompts/`
Characters	`config/agent-characters.json`

When to Use Custom Paths

New Repository
Existing Repository

If you’re creating a new repository for your workflow, use the default structure—no paths configuration needed.

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

If you’re adding a workflow to an existing repository with its own structure, define custom paths:

codemachine.json

{
  "name": "my-workflow",
  "version": "1.0.0",
  "paths": {
    "config": "src/codemachine/config",
    "workflows": "src/codemachine/workflows",
    "prompts": "src/codemachine/prompts"
  }
}

Publish to GitHub

Initialize Repository

Create a new GitHub repository or use an existing one.

# New repository
mkdir my-workflow-codemachine
cd my-workflow-codemachine
git init

Add Manifest

Create your codemachine.json at the repository root.

echo '{
  "name": "my-workflow",
  "version": "1.0.0"
}' > codemachine.json

Add Required Files

Ensure you have the required configuration and workflow files.

mkdir -p config templates/workflows prompts
# Add your main.agents.js, workflow files, and prompts

Push to GitHub

Commit and push to a public repository.

git add .
git commit -m "Initial workflow package"
git remote add origin https://github.com/username/my-workflow-codemachine.git
git push -u origin main

Your repository must be public for others to import it. GitHub private repositories cannot be fetched by the import system.

After Publishing

Once published, users can import your workflow using any of these formats:

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

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

# By short name (if using -codemachine suffix)
codemachine import my-workflow

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

The imported workflow will be available in the workflow selection menu when running codemachine.

Private Workflows

If you prefer to keep your workflow private, you can share it via local import instead of publishing to a public repository.

For private workflows, share the package directory directly and have users import it locally. See Import Workflows - Local Imports for details.

Naming Conventions

For discoverability, consider using the -codemachine suffix in your repository name:

my-workflow-codemachine
react-builder-codemachine
api-generator-codemachine

This allows users to import by short name:

codemachine import my-workflow

CodeMachine searches GitHub for repositories matching {name}-codemachine when using short name imports.

Build Workflows

Configuration

Share Workflows

Prerequisites

Create the Manifest

Minimal Manifest

Full Manifest

Required Fields

Optional Fields

Custom Paths

Default Paths

When to Use Custom Paths

Publish to GitHub

After Publishing

Private Workflows

Naming Conventions

​Prerequisites

​Create the Manifest

​Minimal Manifest

​Full Manifest

​Required Fields

​Optional Fields

​Custom Paths

​Default Paths

​When to Use Custom Paths

​Publish to GitHub

​After Publishing

​Private Workflows

​Naming Conventions

Prerequisites

Create the Manifest

Minimal Manifest

Full Manifest

Required Fields

Optional Fields

Custom Paths

Default Paths

When to Use Custom Paths

Publish to GitHub

After Publishing

Private Workflows

Naming Conventions