Quick Start

Install

npm install -g @qzzqzzb/camo

Create a workflow and use it with Codex

camo create gstack fresh
camo default codex gstack
camo

This creates a workflow, saves it as the default Codex workflow, and launches Codex inside that workflow-scoped environment.

Why Camo

Coding agents are now used for very different kinds of work, from research and planning to implementation, debugging, review, and release automation. Ecosystems like Claude Code already reflect this through collections such as awesome-claude-code, which gather a growing set of skills, hooks, commands, subagents, and workflow patterns.

The problem is that these capabilities do not always belong in the same session. Some projects, such as superpowers and gstack, already behave less like isolated utilities and more like full workflow bundles. That can be very useful, but once several such bundles overlap, the agent becomes noisier, less predictable, and harder to steer. A workflow that injects testing loops, review steps, and implementation-oriented defaults may be helpful during coding, but distracting when you are doing product scoping, requirements breakdown, or early design exploration.

Today, tools like Codex and Claude Code mainly give users global config and project-level config, but not a lightweight named workflow layer between them. As a result, users either overload global config or keep reshaping project config around the workflow they need for the current session.

Other ecosystems eventually needed environment managers for the same reason: Python has conda, and Node.js has nvm and volta.

Camo adds that missing middle layer: workflow-scoped capability configuration — a simple way to switch capability stacks quickly, explicitly, and reversibly.

Common Commands

# launch using the saved default
camo

# launch a specific backend + workflow
camo codex gstack
camo claude review

# set the default backend + workflow
camo default codex gstack

# inspect the current default
camo current

# list workflows
camo list

# create workflows
camo create myworkflow
camo create myworkflow fresh

# import a workflow bundle from GitHub
camo import https://github.com/acme/review-flow

# delete a workflow
camo delete myworkflow

How It Works

A workflow is a named coding-agent environment, such as:

• gstack
• superpowers
• myflow

Each workflow has separate backend-specific state.

Codex

For Codex, Camo launches with:

HOME=~/.camo/workflows/<workflow>/home
CODEX_HOME=~/.camo/workflows/<workflow>/home/.codex

This keeps Codex's own home and ~/.agents discovery inside the workflow-scoped home instead of your real user home.

Claude Code

For Claude Code, Camo launches with:

CLAUDE_CONFIG_DIR=~/.camo/workflows/<workflow>/claude

Workflow creation modes

camo create myworkflow

• clones your existing ~/.codex into home/.codex
• clones your existing ~/.claude into claude/
• injects the built-in camo-workflow-install skill into the workflow Codex home

camo create myworkflow fresh

• does not clone the full backend homes
• copies only a minimal bootstrap set when present
• still injects the built-in camo-workflow-install skill

In fresh mode, the bootstrap files are:

• Codex: auth.json, config.toml
• Claude: settings.json, .claude.json

Import a workflow bundle from GitHub

camo import https://github.com/acme/review-flow

Version 1 accepts these URL forms:

• https://github.com/<owner>/<repo>
• https://github.com/<owner>/<repo>/
• https://github.com/<owner>/<repo>.git

Version 1 rejects SSH-style URLs such as [email protected]:<owner>/<repo>.git and non-GitHub hosts.

When you run camo import, Camo:

1. parses the GitHub URL and derives the workflow name from the repository basename
2. validates that derived name with the normal workflow-name rules
3. clones the repository into a temporary directory
4. verifies that a regular-file camo.setup exists at the repository root
5. creates the workflow with fresh
6. launches Codex for that workflow from your current directory
7. injects a bootstrap prompt that tells Codex to read camo.setup, stay workflow-scoped, and keep protected local bootstrap files intact
8. removes the temporary clone after Codex exits

Version 1 import success means the bootstrap Codex process exited with status 0.

Bundle paths vs runtime paths

A GitHub workflow bundle uses repository-root paths:

• camo.setup
• .codex/
• .claude/

The created workflow uses runtime paths:

• home/.codex/
• claude/

Camo itself does not interpret bundle internals beyond checking root camo.setup. The cloned bundle plus the injected bootstrap prompt are handed to Codex, which performs the actual workflow construction.

Protected local bootstrap files

camo import starts from fresh, so these workflow runtime files are always seeded from the importing machine:

• home/.codex/auth.json
• home/.codex/config.toml
• claude/settings.json
• claude/.claude.json

If the bundle repository contains overlapping files, Codex is instructed not to replace these local versions.

This also defines the future export rule: files that fresh seeds from the importing machine should not be published in an exported bundle.

Export and publish a workflow bundle

Version 1 export is a Codex skill, not a CLI command. Run it from a Camo-managed Codex session for the workflow you want to publish.

A typical invocation inside Codex is:

$camo-export

The export skill:

1. detects the current workflow from CODEX_HOME
2. writes the bundle to ./<workflow> in your current directory
3. exports workflow-level skills from CODEX_HOME/skills and project-level skills from ./.codex/skills
4. flattens all selected skills into bundle-local workflow content under .codex/skills/
5. writes a root camo.setup file for later camo import bootstrap
6. excludes camo-workflow-install and importer-local fresh bootstrap files

If ./<workflow> already exists, export refuses to overwrite it.

A minimal publish flow is:

cd <workflow>
git init
git add .
git commit -m "Publish Camo workflow bundle"
gh repo create <owner>/<repo> --public --source=. --remote=origin --push

For later updates, re-run export into a fresh directory and push the new bundle contents to the same repository.

Enforcement model

Camo hard-enforces only part of the contract:

• workflow creation uses fresh
• workflow runtime env remains workflow-scoped
• root camo.setup must exist
• repository code is not auto-executed before Codex launches

Other rules are prompt-level policy for the bootstrap Codex session:

• use the cloned bundle as the authoritative source of workflow instructions and assets
• keep installation workflow-scoped
• avoid project-level installation
• prefer the built-in camo-workflow-install skill for workflow-local setup flows
• only perform external downloads when camo.setup explicitly requires them, and still keep them workflow-scoped

Cleanup warnings are written to stderr. camo import does not automatically change your default workflow.

Built-in Workflow Install Skill

New workflows include a built-in Codex skill called camo-workflow-install.

Its job is simple: when you are running Codex inside a Camo workflow and ask to install or configure a capability, it helps keep those changes workflow-local instead of leaking into your default global setup.

If you want to invoke it explicitly inside a Camo-spawned Codex session, you can do something like:

$camo-workflow-install git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/gstack
cd ~/gstack && ./setup --host codex

This is useful for tools such as gstack, where the original setup flow may look global at first glance, but should be localized to the current workflow when possible.

Requirements

• macOS or Linux
• Node.js 20+
• codex installed and available on PATH
• claude installed and available on PATH if you want to use Claude Code workflows

Camo launches the backend CLI directly. It does not install Codex or Claude Code for you.

What Camo Does Not Isolate

Camo isolates the user-level workflow environment for the supported coding agent.

It is not a full machine sandbox.

These may still remain shared or external:

• repo-local configuration
• project-level instruction files
• project-local skills or tooling
• system-level policy or config
• external tools installed outside the workflow directory

The mental model is:

Camo switches workflow-scoped coding-agent environments, not the entire machine state.

Development

npm install
npm test
npm run build

License

MIT