npm package: @qzzqzzb/camo
Description: CLI for switching isolated Codex and Claude Code workflows
Latest version: 0.3.1

<p align="center">
  <img src="./assets/camo.png" alt="Camo logo" width="220" />
</p>

<h1 align="center">Camo</h1>

<p align="center">
  <a href="https://www.npmjs.com/package/@qzzqzzb/camo"><img src="https://img.shields.io/npm/v/%40qzzqzzb%2Fcamo" alt="npm version" /></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License" /></a>
  <img src="https://img.shields.io/badge/node-%3E%3D20-blue" alt="Node >=20" />
  <img src="https://img.shields.io/badge/tests-57%20passing-brightgreen" alt="Tests: 57 passing" />
</p>

<p align="center"><strong>Camo is like conda for Codex and Claude Code workflows.</strong></p>

<p align="center">It adds a <code>workflow</code> layer between global config and project config, so you can keep different capability stacks isolated and switch between them with one command.</p>

## Quick Start

### Install

```bash
npm install -g @qzzqzzb/camo
```

### Create a workflow and use it with Codex

```bash
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`](https://github.com/hesreallyhim/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`](https://github.com/obra/superpowers) and [`gstack`](https://github.com/garrytan/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

```bash
# 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:

```bash
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:

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

### Workflow creation modes

```bash
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

```bash
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

```bash
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 `git@github.com:<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:

```text
$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:

```bash
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:

```text
$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

```bash
npm install
npm test
npm run build
```

## License

MIT