{"_id":"@bundt/cleo","_rev":"2-cffce18bb113027ade12642758c2423e","name":"@bundt/cleo","dist-tags":{"alpha":"0.1.0-alpha.0","latest":"0.1.0"},"versions":{"0.1.0-alpha.0":{"name":"@bundt/cleo","version":"0.1.0-alpha.0","keywords":["claude","claude-code","agents","skills","cli","bun","ai","mcp","orchestrator"],"license":"MIT","_id":"@bundt/cleo@0.1.0-alpha.0","maintainers":[{"name":"mega-blastoise","email":"rustycloud42@protonmail.com"}],"homepage":"https://github.com/mega-blastoise/bundt/tree/main/apps/cleo","bugs":{"url":"https://github.com/mega-blastoise/bundt/issues"},"bin":{"cleo":"dist/cleo.mjs","bun-cleo":"bin/cleo.ts"},"dist":{"shasum":"20dec4420f4cebc59c96876087eb2d6f355c0e55","tarball":"https://registry.npmjs.org/@bundt/cleo/-/cleo-0.1.0-alpha.0.tgz","fileCount":98,"integrity":"sha512-iZRL6CyUcAEnIs5oDDz5asqoUPMB+/K5RvhV98LN2lV9LLXGBbbSQJ6l2mHlETzR6fuh49HVf801Rr9n0w5d+g==","signatures":[{"sig":"MEUCIGIEt79+X5XFdLErGKgar3+APpFHOMJvcn8BWUBS3T+9AiEA3dqvLIoVCeEdI8yKNATpSsMHY+9/aNWz2teHdZu8xE0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":481505},"type":"module","engines":{"bun":">=1.3"},"exports":{".":{"bun":"./dist/cli.bun.js","types":"./dist/index.d.ts","import":"./dist/cli.bun.js","default":"./dist/cli.bun.js"}},"gitHead":"2b7109209c9f3bac08a791f1825f102d17e44ec5","scripts":{"dev":"bun run src/cli.ts","test":"echo 'No tests yet'","build":"bun run build:bundle && bun run build:types","clean":"rm -rf dist","prebuild":"rm -rf dist","typecheck":"tsc --noEmit","build:types":"tsc -p tsconfig.build.json","build:bundle":"bun build/index.ts"},"_npmUser":{"name":"mega-blastoise","email":"rustycloud42@protonmail.com"},"repository":{"url":"git+https://github.com/mega-blastoise/bundt.git","type":"git","directory":"apps/cleo"},"_npmVersion":"11.6.2","description":"Claude extensions orchestrator. Manage, run, and share Claude Code agents and skills.","directories":{},"_nodeVersion":"24.13.0","dependencies":{"cac":"^6.7.0","zod":"^4.0.0","marked":"^17.0.3","fuse.js":"^7.1.0","picocolors":"^1.1.0","front-matter":"^4.0.2","@inquirer/prompts":"^8.3.0","@bit-context-protocol/driver":"^0.1.0-alpha.0"},"publishConfig":{"tag":"alpha","access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","typescript":"^5.9.0","@bundt/internal-node-shim":"workspace:*","@bundt/internal-build-utils":"workspace:*"},"_npmOperationalInternal":{"tmp":"tmp/cleo_0.1.0-alpha.0_1772823412286_0.2672179573490767","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@bundt/cleo","version":"0.1.0","type":"module","description":"Claude extensions orchestrator. Manage, run, and share Claude Code agents and skills.","license":"MIT","repository":{"type":"git","url":"git+https://github.com/mega-blastoise/bundt.git","directory":"apps/cleo"},"homepage":"https://github.com/mega-blastoise/bundt/tree/main/apps/cleo","bugs":{"url":"https://github.com/mega-blastoise/bundt/issues"},"bin":{"cleo":"dist/cleo.mjs","bun-cleo":"bin/cleo.ts"},"keywords":["claude","claude-code","agents","skills","cli","bun","ai","mcp","orchestrator"],"exports":{".":{"bun":"./dist/cli.bun.js","import":"./dist/cli.bun.js","types":"./dist/index.d.ts","default":"./dist/cli.bun.js"}},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/","tag":"latest"},"engines":{"bun":">=1.3"},"scripts":{"dev":"bun run src/cli.ts","prebuild":"rm -rf dist","build:types":"tsc -p tsconfig.build.json","build:bundle":"bun build/index.ts","build":"bun run build:bundle && bun run build:types","typecheck":"tsc --noEmit","test":"echo 'No tests yet'","clean":"rm -rf dist"},"dependencies":{"@bit-context-protocol/driver":"^0.1.0","@inquirer/prompts":"^8.3.0","cac":"^6.7.0","front-matter":"^4.0.2","fuse.js":"^7.1.0","marked":"^17.0.3","picocolors":"^1.1.0","zod":"^4.0.0"},"devDependencies":{"@bundt/internal-build-utils":"workspace:*","@bundt/internal-node-shim":"workspace:*","@types/bun":"latest","typescript":"^5.9.0"},"gitHead":"2b7109209c9f3bac08a791f1825f102d17e44ec5","_id":"@bundt/cleo@0.1.0","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-kBIpvpOrD8auhuWMp2WjuJcX/6lnJV9a34NjfyIk82es0jIwjUP25F4KAJ8zCIkBOs3wZ/9tfGLD0UCcDIgF8A==","shasum":"ac6cb4c62c9baa3b995fe658a50b08492700b5d9","tarball":"https://registry.npmjs.org/@bundt/cleo/-/cleo-0.1.0.tgz","fileCount":99,"unpackedSize":490615,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDrxzLm6HCQzI47KhxzSHDHCjipQS/sksbwmNJ8jcy++wIgDm87kVmiGIWSweCiA2bb4QL4KjrdidkawkkKBcS2J+k="}]},"_npmUser":{"name":"mega-blastoise","email":"rustycloud42@protonmail.com"},"directories":{},"maintainers":[{"name":"mega-blastoise","email":"rustycloud42@protonmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cleo_0.1.0_1772825105200_0.9290784730399577"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-06T18:56:52.149Z","modified":"2026-03-06T19:25:05.469Z","0.1.0-alpha.0":"2026-03-06T18:56:52.449Z","0.1.0":"2026-03-06T19:25:05.359Z"},"bugs":{"url":"https://github.com/mega-blastoise/bundt/issues"},"license":"MIT","homepage":"https://github.com/mega-blastoise/bundt/tree/main/apps/cleo","keywords":["claude","claude-code","agents","skills","cli","bun","ai","mcp","orchestrator"],"repository":{"type":"git","url":"git+https://github.com/mega-blastoise/bundt.git","directory":"apps/cleo"},"description":"Claude extensions orchestrator. Manage, run, and share Claude Code agents and skills.","maintainers":[{"name":"mega-blastoise","email":"rustycloud42@protonmail.com"}],"readme":"# @bundt/cleo\n\nClaude extensions orchestrator. Manage, discover, install, and run Claude Code agents and skills from the command line.\n\n> **Status:** Pre-release (0.1.0). Core CLI, agent lifecycle, task runner, TUI, and BCP integration are implemented. Registry is scaffolded but not yet live.\n\n## Install\n\n```bash\n# Global install (recommended)\nbun add -g @bundt/cleo\n\n# Or run directly\nbunx @bundt/cleo\n```\n\n## Features\n\n- **Agent lifecycle management** — Install, uninstall, validate, and rollback agents and skills with full history tracking\n- **Headless task runner** — Run tasks through Claude Code with structured JSON output, cost tracking, and token reporting\n- **Interactive task builder** — Build token-efficient context from files, command output, and documents with priority-based BCP encoding\n- **Fuzzy search** — Search local and registry agents/skills with deep body matching via Fuse.js\n- **Interactive TUI** — Full terminal UI for managing multiple concurrent Claude Code sessions with vim-style navigation\n- **BCP integration** — First-class Bit Context Protocol support for token-efficient context delivery\n- **Task templates** — Save and reuse task definitions; batch-dispatch multiple templates from the TUI\n- **Qualified names** — Namespace/name:tag@version addressing for agents and skills (ADR-001)\n- **Skill authoring** — Scaffold, validate, and submit skills to the registry\n\n## Commands\n\n### Task Execution\n\n```bash\n# Run a task through Claude Code (headless, structured output)\ncleo run \"refactor auth module to use functional patterns\"\ncleo run --model claude-opus-4-6 --max-budget 2.00 \"implement the spec\"\n\n# Run with BCP context (token-efficient binary context)\ncleo run --bcp ./project-context.bcp --budget 8000 \"implement feature X\"\n\n# Interactive task builder — gather files, commands, docs, then execute\ncleo task \"fix the failing tests\"\ncleo task --dry-run \"explore the codebase\"\n\n# Task templates\ncleo task --save my-review          # Save current task as a template\ncleo task --template my-review      # Reload a saved template\ncleo task --list                    # List saved templates\ncleo task --list --global           # List global templates (~/.claude/tasks/)\n```\n\n### Agent Management\n\n```bash\n# Discover agents\ncleo list                           # List available agents (bundled, global, local)\ncleo info <agent>                   # Show agent details and frontmatter\ncleo search \"code review\"           # Search for agents and skills\ncleo search --deep --type skill \"testing\"  # Fuzzy body search, filter by type\n\n# Install/uninstall\ncleo install code-reviewer          # Install to .claude/agents/\ncleo install --global code-reviewer # Install to ~/.claude/agents/\ncleo uninstall code-reviewer        # Remove agent and orphaned skills\n\n# Scaffold new agents and skills\ncleo init my-agent -d \"My custom agent\" -t \"Read,Write,Bash\"\ncleo create-skill my-skill -d \"Reusable skill for X\"\n\n# Validate structure and references\ncleo validate                       # Validate all local agents\ncleo validate my-agent --global     # Validate specific global agent\n```\n\n### Configuration & History\n\n```bash\n# Configuration\ncleo config get registry.url\ncleo config set registry.url https://registry.example.com\ncleo config --global get theme\n\n# History and rollback\ncleo history                        # View recent operations\ncleo history --action install -l 10 # Filter by action, limit results\ncleo history --id <event-id> --detail  # Show full event details\ncleo rollback my-agent              # Restore to previous snapshot\ncleo rollback my-agent --to <id> --dry-run  # Preview rollback\n```\n\n### Interactive TUI\n\n```bash\ncleo tui\n```\n\nThe TUI provides a multi-session terminal interface for Claude Code:\n\n| Key | Action |\n|-----|--------|\n| `n` | New session (with model/agent/template selection) |\n| `D` | Dispatch — batch-launch multiple task templates |\n| `j/k` | Navigate sessions (sidebar) or scroll output (main) |\n| `i` | Enter chat mode (send follow-up to waiting session) |\n| `d` | Kill running session |\n| `x` | Dismiss completed session |\n| `t` | Cycle color theme |\n| `Tab` | Toggle focus between sidebar and main panel |\n| `1-9` | Jump to session by number |\n| `?` | Help |\n| `q` | Quit (confirms if sessions are running) |\n\nThe TUI supports `Ctrl+T` in the new-session modal to pick from saved task templates, which auto-populates the prompt, model, and BCP context.\n\n## Agent Frontmatter Schema\n\nAgents are Markdown files with YAML frontmatter:\n\n```markdown\n---\nname: code-reviewer\ndescription: Reviews code changes for quality, patterns, and bugs\ntools:\n  - Read\n  - Bash\n  - Grep\n  - Glob\nmodel: claude-sonnet-4-6\nskills:\n  - typescript-patterns\n  - testing-standards\nnamespace: bundt\nversion: 1.0.0\ntag: latest\n---\n\nYour agent system prompt goes here...\n```\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `name` | string | yes | Kebab-case agent name |\n| `description` | string | yes | What the agent does |\n| `tools` | string[] | yes | Claude Code tools this agent uses |\n| `model` | string | no | Preferred model |\n| `skills` | string[] | no | Referenced skill directories |\n| `namespace` | string | no | Registry namespace (default: `_`) |\n| `version` | string | no | Semver version |\n| `tag` | string | no | Distribution tag (default: `latest`) |\n| `deprecated` | string \\| boolean | no | Deprecation notice |\n\n## BCP Integration\n\nCleo is a first-class consumer of the [Bit Context Protocol](https://github.com/mega-blastoise/bit-context-protocol). When a `.bcp` file is provided via `--bcp`, Cleo:\n\n1. Validates the file via `driver.validate()`\n2. Inspects block count and total size via `driver.inspect()`\n3. Decodes with adaptive verbosity when `--budget` is set (low-priority blocks are summarized to fit)\n4. Injects the decoded context into Claude Code's system prompt as `<bcp-context>...</bcp-context>`\n\nThe `cleo task` command builds BCP context programmatically using the Context Builder API — gathering source files, command output, and documents with priority levels, then encoding them into a `.bcp` stream.\n\n## Structured Output\n\n`cleo run` uses Claude Code's `--json-schema` mode to enforce structured responses:\n\n```typescript\n{\n  summary: string;        // Brief summary of what was done\n  filesChanged: string[]; // Absolute paths of files created/modified/deleted\n  errors: string[];       // Any errors encountered (empty if none)\n}\n```\n\nToken usage, cost, and duration are reported after each run.\n\n## Architecture\n\n```\napps/cleo/\n  src/\n    cli.ts                  CLI entry — 14 commands via cac\n    schema.ts               Structured output schema (Zod 4)\n    types.ts                Qualified names, frontmatter schemas, validation types\n    prompt.ts               System prompt template\n    helpers.ts              File system helpers, agent loading\n    ui.ts                   Terminal output helpers (picocolors)\n\n    commands/               Command implementations\n      run.ts                Headless task runner (spawns claude CLI)\n      task.ts               Interactive task builder\n      list.ts, info.ts      Agent discovery\n      install.ts            Agent + skill installation with history recording\n      uninstall.ts          Removal with orphan skill cleanup\n      search.ts             Fuzzy search (Fuse.js)\n      init.ts               Agent scaffolding\n      create-skill.ts       Skill scaffolding\n      validate.ts           Structure validation\n      config.ts             Key-value config management\n      history.ts            Operation history viewer\n      rollback.ts           Snapshot restoration\n      submit.ts             Registry submission\n\n    task/                   Task builder subsystem\n      gather.ts             Interactive context gathering (inquirer)\n      execute.ts            BCP assembly + Claude execution\n      review.ts             Pre-execution context review\n      schema.ts             Task definition types\n      templates.ts          Template save/load\n\n    tui/                    Interactive terminal UI\n      index.ts              Event loop + key handling\n      render.ts             ANSI rendering\n      session.ts            Claude Code process management\n      state.ts              Application state\n      terminal.ts           Raw mode + ANSI helpers\n      keys.ts               Key parsing\n      themes.ts             Color theme cycling\n      tasks.ts              Template integration\n      workflows.ts          Multi-step workflows\n\n    integrations/\n      bcp.ts                BCP driver integration\n\n    registry/               Agent/skill registry (scaffolded)\n      index.ts, schemas.ts, search.ts, submit.ts\n\n    history/                Operation history\n      db.ts                 SQLite-backed event store\n      recorder.ts           Event recording\n```\n\n## Requirements\n\n- [Bun](https://bun.sh) v1.3+\n- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed and authenticated\n- Optional: `bcp` binary for BCP context support (`cargo install bcp-cli`)\n\n## License\n\nMIT\n","readmeFilename":"README.md"}