How affaan-m/everything-claude-code works
1. What this repo is
- This is a cross-harness configuration and automation platform for AI coding tools, not a product app. Its core job is to package and deploy “agent harness” behavior: agents, skills, commands, hooks, rules, MCP configs, and install scripts for Claude Code, Cursor, Codex, OpenCode, Gemini, and related environments.
2. Primary surface layers
- The repo is organized around four user-facing surfaces:
- agents/ for specialized subagents
- skills/ for reusable workflows and domain knowledge
- commands/ plus legacy-command-shims/ for slash-command compatibility
- rules/ for always-on guidance, split into common and language-specific packs
- These are the main architectural building blocks an installation copies or mounts into a target harness.
3. Installation and packaging pipeline
- The installation system is manifest-driven and target-aware. manifests/, schemas/, and scripts/lib/install-* define what gets installed, where it lands, and how updates/uninstalls are tracked.
- install.sh, install.ps1, and scripts/ecc.js are the main entry points for applying those manifests to different targets.
- The repo also carries plugin metadata in .claude-plugin/, .codex-plugin/, .opencode/, and .cursor/ so the same content can be projected into each tool’s native config shape.
4. Runtime orchestration and hooks
- Behavior enforcement happens through hooks/ and scripts/hooks/, which implement session lifecycle, edit-time checks, formatting, typecheck triggers, security checks, and compaction suggestions.
- The flow is event-driven: harness event → hook dispatcher/adaptor → shared script logic → side effects such as warnings, formatting, audits, or session-state capture.
- Cursor is a notable special case: .cursor/hooks/adapter.js translates Cursor’s event payloads into the shared hook runtime, so the same enforcement logic can be reused across harnesses.
5. Session, memory, and continuous learning
- The repo has a session-management subsystem centered in scripts/lib/session-*, scripts/lib/state-store, and related CLI commands like /sessions, /instinct-*, and /learn-*.
- Data flow here is: session events and observations → store/adapters → state store / instinct artifacts → later reuse through skills or prompts.
- The newer “continuous-learning-v2” path is more structured and confidence-based, while the older continuous-learning/ path remains as a legacy Stop-hook pattern extractor.
6. Tooling and model-agnostic workflows
- skills/ contains the repository’s actual workflow logic: TDD, verification loops, security review, deep research, content generation, market research, and many language/framework-specific patterns.
- commands/ mainly preserve command-first compatibility; the README explicitly positions skills as the canonical workflow surface.
- Agent routing is intentionally model- and harness-agnostic at the repo level; the same skill/agent content is adapted into Claude Code, Codex, OpenCode, and Cursor-specific formats as needed.
7. MCP and external integrations
- mcp-configs/ and scripts/lib/mcp-config.js manage bundled Model Context Protocol server definitions.
- The repo treats MCPs as optional context-expanding dependencies, with explicit guidance to keep the set small to avoid token bloat.
- The main external services materially shaping architecture are Claude Code, Anthropic marketplace/plugin distribution, GitHub Marketplace, Context7, Exa, Playwright, Supabase, and other MCP-backed services referenced in configs and docs.
8. Cross-harness adapters and targets
- Different harnesses receive different projections of the same canonical content:
- Claude Code: plugin/install + hooks + commands + skills + rules
- Cursor: .cursor/ layout with hook adapter and YAML rules
- Codex: AGENTS.md, .codex/, and sync scripts
- OpenCode: .opencode/ plugin/instruction surface
- The architecture is therefore “canonical source, multiple deploy targets,” not separate implementations per tool.
9. Stateful operational tooling
- scripts/lib/orchestration-*, scripts/orchestrate-*, scripts/loop-*, and commands/multi-* support multi-agent and multi-worktree workflows.
- These features connect planning, execution, and verification across several parallel contexts, often using tmux/worktrees or external workflow runtimes such as ccg-workflow.
- This is the repo’s concurrency/orchestration layer, distinct from the simpler single-session commands.
10. ECC 2.0 alpha control plane
- ecc2/ is a separate Rust prototype for a local control plane. Its modules split into config, comms, notifications, observability, session management, TUI, and worktree handling.
- The visible runtime commands in the README suggest a future daemon-oriented architecture: dashboard, start, sessions, status, stop, resume, daemon.
- The Rust tree is currently an alpha alongside the main Node/Python tooling, not a replacement for it.
11. Dashboard and operator UI
- ecc_dashboard.py provides a Tkinter desktop dashboard for browsing agents, skills, commands, rules, and settings.
- This is a read/inspect/operator interface rather than the core execution engine; it visualizes the same catalog and install surface exposed elsewhere in the repo.
12. Quality gates and CI
- The test suite under tests/ is broad and architecture-relevant: it validates manifests, hooks, install behavior, command docs, plugin surfaces, and cross-tool compatibility.
- GitHub Actions in .github/workflows/ enforce release, validation, and maintenance workflows; the scripts under scripts/ci/ are the main static and structural gates.
- In practice, the CI layer protects the repo’s central invariant: every declared surface must remain installable, discoverable, and consistent across harness targets.
13. Documentation as a delivery surface
- The repo’s docs are not incidental; they are part of the product architecture. README.md, docs/, multilingual translations, release notes, and architecture guides explain how the install/runtime surfaces should behave.
- Many docs describe target-specific behavior and installation constraints, especially around plugin limitations, rules copying, hook duplication, and cross-harness parity.
- For a diagram, treat documentation as the control plane for configuration and adoption, not just reference material.
Main entry points: hooks Hooks runtime · skills Skills · commands Commands · tests CI tests
Components 24
Canonical content
The source catalog of reusable agent behavior and guidance.
Packaging
Manifest-driven installation and target projection.
- Manifests · Component, module, and profile install definitions.
manifests - Schemas · JSON schema contracts for install, hooks, plugins, and state.
schemas - Install scripts · Core install executor, lifecycle, and target resolution logic.
scripts/lib/install-executor.js - Install entry · Primary shell entry points for applying manifests.
install.sh - ECC CLI · Node entry point for install, orchestration, and state operations.
scripts/ecc.js
Runtime control
Hooks, session state, and learning loops that enforce behavior.
- Hooks runtime · Dispatcher and shared hook logic for edit, shell, session, and compaction events.
scripts/hooks - Cursor adapter · Translates Cursor hook payloads into the shared hook runtime.
.cursor/hooks/adapter.js - Session learning · Session adapters, state store, instincts, and continuous learning artifacts.
scripts/lib/state-store/index.js
Deploy targets
Tool-specific projections of the same canonical content.
- MCP configs · Bundled MCP server definitions and merge logic.
mcp-configs/mcp-servers.json - Claude plugin · Claude Code plugin and harness projection surface.
.claude-plugin/plugin.json - Cursor surface · Cursor rules, skills, and hooks projection surface.
.cursor/hooks.json - Codex surface · Codex AGENTS and config projection surface.
.codex/AGENTS.md - OpenCode surface · OpenCode commands, prompts, tools, and plugin projection surface.
.opencode/opencode.json
Operations
Multi-session orchestration and alpha control-plane runtime.
- Orchestration · Multi-agent, multi-worktree, and loop-based execution helpers.
scripts/lib/orchestration-session.js - ECC2 · Alpha Rust control plane for daemon, session, TUI, and worktree management.
ecc2/src/main.rs - Dashboard · Desktop/operator view over catalog, install, and settings.
ecc_dashboard.py
Quality and docs
Validation, CI, and documentation that govern the platform.
Other components
- Repo · Cross-harness agent configuration and automation platform.
Connections 31
- Repo → Agents: contains · Canonical agent catalog.
- Repo → Skills: contains · Canonical skill catalog.
- Repo → Commands: contains · Command compatibility surface.
- Repo → Rules: contains · Always-on guidance packs.
- Repo → Manifests: drives · Manifest-driven install planning.
- Repo → Schemas: defines · Contracts for install and runtime artifacts.
- Manifests → Install scripts: consumed by · Installer executes manifest definitions.
- Install entry → Install scripts: invokes · Shell entry applies install logic.
- ECC CLI → Install scripts: invokes · Node entry reuses installer core.
- Hooks runtime → Session learning: captures · Hooks feed session and instinct state.
- Cursor adapter → Hooks runtime: adapts into · Cursor-specific event payload translation.
- MCP configs → Hooks runtime: augments · MCP health and execution hooks.
- Agents → Claude plugin: projects to · Claude Code plugin surface.
- Skills → Claude plugin: projects to · Claude Code skill packaging.
- Commands → Claude plugin: projects to · Claude Code command surface.
- Rules → Cursor surface: projects to · Cursor rule packs and files.
- Skills → Cursor surface: projects to · Cursor skill projection.
- Commands → Codex surface: projects to · Codex AGENTS and config surface.
- Skills → OpenCode surface: projects to · OpenCode skill prompts and commands.
- Commands → OpenCode surface: projects to · OpenCode command surface.
- Orchestration → Hooks runtime: coordinates · Loop and workflow helpers trigger hook-backed checks.
- Orchestration → ECC2: aligns with · Future daemon-oriented control plane.
- Dashboard → Agents: inspects · Catalog browsing UI.
- Dashboard → Skills: inspects · Skill browsing UI.
- CI tests → Manifests: validates · Install manifest correctness.
- CI tests → Hooks runtime: validates · Hook behavior and parity.
- CI tests → Claude plugin: validates · Plugin surface integrity.
- Workflows → CI tests: runs · Repository automation gates.
- Docs → Install entry: documents · Installation and target behavior.
- Docs → Hooks runtime: documents · Hook contracts and limitations.
- Docs → Session learning: documents · Session and learning workflows.