Skip to content
/
Tier B A10 Memory engine

ZCC — oh-my-zsh for Claude Code

zcc · Git-on-my-level/zcc · ★ 17 · last commit 2025-09-13

Bring oh-my-zsh concepts (themes as modes, plugins as packs, tmux sessions as tickets) to Claude Code for persistent, context-aware development.

Best whenThe real problem with AI coding tools is not capability but persistent context — swappable modes and ticket tracking solve what CLAUDE.md alone cannot.
Skip ifRe-adding the same CLAUDE.md instructions per project, Context loss after compaction
vs seeds
spec-kit's stat…
Primitive shape 9 total
Commands 3 Subagents 1 Hooks 5
00

Summary

ZCC — "oh-my-zsh for Claude Code"

ZCC (z-claude-code) is an npm-published CLI framework (v1.1.0) that brings oh-my-zsh-style concepts to Claude Code: swappable AI personality "modes" (architect, engineer, reviewer), persistent task "tickets" tracked in .zcc/, installable "packs" (curated bundles of modes + workflows + agents + hooks), and a fuzzy-match command dispatcher. The analogy is intentional — modes are like themes, tickets are like tmux sessions, external packs are like oh-my-zsh plugins. Installation deploys 3 slash commands (/mode, /ticket, /zcc) and optional hooks that inject git context, project overview, and acronym expansion on every prompt. The CLI binary zcc handles initialization, pack management, source registration, and community pack discovery from external GitHub repos.

differs_from_seeds: Most similar to spec-kit (structured CLI, curated command set, hook lifecycle) but ZCC's differentiator is the "mode" system — swappable behavioral personas loaded from .zcc/modes/ files, analogous to zsh themes. Unlike spec-kit's static command/skill mirroring, ZCC's modes are dynamic and user-extensible. The ticket system for persistent cross-session task tracking also has no direct seed counterpart.

01

Overview

Overview — ZCC

Origin

Created by Git-on-my-level. npm package z-claude-code, version 1.1.0. Last commit: 2025-09-13. TypeScript codebase.

Philosophy (verbatim from README)

"Transform Claude Code from a basic AI assistant into a project-aware, context-intelligent development powerhouse."

"Just as zsh transformed terminals with themes and plugins, zcc transforms Claude Code with modes, tickets, and hooks."

Problem statement (verbatim)

"Claude Code breaks down as your codebase grows:

  • Re-adding the same CLAUDE.md instructions across projects
  • Claude spams markdown files instead of organized task tracking
  • Goes in circles after context compacting, repeating failed approaches
  • Copy-pasting roleplay prompts: 'Act as engineer...' 'Be a reviewer...'"

oh-my-zsh feature mapping (verbatim)

ZCC Feature What It Does zsh Equivalent
AI Modes Switch personalities (architect/engineer/reviewer) Themes
Tickets Persistent task tracking across sessions tmux sessions
External Packs Install community packs from GitHub oh-my-zsh plugins
Fuzzy Matching /mode eng → finds engineer Smart completions
Hooks Auto-load context, expand acronyms precmd/preexec
Workflows Reusable procedures Functions
Agents Specialized tools Plugins

Starter packs

  • essentials: Core modes + workflows + hooks (routing, git context, project overview, acronym expander)
  • advanced-code-refactoring: Mode + workflows + agent + hook for AST/semantic refactoring

Community packs

External pack sources from GitHub (like oh-my-zsh community themes):

zcc source add awesome-packs --type github --owner community --repo zcc-packs
zcc add pack react-toolkit
02

Architecture

Architecture — ZCC

Distribution

npm package (z-claude-code) + global install.

Install

# Recommended (interactive)
npx zcc init

# Specific pack
npx zcc init --pack essentials
npx zcc init --pack advanced-code-refactoring

# Global
npm install -g z-claude-code
zcc init

Required runtime

  • node>=14 (implied by npm packaging)
  • Claude Code CLI

CLI binary

  • zcc (dist/cli.js)

Directory tree (after zcc init)

<project>/
├── .claude/
│   ├── commands/
│   │   ├── mode.md         # /mode <name> — fuzzy mode switch
│   │   ├── ticket.md       # /ticket — task management
│   │   └── zcc.md          # /zcc — project status
│   └── settings.local.json
├── .zcc/
│   ├── modes/              # AI personality definitions
│   ├── workflows/          # Reusable procedures
│   ├── scripts/
│   │   └── mode-switch.sh  # Fuzzy mode matching
│   └── ...
├── CLAUDE.md               # Injected by zcc init
└── src/ (framework source)
    ├── cli.ts
    ├── commands/
    ├── lib/
    └── types/

Target AI tools

Claude Code (primary). The mode/ticket system is Claude Code-specific.

Config files

  • .zcc/ directory (project-level config)
  • .claude/settings.local.json
  • CLAUDE.md (auto-generated/updated by zcc)
03

Components

Components — ZCC

Commands (3 core)

Command Purpose
/mode [name] List available modes or fuzzy-switch to named mode (e.g., /mode eng → engineer)
/ticket [action] Create, list, move, load persistent task tickets across sessions
/zcc Show project status: active tickets, available modes, available workflows, CLAUDE.md preview

Modes (installed via packs — from essentials pack)

  • autonomous-project-manager
  • engineer
  • architect
  • reviewer
  • ai-debt-maintainer
  • refactoring-specialist (advanced-code-refactoring pack)

Workflows (installed via packs)

  • review
  • summarize
  • openmemory-setup
  • semantic-search (advanced-code-refactoring pack)
  • safe-refactoring (advanced-code-refactoring pack)

Agents (installed via packs)

  • code-archaeologist (advanced-code-refactoring pack)

Hooks (installed via packs — essentials)

  • routing — route commands to appropriate mode
  • git context — inject git state on every prompt
  • project overview — inject project summary
  • acronym expander — expand domain acronyms
  • ast-grep-awareness (advanced-code-refactoring pack)

Scripts

  • .zcc/scripts/mode-switch.sh — Bash script for fuzzy mode matching

CLI subcommands (zcc)

  • zcc init [--pack <name>] [--force]
  • zcc source add <name> --type github --owner <org> --repo <repo>
  • zcc search <query>
  • zcc add pack <name>
  • zcc ticket list
  • zcc ticket create <title>
  • zcc ticket move <id> <status>

MCP servers

None.

Skills

None (ZCC uses "modes" not SKILL.md format).

05

Prompts

Prompts — ZCC

Verbatim excerpt 1 — .claude/commands/zcc.md (the /zcc status command)

---
allowed-tools: Bash(npx zcc ticket list), Bash(ls:.zcc/modes/), Bash(ls:.zcc/workflows/), Bash(head:CLAUDE.md)
description: Show current zcc project status
---
# zcc Status

## Active Tickets
!`npx zcc ticket list 2>/dev/null || echo "No tickets found"`

## Available Modes
!`ls -1 .zcc/modes/ 2>/dev/null | head -10 || echo "No modes installed"`

## Available Workflows  
!`ls -1 .zcc/workflows/ 2>/dev/null | head -10 || echo "No workflows installed"`

## Current Configuration
!`head -20 CLAUDE.md 2>/dev/null || echo "CLAUDE.md not found"`

Prompting technique: Shell-execution-in-prompt. The ! prefix executes bash commands inline and injects their output into the prompt context. This is the Claude Code "dynamic context injection" pattern — the command bootstraps itself with live filesystem state before Claude even reads the message.

Verbatim excerpt 2 — .claude/commands/mode.md (the /mode switch command)

---
allowed-tools: Bash(sh .zcc/scripts/mode-switch.sh:*)
argument-hint: [mode-name]
description: List available modes or switch to a specific mode
---
!`sh .zcc/scripts/mode-switch.sh $ARGUMENTS`

I'll now operate according to the selected mode.

Prompting technique: External script delegation + argument passthrough. The entire mode-switching logic is in mode-switch.sh (fuzzy matching). The prompt itself is minimal — two lines. The $ARGUMENTS passthrough and ! execution make this an imperative script-dispatch command. "I'll now operate according to the selected mode" is the only natural-language instruction to Claude, telling it to adopt the mode persona output by the script.

09

Uniqueness

Uniqueness — ZCC

differs_from_seeds

Most similar to spec-kit (CLI binary, command structure, hook lifecycle) but ZCC's key innovation is the "mode" system — swappable AI personality templates loaded dynamically from .zcc/modes/ files. Spec-kit has static command/skill mirroring; ZCC has a theme-switcher metaphor. Against superpowers (skills-only), ZCC uses modes + commands + hooks. The ticket system for persistent cross-session task tracking has no direct counterpart in any seed — it addresses the context-compaction loop problem differently from ccmemory (graph DB) or taskmaster-ai (tasks.json MCP).

Positioning

"oh-my-zsh for Claude Code." The positioning is clear and memorable. The community pack registry (zcc source add) creates a potential ecosystem effect similar to oh-my-zsh plugin community — though as of 2025-09-13 this appears nascent (17 stars, dormant).

Observable failure modes

  • Dormant: last commit 2025-09-13 (about 8 months old). Community pack ecosystem did not materialize.
  • Mode file format unclear: .zcc/modes/ files are presumably markdown persona definitions but no formal schema is documented in accessible README content.
  • Only 3 slash commands: very thin command surface compared to the rich feature set implied by the README.
  • npm package age: v1.1.0 with no recent updates while Claude Code itself has evolved rapidly.

Cross-references

No explicit references to seeds. The ZCF (UfoMiao) repo in this batch is superficially similar (also "ZC" prefix, also CLI binary) but architecturally distinct — ZCF focuses on BMAD + provider config, ZCC focuses on the mode/ticket metaphor.

04

Workflow

Workflow — ZCC

Phases

Phase Description Artifact
Install npx zcc init --pack essentials .zcc/, .claude/commands/, CLAUDE.md
Mode select /mode architect Mode loaded into session context
Create ticket /ticket create "Add auth" .zcc/tickets/<id>.md
Implement Work with Claude in selected mode Code changes
Track /ticket move <id> in-progress Updated ticket status
Review /mode reviewer + review session Review output
Close /ticket close <id> Closed ticket

Daily workflow example (from README)

# Morning
/mode architect → "Design the payment system"

# Afternoon
/mode engineer → "Implement stripe integration"

# Evening
/mode reviewer → "Check for security issues"

# Status
/ticket list
/ticket payment-system  ← loads full ticket context

Approval gates

None explicit. ZCC is interactive-loop; the ticket system is the persistence mechanism, not a gating mechanism.

Pack install workflow

npx zcc init                    # interactive pack selection
npx zcc init --pack essentials  # headless pack install
06

Memory Context

Memory & Context — ZCC

State storage

File-based in .zcc/ directory.

Ticket persistence

.zcc/tickets/<id>.md — each ticket is a markdown file with status, description, and history. Tickets persist across sessions and can be loaded with /ticket <id> to restore full context.

Mode state

.zcc/modes/<name>.md — mode definitions loaded at /mode invocation.

Context injection (via hooks)

  • git context hook: injects git status on every prompt
  • project overview hook: injects project summary These run as precmd-style hooks that prepend context to every Claude interaction.

Compaction handling

The ticket system is designed to solve the "goes in circles after context compacting" problem by providing a stable reference point (/ticket <id>) that can be loaded after compaction.

Cross-session handoff

Yes. Tickets survive session boundaries. /ticket <id> loads the full ticket context for resumption.

07

Orchestration

Orchestration — ZCC

Multi-agent

Partial. The advanced-code-refactoring pack ships a code-archaeologist agent, suggesting agent support exists in the framework, but the core is single-agent.

Orchestration pattern

Sequential. Mode switches change the behavioral context; no parallel fan-out.

Isolation mechanism

None.

Multi-model

No.

Execution mode

Interactive-loop. The mode + ticket system is designed for sustained multi-session work, not one-shot invocations.

Consensus mechanism

None.

Prompt chaining

The mode → ticket → workflow pipeline creates implicit chaining where mode selection affects how subsequent commands are processed, but this is contextual, not explicit output-as-prompt chaining.

08

Ui Cli Surface

UI/CLI Surface — ZCC

Dedicated CLI binary

Yes. zcc (dist/cli.js, published to npm as z-claude-code).

Subcommands

  • zcc init [--pack <name>] [--force]
  • zcc source add
  • zcc search
  • zcc add pack
  • zcc ticket list/create/move/close

Local web dashboard

None.

IDE integration

Claude Code only. The /mode, /ticket, /zcc commands are Claude Code slash commands.

Observability

  • /zcc command provides live project status dashboard (in-terminal, via bash command execution)
  • Ticket files in .zcc/tickets/ are human-readable markdown

Community pack registry

External pack sources via zcc source add — a community-driven extension mechanism analogous to oh-my-zsh's plugin registry.

Related frameworks

same archetype · same primary tool · same memory type

MemPalace ★ 53k
A10 Memory engine

Verbatim local-first AI memory with 96.6% R@5 retrieval on LongMemEval using zero API calls — structured into a palace hierarchy…

Beads (Yegge) ★ 24k
A10 Memory engine

Dolt-powered distributed graph issue tracker where AI agents track tasks with hierarchical IDs and dependency edges, claim work…

deepagents (LangChain) ★ 23k
A10 Memory engine

Opinionated Python agent harness on top of LangGraph with sub-agents, filesystem, memory, and context compaction bundled in

agentmemory ★ 18k
A10 Memory engine

Persistent, searchable memory for AI coding agents that captures every tool interaction, compresses it via LLM, and injects…

Open Multi-Agent ★ 6.3k
A10 Memory engine

Give a natural-language goal to a coordinator agent and get a dynamically decomposed, parallelized task DAG executed by…

Basic Memory ★ 3.1k
A10 Memory engine

Gives AI agents a persistent, human-readable knowledge graph of project decisions, observations, and relations stored as plain…