{
  "markdown": "# meta-cc\n\n[![CI](https://github.com/yaleh/meta-cc/actions/workflows/ci.yml/badge.svg)](https://github.com/yaleh/meta-cc/actions)\n[![License](https://img.shields.io/github/license/yaleh/meta-cc)](LICENSE)\n[![Release](https://img.shields.io/github/v/release/yaleh/meta-cc)](https://github.com/yaleh/meta-cc/releases)\n[![Go Version](https://img.shields.io/github/go-mod/go-version/yaleh/meta-cc)](go.mod)\n[![Host Support](https://img.shields.io/badge/Hosts-Claude_Code%20%2B%20Codex-blue)](https://github.com/yaleh/meta-cc)\n\n**Meta-cognition tool for Claude Code and Codex** - Analyze session history, detect patterns, optimize workflows. 16 MCP tools.\n\n> **Note**: Skills and agents from previous versions have been moved to [yaleh/baime](https://github.com/yaleh/baime). meta-cc 3.0.0 focuses exclusively on session history analysis via MCP tools.\n\n---\n\n## What is meta-cc?\n\nmeta-cc helps you understand and improve your Claude Code and Codex workflows through:\n\n- **Autonomous analysis** - Claude Code or Codex can query session data via MCP tools\n- **16 MCP tools** - Error analysis, quality scanning, work patterns, timelines, bug detection, edit sequence analysis, and more\n- **Prompt library** - Save, search, and reuse optimized prompts with Claude Code slash commands or Codex skills\n\n**Native host integrations** - Claude Code marketplace/archive support plus Codex plugin and skills packaging.\n\n---\n\n## Quick Install\n\n### Method 1: Claude Code Plugin Marketplace (Recommended for Claude Code)\n\n```bash\n/plugin marketplace add yaleh/meta-cc\n/plugin install meta-cc\n```\n\nRestart Claude Code. The MCP server is automatically configured via `.mcp.json` bundled in the plugin.\n\nThe meta-cc plugin includes:\n- **3 Slash Commands** - `/prompt-find`, `/prompt-list`, `/prompt-show` for prompt library management\n- **16 MCP Tools** - Session data analysis with consolidated query and two-stage architecture\n\n### Method 2: Archive Install (Claude Code + Codex)\n\n**Full install** (MCP server + Claude Code commands + Codex skills):\n\n```bash\n# Linux/macOS (one-liner)\ncurl -L https://github.com/yaleh/meta-cc/releases/latest/download/meta-cc-plugin-linux-amd64.tar.gz | tar xz\ncd meta-cc-plugin-linux-amd64\n./install.sh\n```\n\nThe archive installer copies the binary and integration files, installs Claude Code commands under `~/.claude/commands/`, installs Codex skills under `~/.codex/skills/`, and merges the Claude Code MCP server configuration into `~/.claude/mcp.json`. Codex users get plugin metadata under `~/.codex/plugins/meta-cc/` with bundled `.codex-plugin/plugin.json` and `.codex-mcp.json`.\n\n**Prompt-library commands/skills only** (no binary required, any platform):\n\n```bash\ncurl -L https://github.com/yaleh/meta-cc/releases/latest/download/meta-cc-skills-latest.tar.gz | tar xz\ncd meta-cc-skills-*/\n./install-skills.sh\n```\n\nUse `INSTALL_CLAUDE=0` or `INSTALL_CODEX=0` to install one host only.\n\n### Method 3: Codex Plugin Marketplace (Recommended for Codex CLI 0.145+)\n\n```bash\ncodex plugin marketplace add .   # from an extracted release archive, or a git checkout of this repo\ncodex plugin add meta-cc@meta-cc-marketplace\n```\n\nVerify with `codex plugin list --json` and `codex mcp list` (expect exactly\none `meta-cc` entry), then **start a new Codex session** — a running\nsession cannot hot-load a plugin installed after it started. For the\nminimal MCP-only fallback (`codex mcp add`), upgrade/uninstall flows, and\ntroubleshooting duplicate registrations, see\n[Installation Guide: Method 1b](docs/tutorials/installation.md#method-1b-codex-plugin-marketplace-preferred-for-codex-cli-0145).\n\n**MCP server binary only** (for CI/Docker/PATH installs):\n\n```bash\n# Download the bare binary for your platform, e.g. Linux amd64:\ncurl -LO https://github.com/yaleh/meta-cc/releases/latest/download/meta-cc-mcp-linux-amd64\nchmod +x meta-cc-mcp-linux-amd64\nINSTALL_DIR=~/.local/bin bash scripts/install/install-mcp.sh meta-cc-mcp-linux-amd64\n```\n\n**Other platforms**: See [Installation Guide](docs/tutorials/installation.md) for macOS (Apple Silicon), Windows, and manual installation.\n\n### Verify Installation\n\nIn Claude Code or Codex, ask naturally:\n\n```\n\"Show me all Bash errors in this project\"\n\"Which tools do I use most often?\"\n\"Find user messages mentioning 'refactor'\"\n```\n\n**Troubleshooting**: See [Installation Guide](docs/tutorials/installation.md#troubleshooting) for common issues.\n\n---\n\n## Quick Start\n\n### Autonomous Analysis (MCP)\n\nAsk Claude Code or Codex naturally - MCP tools are invoked automatically:\n\n```\n\"Show me all Bash errors in this project\"\n\"Find user messages mentioning 'refactor'\"\n\"Which tools do I use most often?\"\n\"Scan session quality and show me scores\"\n\"Show my work patterns and peak hours\"\n\"Find bug fix pairs in my session\"\n```\n\n**16 MCP tools: consolidated query tools, two-stage jq, and analysis tools**:\n\n```javascript\n// Session discovery - metadata-first: list sessions without loading turn content\nquery_sessions({limit: 10})                              // what sessions exist in this project\n// Discovery-to-content: target one discovered session by exact ID\nquery_session_content({role: \"user\", session_id: \"<id from query_sessions>\"})\n\n// Consolidated query tools - cover the most common access patterns\nquery_session_signals({type: \"errors\", limit: 10})       // tool execution errors\nquery_session_signals({type: \"tokens\", stats_first: true}) // token usage stats\nquery_session_content({role: \"user\", pattern: \"refactor\"}) // user messages\nquery_session_content({role: \"tool\", block_type: \"tool_use\"}) // tool calls with context\nquery_file_activity({type: \"snapshots\"})                  // file history\n\n// Two-stage jq - maximum flexibility for power users\nconst dir = get_session_directory({scope: \"project\"})\nexecute_stage2_query({\n  files: dir.files,\n  filter: 'select(.type == \"assistant\")',\n  transform: '{timestamp, usage: .message.usage}'\n})\n\n// Analysis tools - aggregate and detect patterns\nanalyze_errors({})          // Aggregate errors by tool and type; result includes data_source field\nquality_scan({})            // Compute error/retry/diversity scores\nget_work_patterns({})       // Hourly activity and context switches\nget_timeline({})            // Chronological session events\nanalyze_bugs({})            // Error-fix pairs and recurring patterns\nget_tech_debt({})           // TODO/FIXME markers and unresolved errors\nquery_edit_sequences({files: [\"/path/to/file.go\"]})  // File edit/read patterns, docRole, co-accessed docs\nget_session_metadata({})    // JSONL schema, file info, and query templates\n```\n\n**Key Features**:\n- **Claude Code + Codex support**: Reads Claude transcripts from `~/.claude/projects/` and Codex conversations from the highest-compatible `state_N.sqlite` under the canonical Codex root (`META_CC_CODEX_ROOT` → `CODEX_HOME` → `~/.codex`) plus rollout JSONL files, with a rollout-only fallback when no compatible database exists\n- **Provider-aware normalization**: Use `provider: \"claude\" | \"codex\" | \"all\"` on query and analysis tools; omitted `provider` resolves to the host that launched the MCP server (`claude` for standalone installs). Codex `response_item`, `event_msg`, function/custom tool calls, tool outputs, and token counts are normalized through the same MCP surface\n- **Hybrid Output Mode**: Auto-switches between inline (<8KB) and file_ref (≥8KB); can override with `output_mode` parameter\n- **jq Integration**: Native jq filtering for complex queries; warns when a transform produces all-null results\n- **Time Filtering**: `since`/`until` (RFC3339) on all `query_session_content` roles, all `query_session_signals` types, and `get_timeline`; `query_sessions` filters with `created_since`/`created_until`\n- **No Limits by Default**: Returns all results, relies on hybrid mode\n- **data_source field**: All six analysis tools label results as `measured` (from session data) or `estimated` so callers know data provenance\n- **16 Tools**: 1 session discovery + 3 consolidated query + 5 two-stage (directory/inspect/stage2/metadata/edit-sequences) + 6 analysis + 1 cleanup\n\n**Resources**:\n- [MCP Query Tools Reference](docs/guides/mcp-query-tools.md) - Complete tool documentation (authoritative query reference)\n- [Two-Stage Query Guide](docs/guides/two-stage-query-guide.md) - Custom jq workflows over selected session files\n- [Codex History Model](docs/reference/codex-history-model.md) - Codex provider reference (lineage, archiving, pagination)\n- [Codex App-Server Backend](docs/reference/codex-app-server.md) - Codex history backend modes (`auto`/`app_server`/`files`)\n- [Local FTS Index](docs/reference/fts-index.md) - Internal index that accelerates project content queries (no standalone tool)\n\n### Prompt Library (Slash Commands / Codex Skills)\n\nSave and reuse your best prompts with 3 built-in Claude Code slash commands or Codex skills:\n\n```bash\n/prompt-find phase execution      # Search by keywords\n/prompt-list sort=usage           # Browse all (sorted by use)\n/prompt-show phase-execution-001  # View full prompt details\n```\n\n---\n\n## Documentation\n\n### Getting Started\n\n- **[Installation Guide](docs/tutorials/installation.md)** - Detailed setup for all platforms\n- **[Quick Start Tutorial](docs/tutorials/examples.md)** - Step-by-step examples\n- **[Troubleshooting](docs/guides/troubleshooting.md)** - Common issues and solutions\n\n### Integration\n\n- **[MCP Guide](docs/guides/mcp.md)** - Complete MCP tool reference (16 tools)\n- **[Integration Guide](docs/guides/integration.md)** - MCP and Slash Commands\n- **[MCP Query Tools Reference](docs/guides/mcp-query-tools.md)** - Consolidated query tools, two-stage jq, hybrid output\n- **[Two-Stage Query Guide](docs/guides/two-stage-query-guide.md)** - File selection plus custom jq\n\n### Advanced\n\n- **[JSONL Reference](docs/reference/jsonl.md)** - Output format and jq patterns\n- **[Feature Overview](docs/reference/features.md)** - Advanced features and capabilities\n- **[Codex History Model](docs/reference/codex-history-model.md)** - Codex lineage, archives, pagination\n- **[Codex App-Server Backend](docs/reference/codex-app-server.md)** - Codex backend modes and fallback\n- **[Local FTS Index](docs/reference/fts-index.md)** - Internal query-acceleration index (DIR-031)\n\n### Development\n\n- **[Contributing Guide](CONTRIBUTING.md)** - Development workflow and guidelines\n- **[Code of Conduct](CODE_OF_CONDUCT.md)** - Community standards\n\n### Host Notes\n\n- **[CLAUDE.md](CLAUDE.md)** - Project instructions for Claude Code development\n- **[Design Principles](docs/core/principles.md)** - Core constraints and architecture\n- **[Implementation Plan](docs/core/plan.md)** - Development roadmap\n- Codex integration uses `plugin-src/.codex-plugin/plugin.json`, `plugin-src/.codex-mcp.json`, and `plugin-src/skills/*/SKILL.md`\n\n**Complete documentation map**: [DOCUMENTATION_MAP.md](docs/DOCUMENTATION_MAP.md)\n\n---\n\n## Key Features\n\n- **16 MCP tools** - Autonomous session data analysis: 1 session discovery + 3 consolidated query + 5 two-stage + 6 analysis + 1 cleanup\n- **Claude Code + Codex transcript analysis** - Shared query/analysis surface over both host schemas\n- **3 Prompt Library commands/skills** - Prompt management (`prompt-find`, `prompt-list`, `prompt-show`)\n- **Advanced analytics** - jq-based filtering, aggregation, time series; `since`/`until` time filtering on all query and signal paths + `get_timeline`\n- **Error analysis** - Aggregate tool errors by name and type, with `data_source` provenance field\n- **Quality scanning** - Error/retry/diversity/completion dimensions\n- **Work pattern detection** - Tool frequency, hourly activity, context switches\n- **Timeline visualization** - Chronological session events as JSON\n- **Bug detection** - Error-fix pairs and recurring patterns\n- **Tech debt tracking** - TODO/FIXME markers and unresolved errors\n- **Edit sequence analysis** - File edit/read patterns, docRole classification, co-accessed document detection\n- **File operation tracking** - Identify hotspots and churn\n- **No external runtime dependencies** - Single binary MCP server\n- **Prompt Learning System** - Save, search, and reuse optimized prompts with project-specific intelligence\n\n---\n\n## Development\n\n### Prerequisites\n\n- Go 1.24 or later (matches the `go` directive in `go.mod`)\n- make\n\n### Build from Source\n\n```bash\ngit clone https://github.com/yaleh/meta-cc.git\ncd meta-cc\nmake build\n```\n\n### Development Workflow (3-Tier)\n\nUse the optimized 3-tier workflow for efficient development:\n\n```bash\nmake dev           # Quick dev build (format + build, <10s)\nmake commit        # Pre-commit validation (workspace + tests, <60s)\nmake push          # Full check before push (all checks + lint, <120s)\n```\n\n**Workflow**:\n1. **Iterate**: Use `make dev` for fast feedback during development\n2. **Commit**: Run `make commit` to validate before committing\n3. **Push**: Run `make push` for full verification before pushing to remote\n\n### Run Tests\n\n```bash\nmake test           # Unit tests (fast)\nmake test-e2e-codex # Codex install/session E2E\nmake test-all       # Including MCP and Codex E2E tests (~30s)\nmake test-coverage  # With coverage report\n```\n\n**Coverage Requirement**: Maintain ≥80% test coverage for all code changes.\n\n---\n\n## Platform Support\n\n- Linux (amd64, arm64)\n- macOS (Intel, Apple Silicon)\n- Windows (amd64)\n\n---\n\n## Contributing\n\nWe welcome contributions! Please see:\n\n- **[Contributing Guide](CONTRIBUTING.md)** - Development process and guidelines\n- **[Code of Conduct](CODE_OF_CONDUCT.md)** - Community standards\n\n---\n\n## License\n\nMIT License - See [LICENSE](LICENSE) file for details.\n",
  "bytes": 13613,
  "sha": "4e9da83d1d84a9254bbb3c25394654909f8da00d66f39707984f9f36eddcd390",
  "repo_slug": "yaleh/meta-cc",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_yaleh_meta_cc_claude_skills_methodology__a47cf52c/readme"
}